feat: add support for array remove operation (#19)

* feat: add support for array remove operation

* fix: improve typings for remove operation

examples/ts/apply-patch-mutation.ts

@@ -7,6 +7,7 @@ import {
   insertBefore,
   patch,
   prepend,
+  remove,
   setIfMissing,
   unassign,
   unset,
@@ -17,6 +18,7 @@ const document = {
   _id: 'test',
   _type: 'foo',
   unsetme: 'yes',
+  someArray: [{_key: 'foo'}, {_key: 'bar'}],
   unassignme: 'please',
   assigned: {existing: 'prop'},
 } as const
@@ -30,6 +32,7 @@ const patches = patch('test', [
   at('cities', insertAfter(['Chicago'], 1)),
   at('cities', insertBefore(['Raleigh'], 3)),
   at('unsetme', unset()),
+  at('someArray', remove({_key: 'foo'})),
   at([], unassign(['unassignme'])),
   at('hmmm', assign({other: 'value'})),
 ])

examples/web/lib/mutate-formatter/react/components/FormatPatchMutation.tsx

@@ -125,6 +125,13 @@ function FormatOp(props: {op: Operation}) {
       </Text>
     )
   }
+  if (op.type === 'remove') {
+    return (
+      <Text size={1} weight="semibold">
+        {op.type} ({formatReferenceItem(op.referenceItem)}))
+      </Text>
+    )
+  }
   // @ts-expect-error all cases are covered
   throw new Error(`Invalid operation type: ${op.type}`)
 }

src/apply/patch/__test__/array.test.ts

@@ -1,6 +1,6 @@
 import {expect, test} from 'vitest'
 
-import {insert, replace} from '../../../mutations/operations/creators'
+import {insert, remove, replace} from '../../../mutations/operations/creators'
 import {applyOp} from '../applyOp'
 
 test('replace on item', () => {
@@ -151,3 +151,37 @@ test('insert relative to nonexisting keyed path elements', () => {
     applyOp(insert(['INSERT!'], 'after', {_key: 'foo'}), []),
   ).toThrow()
 })
+
+test('remove item at key', () => {
+  expect(
+    applyOp(remove({_key: 'foo'}), [
+      {_key: 'one'},
+      {_key: 'foo'},
+      {_key: 'two'},
+    ]),
+  ).toEqual([{_key: 'one'}, {_key: 'two'}])
+
+  expect(
+    applyOp(remove({_key: 'foo'}), [{_key: 'foo'}, {_key: 'two'}]),
+  ).toEqual([{_key: 'two'}])
+  expect(
+    applyOp(remove({_key: 'foo'}), [{_key: 'one'}, {_key: 'foo'}]),
+  ).toEqual([{_key: 'one'}])
+
+  expect(applyOp(remove({_key: 'foo'}), [{_key: 'foo'}])).toEqual([])
+})
+
+test('remove item at index', () => {
+  expect(
+    applyOp(remove(1), [{_key: 'one'}, {_key: 'foo'}, {_key: 'two'}]),
+  ).toEqual([{_key: 'one'}, {_key: 'two'}])
+
+  expect(applyOp(remove(0), [{_key: 'foo'}, {_key: 'two'}])).toEqual([
+    {_key: 'two'},
+  ])
+  expect(applyOp(remove(1), [{_key: 'one'}, {_key: 'foo'}])).toEqual([
+    {_key: 'one'},
+  ])
+
+  expect(applyOp(remove(0), [{_key: 'foo'}])).toEqual([])
+})

src/apply/patch/operations/array.ts

@@ -2,6 +2,7 @@ import {
   type InsertOp,
   type KeyedPathElement,
   type RelativePosition,
+  type RemoveOp,
   type ReplaceOp,
   type TruncateOp,
   type UpsertOp,
@@ -87,6 +88,20 @@ export function replace<
   }
   return splice(currentValue, index, op.items.length, op.items)
 }
