Add popArray for mutating non-empty arrays

Author: steida

.changeset/afraid-wolves-lay.md

@@ -0,0 +1,7 @@
+---
+"@evolu/common": minor
+---
+
+Add `popArray` function for removing and returning the last element from a non-empty mutable array.
+
+This complements the existing `shiftArray` function by providing symmetric mutable operations for both ends of arrays. The function ensures type safety by only accepting mutable non-empty arrays and guaranteeing a return value.

packages/common/src/Array.ts

@@ -1,5 +1,5 @@
 /**
- * Array types, type guards, operations, transformations, accessors, and
+ * Array types, type guards, operations, transformations, accessors, and (rare)
  * mutations
  *
  * ### Example
@@ -414,3 +414,20 @@ export const lastInArray = <T>(array: NonEmptyReadonlyArray<T>): T =>
  * @category Mutations
  */
 export const shiftArray = <T>(array: NonEmptyArray<T>): T => array.shift() as T;
+
+/**
+ * Pops an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * popArray(arr); // 3
+ * arr; // [1, 2]
+ * ```
+ *
+ * @category Mutations
+ */
+export const popArray = <T>(array: NonEmptyArray<T>): T => array.pop() as T;

packages/common/test/Array.test.ts

@@ -9,6 +9,7 @@ import {
   lastInArray,
   mapArray,
   partitionArray,
+  popArray,
   prependToArray,
   shiftArray,
   type NonEmptyArray,
@@ -398,4 +399,38 @@ describe("Mutations", () => {
       shiftArray([1, 2, 3] as NonEmptyReadonlyArray<number>);
     });
   });
+
+  describe("popArray", () => {
+    test("pops last element from array", () => {
+      const arr: NonEmptyArray<number> = [1, 2, 3];
+      const result = popArray(arr);
+      expect(result).toBe(3);
+      expect(arr).toEqual([1, 2]);
+    });
+
+    test("pops from single element array", () => {
+      const arr: NonEmptyArray<number> = [42];
+      const result = popArray(arr);
+      expect(result).toBe(42);
+      expect(arr).toEqual([]);
+    });
+
+    test("mutates the original array", () => {
+      const arr: NonEmptyArray<string> = ["a", "b", "c"];
+      popArray(arr);
+      expect(arr).toEqual(["a", "b"]);
+    });
+
+    test("only accepts mutable arrays", () => {
+      const mutableArr: NonEmptyArray<number> = [1, 2, 3];
+      const result = popArray(mutableArr);
+      expect(result).toBe(3);
+      expect(mutableArr).toEqual([1, 2]);
+      expectTypeOf(result).toEqualTypeOf<number>();
+
+      // Verify readonly arrays are NOT accepted by TypeScript
+      // @ts-expect-error - readonly arrays cannot be mutated
+      popArray([1, 2, 3] as NonEmptyReadonlyArray<number>);
+    });
+  });
 });