fix(docs): complete apidocs for migrations

Co-Authored-By: Knut Melvær <[email protected]>

packages/@sanity/migrate/src/defineMigration.ts

@@ -1,5 +1,29 @@
 import {type Migration} from './types'
 
+/**
+ * Helper function for defining a Sanity content migration. This function does not do anything on its own;
+ * it exists to check that your schema definition is correct, and help autocompletion in your IDE.
+ *
+ * @see https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6
+
+ * ### Basic usage
+ *
+ * ```ts
+ * export default defineMigration({
+ *  title: 'Make sure all strings with “acme” is uppercased to “ACME”',
+ *  migrate: {
+ *    string(node, path, context) {
+ *      if (node === "acme") {
+ *        return set(node.toUpperCase())
+ *      }
+ *    },
+ *  },
+ * })
+ * ```
+ * @param migration - The migration definition
+ *
+ * See {@link Migration}
+ */
 export function defineMigration<T extends Migration>(migration: T): T {
   return migration
 }

packages/@sanity/migrate/src/mutations/creators.ts

@@ -19,7 +19,7 @@ import {type NormalizeReadOnlyArray, type Optional, type Tuplify} from './typeUt
 /**
  * Creates a new document.
  * @param document - The document to be created.
- * @returns The mutation operation to create the document.
+ * @returns The mutation to create the document.
  * @beta
  */
 export function create<Doc extends Optional<SanityDocument, '_id'>>(
@@ -30,10 +30,10 @@ export function create<Doc extends Optional<SanityDocument, '_id'>>(
 
 /**
  * Applies a patch to a document.
- * @param id - The id of the document to be patched.
+ * @param id - The ID of the document to be patched.
  * @param patches - The patches to be applied.
  * @param options - Optional patch options.
- * @returns The mutation operation to patch the document.
+ * @returns The mutation to patch the document.
  * @beta
  */
 export function patch<P extends NodePatchList | NodePatch>(
@@ -50,7 +50,7 @@ export function patch<P extends NodePatchList | NodePatch>(
 }
 
 /**
- * Creates a node patch at a specific path.
+ * Creates a {@link NodePatch} at a specific path.
  * @param path - The path where the operation should be applied.
  * @param operation - The operation to be applied.
  * @returns The node patch.
@@ -98,6 +98,6 @@ export function delete_(id: string): DeleteMutation {
 }
 
 /**
- * Alias for delete_
+ * Alias for delete
  */
 export const del = delete_

packages/@sanity/migrate/src/mutations/operations/creators.ts

@@ -22,6 +22,12 @@ import {
  * @returns A `set` operation.
  * {@link https://www.sanity.io/docs/http-patches#6TPENSW3}
  * @beta
+ *
+ * ### Examples
+ * ```ts
+ * const setFoo = set('foo')
+ * const setEmptyArray = set([])
+ * ```
  */
 export const set = <const T>(value: T): SetOp<T> => ({type: 'set', value})
 
@@ -31,6 +37,11 @@ export const set = <const T>(value: T): SetOp<T> => ({type: 'set', value})
  * @returns A `setIfMissing` operation.
  * {@link https://www.sanity.io/docs/http-patches#A80781bT}
  * @beta
+ * ### Examples
+ * ```ts
+ * const setFooIfMissing = setIfMissing('foo')
+ * const setEmptyArrayIfMissing = setIfMissing([])
+ * ```
  */
 export const setIfMissing = <const T>(value: T): SetIfMissingOp<T> => ({
   type: 'setIfMissing',
@@ -42,15 +53,26 @@ export const setIfMissing = <const T>(value: T): SetIfMissingOp<T> => ({
  * @returns An `unset` operation.
  * {@link https://www.sanity.io/docs/http-patches#xRtBjp8o}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const unsetAnyValue = unset()
+ * ```
  */
 export const unset = (): UnsetOp => ({type: 'unset'})
 
 /**
  * Creates an `inc` (increment) operation with the provided amount.
  * @param amount - The amount to increment by.
- * @returns An `inc` operation.
+ * @returns An incrementation operation for numeric values
  * {@link https://www.sanity.io/docs/http-patches#vIT8WWQo}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const incBy1 = inc()
+ * const incBy5 = inc(5)
+ * ```
  */
 export const inc = <const N extends number = 1>(amount: N = 1 as N): IncOp<N> => ({
   type: 'inc',
@@ -63,6 +85,12 @@ export const inc = <const N extends number = 1>(amount: N = 1 as N): IncOp<N> =>
  * @returns A `dec` operation.
  * {@link https://www.sanity.io/docs/http-patches#vIT8WWQo}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const decBy1 = dec()
+ * const decBy10 = dec(10)
+ * ```
  */
 export const dec = <const N extends number = 1>(amount: N = 1 as N): DecOp<N> => ({
   type: 'dec',
@@ -74,7 +102,7 @@ export const dec = <const N extends number = 1>(amount: N = 1 as N): DecOp<N> =>
  * @param value - The value for the diff match patch operation.
  * @returns A `diffMatchPatch` operation.
  * {@link https://www.sanity.io/docs/http-patches#aTbJhlAJ}
- * @beta
+ *
  */
 export const diffMatchPatch = (value: string): DiffMatchPatchOp => ({
   type: 'diffMatchPatch',
@@ -86,9 +114,16 @@ export const diffMatchPatch = (value: string): DiffMatchPatchOp => ({
  * @param items - The items to insert.
  * @param position - The position to insert at.
  * @param indexOrReferenceItem - The index or reference item to insert before or after.
- * @returns An `insert` operation.
+ * @returns An `insert` operation for adding values to arrays
  * {@link https://www.sanity.io/docs/http-patches#febxf6Fk}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const prependFoo = insert(['foo'], 'before')
+ * const appendFooAndBar = insert(['foo', 'bar'], 'after')
+ * const insertObjAfterXYZ = insert({name: 'foo'}, 'after', {_key: 'xyz'}])
+ * ```
  */
 export function insert<
   const Items extends AnyArray<unknown>,
@@ -113,6 +148,13 @@ export function insert<
  * @returns An `insert` operation at the end of the array.
  * {@link https://www.sanity.io/docs/http-patches#Cw4vhD88}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const appendFoo = append('foo')
+ * const appendObject = append({name: 'foo'})
+ * const appendObjects = append([{name: 'foo'}, [{name: 'bar'}]])
+ * ```
  */
 export function append<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
   return insert(items, 'after', -1)
@@ -124,6 +166,13 @@ export function append<const Items extends AnyArray<unknown>>(items: Items | Arr
  * @returns An `insert` operation at the beginning of the array.
  * {@link https://www.sanity.io/docs/http-patches#refAUsf0}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const prependFoo = prepend('foo')
+ * const prependObject = prepend({name: 'foo'})
+ * const prependObjects = prepend([{name: 'foo'}, [{name: 'bar'}]])
+ * ```
  */
 export function prepend<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
   return insert(items, 'before', 0)
@@ -135,6 +184,12 @@ export function prepend<const Items extends AnyArray<unknown>>(items: Items | Ar
  * @param indexOrReferenceItem - The index or reference item to insert before.
  * @returns An `insert` operation before the provided index or reference item.
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
+ *
+ * ### Example
+ * ```ts
+ * const insertFooBeforeIndex3 = insertBefore('foo', 3)
+ * const insertObjectBeforeKey = insertBefore({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
 export function insertBefore<
   const Items extends AnyArray<unknown>,
@@ -150,6 +205,12 @@ export function insertBefore<
  * @returns An `insert` operation after the provided index or reference item.
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const insertFooAfterIndex3 = insertAfter('foo', 3)
+ * const insertObjectAfterKey = insertAfter({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
 export const insertAfter = <
   const Items extends AnyArray<unknown>,
@@ -169,6 +230,13 @@ export const insertAfter = <
  * @remarks - This will be converted to an `unset` patch when submitted to the API
  * {@link https://www.sanity.io/docs/http-patches#xRtBjp8o}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const clearArray = truncate(0)
+ * const removeItems = truncate(3, 5) // Removes items at index 3, 4, and 5
+ * const truncate200 = truncate(200) // Removes all items after index 200
+ * ```
  */
 export function truncate(startIndex: number, endIndex?: number): TruncateOp {
   return {
@@ -186,6 +254,13 @@ export function truncate(startIndex: number, endIndex?: number): TruncateOp {
  * @remarks This will be converted to an `insert`/`replace` patch when submitted to the API
  * {@link https://www.sanity.io/docs/http-patches#GnVSwcPa}
  * @beta
+ *
+ * ### Example
+ * ```ts
+ * const replaceItem3WithFoo = replace('foo', 3)
+ * const replaceItem3WithFooAndBar = replace(['foo', 'bar'], 3)
+ * const replaceObject = replace({name: 'bar'}, {_key: 'xyz'})
+ * ```
  */
 export function replace<Items extends any[], ReferenceItem extends IndexedSegment | KeyedSegment>(
   items: Items | ArrayElement<Items>,

packages/@sanity/migrate/src/mutations/operations/types.ts

@@ -2,36 +2,60 @@ import {type KeyedSegment} from '@sanity/types'
 
 import {type AnyArray} from '../typeUtils'
 
+/**
+ * Represents an indexed segment in a document.
+ */
 type IndexedSegment = number
 
 export type {IndexedSegment, KeyedSegment}
 
+/**
+ * Represents a set-operation that can be applied to any value
+ */
 export type SetOp<T> = {
   type: 'set'
   value: T
 }
 
+/**
+ * Represents an unset operation that can be applied to any value
+ */
 export type UnsetOp = {
   type: 'unset'
 }
 
+/**
+ * Represents a setIfMissing operation that can be applied to any value
+ */
 export type SetIfMissingOp<T> = {
   type: 'setIfMissing'
   value: T
 }
 
+/**
+ * Represents a increment-operation that can be applied to a number
+ */
 export type IncOp<Amount extends number> = {
   type: 'inc'
   amount: Amount
 }
 
+/**
+ * Represents a decrement-operation that can be applied to a number
+ */
 export type DecOp<Amount extends number> = {
   type: 'dec'
   amount: Amount
 }
 
+/**
+ * Represents a relative position in a document.
+ */
 export type RelativePosition = 'before' | 'after'
 
+/**
+ * Represents an insert-operation that can be applied to an array
+ */
 export type InsertOp<
   Items extends AnyArray,
   Pos extends RelativePosition,
@@ -43,11 +67,18 @@ export type InsertOp<
   items: Items
 }
 
+/**
+ * Represents a truncate-operation that can be applied to an array
+ */
 export type TruncateOp = {
   type: 'truncate'
   startIndex: number
   endIndex?: number
 }
+
+/**
+ * Represents a replace-operation that can be applied to an array
+ */
 export type ReplaceOp<
   Items extends AnyArray,
   ReferenceItem extends IndexedSegment | KeyedSegment,
@@ -56,42 +87,44 @@ export type ReplaceOp<
   referenceItem: ReferenceItem
   items: Items
 }
-export type UpsertOp<
-  Items extends AnyArray,
-  Pos extends RelativePosition,
-  ReferenceItem extends IndexedSegment | KeyedSegment,
-> = {
-  type: 'upsert'
-  items: Items
-  referenceItem: ReferenceItem
-  position: Pos
-}
-
-export type AssignOp<T extends object = object> = {
-  type: 'assign'
-  value: T
-}
-
-export type UnassignOp<K extends readonly string[] = readonly string[]> = {
-  type: 'unassign'
-  keys: K
-}
 
+/**
+ * Represents a diffMatchPatch operation that can be applied to a string
+ */
 export type DiffMatchPatchOp = {
   type: 'diffMatchPatch'
   value: string
 }
 
-export type Operation = PrimitiveOp | ArrayOp | ObjectOp
+/**
+ * Represents an operation that can be applied to values of all types
+ */
+export type Operation = PrimitiveOp | ArrayOp
 
+/**
+ * Represents an operation that can be applied to values of all types
+ */
 export type AnyOp = SetOp<unknown> | SetIfMissingOp<unknown> | UnsetOp
+
+/**
+ * Represents an operation that can be applied to a number
+ */
 export type NumberOp = IncOp<number> | DecOp<number>
+
+/**
+ * Represents an operation that can be applied to a string
+ */
 export type StringOp = DiffMatchPatchOp
-export type ObjectOp = AssignOp | UnassignOp
+
+/**
+ * Represents ann operation that can be applied to an array
+ */
 export type ArrayOp =
   | InsertOp<AnyArray, RelativePosition, IndexedSegment | KeyedSegment>
-  | UpsertOp<AnyArray, RelativePosition, IndexedSegment | KeyedSegment>
   | ReplaceOp<AnyArray, IndexedSegment | KeyedSegment>
   | TruncateOp
 
+/**
+ * Represents an operation that can be applied to any primitive value
+ */
 export type PrimitiveOp = AnyOp | StringOp | NumberOp