+export function remove<
+  O extends RemoveOp<number | KeyedPathElement>,
+  CurrentValue extends unknown[],
+>(op: O, currentValue: CurrentValue) {
+  if (!Array.isArray(currentValue)) {
+    throw new TypeError('Cannot apply "remove()" on non-array value')
+  }
+
+  const index = findTargetIndex(currentValue, op.referenceItem)
+  if (index === null) {
+    throw new Error(`Found no matching array element to replace`)
+  }
+  return splice(currentValue, index, 1, [])
+}
 
 export function truncate<O extends TruncateOp, CurrentValue extends unknown[]>(
   op: O,

src/apply/patch/typings/applyOp.ts

@@ -8,6 +8,7 @@ import {
   type InsertOp,
   type KeyedPathElement,
   type Operation,
+  type RemoveOp,
   type ReplaceOp,
   type SetIfMissingOp,
   type SetOp,
@@ -88,6 +89,36 @@ export type InsertAtIndex<
   NormalizeIndex<Index, ArrayLength<Current>>
 >
 
+export type DropFirst<Array extends unknown[]> = Array extends [
+  infer Head,
+  ...infer Rest,
+]
+  ? Rest
+  : []
+
+export type _RemoveAtIndex<Current extends unknown[], Index extends number> =
+  Between<Index, 0, ArrayLength<Current>> extends true
+    ? Call<Tuples.SplitAt<Index>, Current> extends [infer Head, infer Tail]
+      ? Head extends AnyArray
+        ? Tail extends AnyArray
+          ? [
+              ...(Head extends never[] ? [] : Head),
+              ...(Tail extends never[]
+                ? []
+                : Tail extends unknown[]
+                  ? DropFirst<Tail>
+                  : Tail),
+            ]
+          : never
+        : never
+      : never
+    : Current
+
+export type RemoveAtIndex<
+  Current extends unknown[],
+  Index extends number,
+> = _RemoveAtIndex<Current, NormalizeIndex<Index, ArrayLength<Current>>>
+
 export type ArrayInsert<
   Current extends unknown[],
   Items extends unknown[],
@@ -101,6 +132,16 @@ export type ArrayInsert<
       : (E | ArrayElement<Items>)[]
   : Current
 
+export type ArrayRemove<
+  Current extends unknown[],
+  Ref extends number | KeyedPathElement,
+> = number extends Ref
+  ? Current
+  : Ref extends number
+    ? RemoveAtIndex<Current, Ref>
+    : // todo: look up index of item with _key
+      Current
+
 export type Assign<Current, Attrs> = {
   [K in keyof Attrs | keyof Current]: K extends keyof Attrs
     ? Attrs[K]
@@ -155,4 +196,9 @@ export type ApplyOp<O extends Operation, Current> = Current extends never
                       }
                     : O extends DiffMatchPatchOp
                       ? string
-                      : never
+                      : O extends RemoveOp<infer Ref>
+                        ? Current extends AnyArray<unknown>
+                          ? ArrayRemove<NormalizeReadOnlyArray<Current>, Ref>
+                          : Current
+                        : // fallback
+                          Current

src/encoders/compact/encode.ts

@@ -105,6 +105,9 @@ function encodePatchMutation(
   if (op.type === 'truncate') {
     return ['patch', 'truncate', id, path, [op.startIndex, op.endIndex]]
   }
+  if (op.type === 'remove') {
+    return ['patch', 'remove', id, path, [encodeItemRef(op.referenceItem)]]
+  }
   // @ts-expect-error all cases are covered
   throw new Error(`Invalid operation type: ${op.type}`)
 }

src/encoders/compact/types.ts

@@ -86,6 +86,14 @@ export type ReplaceMutation = [
   [ItemRef, AnyArray],
   RevisionLock?,
 ]
+export type RemoveMutation = [
+  'patch',
+  'remove',
+  Id,
+  CompactPath,
+  [ItemRef],
+  RevisionLock?,
+]
 export type SetMutation = ['patch', 'set', Id, CompactPath, any, RevisionLock?]
 export type SetIfMissingMutation = [
   'patch',
@@ -118,6 +126,7 @@ export type CompactPatchMutation =
   | AssignMutation
   | UnassignMutation
   | ReplaceMutation
+  | RemoveMutation
 
 export type CompactMutation<Doc> =
   | DeleteMutation

src/encoders/sanity/encode.ts

@@ -113,6 +113,11 @@ function patchToSanity(patch: NodePatch) {
       },
     }
   }
+  if (op.type === 'remove') {
+    return {
+      unset: [stringifyPath(path.concat(op.referenceItem))],
+    }
+  }
   //@ts-expect-error all cases should be covered
   throw new Error(`Unknown operation type ${op.type}`)
 }

src/formatters/compact.ts

@@ -90,6 +90,9 @@ function formatPatchMutation(patch: NodePatch<any>): string {
   if (op.type === 'truncate') {
     return [path, `truncate(${op.startIndex}, ${op.endIndex}`].join(': ')
   }
+  if (op.type === 'remove') {
+    return [path, `remove(${encodeItemRef(op.referenceItem)})`].join(': ')
+  }
   // @ts-expect-error all cases are covered
   throw new Error(`Invalid operation type: ${op.type}`)
 }

src/mutations/operations/creators.ts

@@ -13,6 +13,7 @@ import {
   type InsertOp,
   type KeyedPathElement,
   type RelativePosition,
+  type RemoveOp,
   type ReplaceOp,
   type SetIfMissingOp,
   type SetOp,
@@ -135,6 +136,18 @@ export function replace<
   }
 }
 
+/*
+  Remove an item from an array by either key or index
+ */
+export function remove<ReferenceItem extends Index | KeyedPathElement>(
+  referenceItem: ReferenceItem,
+): RemoveOp<ReferenceItem> {
+  return {
+    type: 'remove',
+    referenceItem,
+  }
+}
+
 /*
 use this when the reference Items may or may not exist
  */

src/mutations/operations/types.ts

@@ -45,6 +45,12 @@ export type TruncateOp = {
   startIndex: number
   endIndex?: number
 }
+
+export type RemoveOp<ReferenceItem extends Index | KeyedPathElement> = {
+  type: 'remove'
+  referenceItem: ReferenceItem
+}
+
 export type ReplaceOp<
   Items extends AnyArray,
   ReferenceItem extends Index | KeyedPathElement,
@@ -90,5 +96,6 @@ export type ArrayOp =
   | UpsertOp<AnyArray, RelativePosition, Index | KeyedPathElement>
   | ReplaceOp<AnyArray, Index | KeyedPathElement>
   | TruncateOp
+  | RemoveOp<Index | KeyedPathElement>
 
 export type PrimitiveOp = AnyOp | StringOp | NumberOp