@sanity/migrate - npm Package Compare versions

Comparing version 3.30.0 to 3.30.1-cds-unstable.30

lib/dts/src/_exports/index.d.ts

@@ -23,4 +23,14 @@ import {KeyedSegment} from '@sanity/types'
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to values of all types
+ */
 export declare type AnyOp = SetOp<unknown> | SetIfMissingOp<unknown> | UnsetOp
 
+/**
+ * API configuration for the migration runner
+ * @internal
+ * @hidden
+ */
 export declare interface APIConfig {
@@ -37,5 +47,12 @@ projectId: string
  * @param items - The items to append.
- * @returns An `insert` operation at the end of the array.
+ * @returns An `insert` operation for adding a value to the end of an 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'}]])
+ * ```
  */
@@ -48,13 +65,12 @@ export declare function append<const Items extends AnyArray<unknown>>(
 
+/**
+ * @public
+ *
+ * Represents ann operation that can be applied to an array
+ */
 export declare type ArrayOp =
   | InsertOp<AnyArray, RelativePosition, IndexedSegment | KeyedSegment>
-  | UpsertOp<AnyArray, RelativePosition, IndexedSegment | KeyedSegment>
   | ReplaceOp<AnyArray, IndexedSegment | KeyedSegment>
   | TruncateOp
 
-export declare type AssignOp<T extends object = object> = {
-  type: 'assign'
-  value: T
-}
-
 export declare type AsyncIterableMigration = (
@@ -66,3 +82,3 @@ documents: () => AsyncIterableIterator<SanityDocument_2>,
 /**
- * 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.
@@ -87,3 +103,3 @@ * @param operation - The operation to be applied.
  * @param document - The document to be created.
- * @returns The mutation operation to create the document.
+ * @returns The mutation to create the document.
  * @beta
@@ -105,2 +121,7 @@ */
 
+/**
+ * @public
+ *
+ * Represents a mutation that can create a new document in the Sanity Content Lake if its ID does not exist.
+ */
 export declare type CreateIfNotExistsMutation<Doc extends SanityDocument> = {
@@ -111,2 +132,7 @@ type: 'createIfNotExists'
 
+/**
+ * @public
+ *
+ * Represents a mutation that creates a new document in the Sanity Content Lake. This mutation will fail if the ID already exist.
+ */
 export declare type CreateMutation<Doc extends Optional<SanityDocument, '_id'>> = {
@@ -127,2 +153,7 @@ type: 'create'
 
+/**
+ * @public
+ *
+ * Represents a mutation that can create or replace a document in the Sanity Content Lake given its ID.
+ */
 export declare type CreateOrReplaceMutation<Doc extends SanityDocument> = {
@@ -139,2 +170,8 @@ type: 'createOrReplace'
  * @beta
+ *
+ * @example
+ * ```ts
+ * const decBy1 = dec()
+ * const decBy10 = dec(10)
+ * ```
  */
@@ -147,2 +184,7 @@ export declare const dec: <const N extends number = 1>(amount?: N) => DecOp<N>
 
+/**
+ * @public
+ *
+ * Represents a decrement-operation that can be applied to a number
+ */
 export declare type DecOp<Amount extends number> = {
@@ -155,6 +197,32 @@ type: 'dec'
 
+/**
+ * @public
+ *
+ * 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.
+ *
+ * {@link https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6}
+
+ * @example 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 declare function defineMigration<T extends Migration>(migration: T): T
 
 /**
- * Alias for delete_
+ * Alias for delete
  */
@@ -176,2 +244,7 @@ export declare const del: typeof delete_
 
+/**
+ * @public
+ *
+ * Represents a mutation that can delete a document in the Sanity Content Lake.
+ */
 export declare type DeleteMutation = {
@@ -187,6 +260,12 @@ type: 'delete'
  * {@link https://www.sanity.io/docs/http-patches#aTbJhlAJ}
- * @beta
+ * @public
  */
 export declare const diffMatchPatch: (value: string) => DiffMatchPatchOp
 
+/**
+ * @public
+ *
+ * Represents a diff-match-patch operation that can be applied to a string
+ * {@link https://www.npmjs.com/package/@sanity/diff-match-patch}
+ */
 export declare type DiffMatchPatchOp = {
@@ -197,2 +276,8 @@ type: 'diffMatchPatch'
 
+/**
+ * @public
+ *
+ * Possible return values from a migration helper that runs on a document as a whole
+ * Currently, this is only applies to {@link NodeMigration.document}
+ */
 export declare type DocumentMigrationReturnValue =
@@ -211,2 +296,7 @@ | Mutation
 
+/**
+ * API configuration for exports
+ * @internal
+ * @hidden
+ */
 export declare interface ExportAPIConfig extends APIConfig {
@@ -239,8 +329,19 @@ documentTypes?: string[]
  * @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 declare const inc: <const N extends number = 1>(amount?: N) => IncOp<N>
 
+/**
+ * @public
+ *
+ * Represents an increment-operation that can be applied to a number
+ */
 export declare type IncOp<Amount extends number> = {
@@ -251,2 +352,7 @@ type: 'inc'
 
+/**
+ * @public
+ *
+ * Represents an indexed segment in a document.
+ */
 export declare type IndexedSegment = number
@@ -259,5 +365,12 @@
  * @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'}])
+ * ```
  */
@@ -281,2 +394,8 @@ export declare function insert<
  * @beta
+ *
+ * @example
+ * ```ts
+ * const insertFooAfterIndex3 = insertAfter('foo', 3)
+ * const insertObjectAfterKey = insertAfter({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
@@ -297,2 +416,9 @@ export declare const insertAfter: <
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
+ * @public
+ *
+ * @example
+ * ```ts
+ * const insertFooBeforeIndex3 = insertBefore('foo', 3)
+ * const insertObjectBeforeKey = insertBefore({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
@@ -307,2 +433,7 @@ export declare function insertBefore<
 
+/**
+ * @public
+ *
+ * Represents an insert-operation that can be applied to an array
+ */
 export declare type InsertOp<
@@ -346,20 +477,41 @@ Items extends AnyArray,
 
+/**
+ * @public
+ *
+ * Interface for `Migration['migrate']`. Either a NodeMigration or an AsyncIterableMigration
+ * {@link NodeMigration}
+ * {@link AsyncIterableMigration}
+ */
 export declare type MigrateDefinition = NodeMigration | AsyncIterableMigration
 
+/**
+ * @public
+ *
+ * Main interface for a content migration definition
+ * {@link https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6}
+ */
 export declare interface Migration<Def extends MigrateDefinition = MigrateDefinition> {
   /**
-   * The title of the migration
+   * A reader-friendly description of what the content migration does
    */
   title: string
   /**
-   * What document types to use in the migration
+   * An array of document types to run the content migration on. If you don’t define this, the migration type will target all document types.
+   * Note: This reflects the document types your migration will be based on, not necessarily the documents you will modify.
    */
   documentTypes?: string[]
   /**
-   * What document types to use in the migration
+   * A simple GROQ-filter (doesn’t support joins) for documents you want to run the content migration on.
+   * Note: instead of adding `_type == 'yourType'` to the filter, it's better to add its `_type` to `documentTypes`.
+   * Note: `documentTypes` and `filter` are combined with AND. This means a document will only be included in the
+   * migration if its `_type` matches any of the provided `documentTypes` AND it also matches the `filter` (if provided).
    */
   filter?: string
   /**
-   * The actual migration. This can be either a function that returns an async iterable, or an object with hooks for different node types.
-   * Currently only "json"-type hooks are supported
+   * An object of named helper functions corresponding to the primary schema type of the content you want to migrate.
+   * You can also run these functions as async and return the migration instructions as promises if you need to fetch data from elsewhere.
+   * If you want more control, `migrate` can also be an async iterable function that yields mutations or transactions.
+   * {@link NodeMigration}
+   * {@link AsyncIterableMigration}
+   *
    */
@@ -369,2 +521,7 @@ migrate: Def
 
+/**
+ * @public
+ *
+ * Migration context. This will be passed to both async iterable migrations and node migration helper functions
+ */
 export declare interface MigrationContext {
@@ -378,2 +535,7 @@ client: RestrictedClient
 
+/**
+ * Migration progress, only used internally (for now)
+ * @internal
+ * @hidden
+ */
 export declare type MigrationProgress = {
@@ -400,2 +562,7 @@ documents: number
 
+/**
+ * @public
+ *
+ * Represents a mutation that can be applied to a document in the Sanity Content Lake.
+ */
 export declare type Mutation<Doc extends SanityDocument = any> =
@@ -408,3 +575,13 @@ | CreateMutation<Doc>
 
+/**
+ * @public
+ *
+ * Node migration helper functions. As the migration is processing a document, it will visit each node in the document, depth-first, call the appropriate helper function for the node type and collect any mutations returned from it.
+ */
 export declare interface NodeMigration {
+  /**
+   * Helper function for migrating a document as a whole
+   * @param doc - The document currently being processed
+   * @param context - The {@link MigrationContext} instance
+   */
   document?: <Doc extends SanityDocument_2>(
@@ -418,2 +595,8 @@ doc: Doc,
     | Promise<DocumentMigrationReturnValue | Transaction>
+  /**
+   * Helper function that will be called for each node in each document included in the migration
+   * @param node - The node currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   node?: <Node extends JsonValue>(
@@ -424,2 +607,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each object in each document included in the migration
+   * @param object - The object value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   object?: <Node extends JsonObject>(
@@ -430,2 +619,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each array in each document included in the migration
+   * @param object - The object value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   array?: <Node extends JsonArray>(
@@ -436,2 +631,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each string in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   string?: <Node extends string>(
@@ -442,2 +643,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each number in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   number?: <Node extends number>(
@@ -448,2 +655,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each boolean value in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   boolean?: <Node extends boolean>(
@@ -454,2 +667,8 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+  /**
+   * Helper function that will be called for each `null` value in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   null?: <Node extends null>(
@@ -462,2 +681,7 @@ node: Node,
 
+/**
+ * @public
+ *
+ * Possible return values from a migration helper that runs on nodes within a document
+ */
 export declare type NodeMigrationReturnValue =
@@ -468,2 +692,7 @@ | DocumentMigrationReturnValue
 
+/**
+ * @public
+ *
+ * A NodePatch represents a single operation that can be applied at a node at a specific path in a Sanity document.
+ */
 export declare type NodePatch<P extends Path = Path, O extends Operation = Operation> = {
@@ -474,2 +703,7 @@ path: P
 
+/**
+ * @public
+ *
+ * A list of {@link NodePatch} objects.
+ */
 export declare type NodePatchList =
@@ -487,8 +721,16 @@ | [NodePatch, ...NodePatch[]]
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to a number
+ */
 export declare type NumberOp = IncOp<number> | DecOp<number>
 
-export declare type ObjectOp = AssignOp | UnassignOp
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to values of all types
+ */
+export declare type Operation = PrimitiveOp | ArrayOp
 
-export declare type Operation = PrimitiveOp | ArrayOp | ObjectOp
-
 declare type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
@@ -508,6 +750,6 @@
  * 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
@@ -521,2 +763,7 @@ */
 
+/**
+ * @public
+ *
+ * Represents a patch mutation that can change a value for a document in the Sanity Content Lake.
+ */
 export declare type PatchMutation<Patches extends NodePatchList = NodePatchList> = {
@@ -529,3 +776,11 @@ type: 'patch'
 
+/**
+ * @public
+ *
+ * Options for a patch operation.
+ */
 export declare type PatchOptions = {
+  /**
+   * {@link https://www.sanity.io/docs/http-mutations#26600a871378}
+   */
   ifRevision?: string
@@ -539,5 +794,12 @@ }
  * @param items - The items to prepend.
- * @returns An `insert` operation at the beginning of the array.
+ * @returns An `insert` operation for adding a value to the start of an 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'}]])
+ * ```
  */
@@ -548,4 +810,14 @@ export declare function prepend<const Items extends AnyArray<unknown>>(
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to any primitive value
+ */
 export declare type PrimitiveOp = AnyOp | StringOp | NumberOp
 
+/**
+ * @public
+ *
+ * Represents a relative position in a document.
+ */
 export declare type RelativePosition = 'before' | 'after'
@@ -561,2 +833,9 @@
  * @beta
+ *
+ * @example
+ * ```ts
+ * const replaceItem3WithFoo = replace('foo', 3)
+ * const replaceItem3WithFooAndBar = replace(['foo', 'bar'], 3)
+ * const replaceObject = replace({name: 'bar'}, {_key: 'xyz'})
+ * ```
  */
@@ -568,2 +847,7 @@ export declare function replace<
 
+/**
+ * @public
+ *
+ * Represents a replace-operation that can be applied to an array
+ */
 export declare type ReplaceOp<
@@ -592,2 +876,7 @@ Items extends AnyArray,
 
+/**
+ * @public
+ *
+ * A Sanity Content Lake document
+ */
 export declare type SanityDocument = {
@@ -607,2 +896,8 @@ _id?: string
  * @beta
+ *
+ * @example
+ * ```ts
+ * const setFoo = set('foo')
+ * const setEmptyArray = set([])
+ * ```
  */
@@ -617,5 +912,15 @@ export declare const set: <const T>(value: T) => SetOp<T>
  * @beta
+ * @example
+ * ```ts
+ * const setFooIfMissing = setIfMissing('foo')
+ * const setEmptyArrayIfMissing = setIfMissing([])
+ * ```
  */
 export declare const setIfMissing: <const T>(value: T) => SetIfMissingOp<T>
 
+/**
+ * @public
+ *
+ * Represents a setIfMissing operation that can be applied to any value
+ */
 export declare type SetIfMissingOp<T> = {
@@ -626,2 +931,7 @@ type: 'setIfMissing'
 
+/**
+ * @public
+ *
+ * Represents a set-operation that can be applied to any value
+ */
 export declare type SetOp<T> = {
@@ -645,2 +955,7 @@ type: 'set'
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to a string
+ */
 export declare type StringOp = DiffMatchPatchOp
@@ -666,3 +981,14 @@
 
-export declare function transaction(id: string, mutations: Mutation[]): Transaction
+/**
+ * @public
+ *
+ * Wraps a set of mutations in a transaction.
+ * Note: use with caution. Transactions cannot be optimized and will be submitted one-by-one, which means they will make
+ * your migration run slower and produce more API requests.
+ * @param transactionId - The transaction ID. This is optional and should usually be omitted, as it will be auto-generated by the server if not provided.
+ * @param mutations - The mutations to include in the transaction.
+ *
+ * {@link https://www.sanity.io/docs/http-mutations#afccc1b9ef78}
+ */
+export declare function transaction(transactionId: string, mutations: Mutation[]): Transaction
 
@@ -684,5 +1010,17 @@ export declare function transaction(mutations: Mutation[]): Transaction
  * @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 declare function truncate(startIndex: number, endIndex?: number): TruncateOp
 
+/**
+ * @public
+ *
+ * Represents a truncate-operation that can be applied to an array
+ */
 export declare type TruncateOp = {
@@ -700,7 +1038,2 @@ type: 'truncate'
 
-export declare type UnassignOp<K extends readonly string[] = readonly string[]> = {
-  type: 'unassign'
-  keys: K
-}
-
 /**
@@ -711,5 +1044,15 @@ * Creates an `unset` operation.
  * @beta
+ *
+ * @example
+ * ```ts
+ * const unsetAnyValue = unset()
+ * ```
  */
 export declare const unset: () => UnsetOp
 
+/**
+ * @public
+ *
+ * Represents an unset operation that can be applied to any value
+ */
 export declare type UnsetOp = {
@@ -719,13 +1062,2 @@ type: 'unset'
 
-export declare type UpsertOp<
-  Items extends AnyArray,
-  Pos extends RelativePosition,
-  ReferenceItem extends IndexedSegment | KeyedSegment,
-> = {
-  type: 'upsert'
-  items: Items
-  referenceItem: ReferenceItem
-  position: Pos
-}
-
 export {}

package.json

 {
   "name": "@sanity/migrate",
-  "version": "3.30.0",
+  "version": "3.30.1-cds-unstable.30+f3a9c9bb4c",
   "description": "Tooling for running data migrations on Sanity.io projects",
@@ -68,4 +68,4 @@ "keywords": [
     "@sanity/client": "^6.13.3",
-    "@sanity/types": "3.30.0",
-    "@sanity/util": "3.30.0",
+    "@sanity/types": "3.30.1-cds-unstable.30+f3a9c9bb4c",
+    "@sanity/util": "3.30.1-cds-unstable.30+f3a9c9bb4c",
     "arrify": "^2.0.1",
@@ -86,3 +86,3 @@ "debug": "^4.3.4",
   },
-  "gitHead": "c29014a64236b29cc4fbcf5e2c57ca66083bdc43"
+  "gitHead": "f3a9c9bb4cb283f3bd7f8682c9f279a4f6c03648"
 }

src/defineMigration.ts

 import {type Migration} from './types'
 
+/**
+ * @public
+ *
+ * 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.
+ *
+ * {@link https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6}
+
+ * @example 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
 }

src/mutations/creators.ts

@@ -22,3 +22,3 @@ import {type Path} from '@sanity/types'
  * @param document - The document to be created.
- * @returns The mutation operation to create the document.
+ * @returns The mutation to create the document.
  * @beta
@@ -34,6 +34,6 @@ */
  * 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
@@ -55,3 +55,3 @@ */
 /**
- * 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.
@@ -104,4 +104,4 @@ * @param operation - The operation to be applied.
 /**
- * Alias for delete_
+ * Alias for delete
  */
 export const del = delete_

src/mutations/operations/creators.ts

@@ -25,2 +25,8 @@ import arrify from 'arrify'
  * @beta
+ *
+ * @example
+ * ```ts
+ * const setFoo = set('foo')
+ * const setEmptyArray = set([])
+ * ```
  */
@@ -35,2 +41,7 @@ export const set = <const T>(value: T): SetOp<T> => ({type: 'set', value})
  * @beta
+ * @example
+ * ```ts
+ * const setFooIfMissing = setIfMissing('foo')
+ * const setEmptyArrayIfMissing = setIfMissing([])
+ * ```
  */
@@ -47,2 +58,7 @@ export const setIfMissing = <const T>(value: T): SetIfMissingOp<T> => ({
  * @beta
+ *
+ * @example
+ * ```ts
+ * const unsetAnyValue = unset()
+ * ```
  */
@@ -54,5 +70,11 @@ export const unset = (): UnsetOp => ({type: 'unset'})
  * @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)
+ * ```
  */
@@ -70,2 +92,8 @@ export const inc = <const N extends number = 1>(amount: N = 1 as N): IncOp<N> => ({
  * @beta
+ *
+ * @example
+ * ```ts
+ * const decBy1 = dec()
+ * const decBy10 = dec(10)
+ * ```
  */
@@ -82,3 +110,3 @@ export const dec = <const N extends number = 1>(amount: N = 1 as N): DecOp<N> => ({
  * {@link https://www.sanity.io/docs/http-patches#aTbJhlAJ}
- * @beta
+ * @public
  */
@@ -95,5 +123,12 @@ export const diffMatchPatch = (value: string): DiffMatchPatchOp => ({
  * @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'}])
+ * ```
  */
@@ -120,5 +155,12 @@ export function insert<
  * @param items - The items to append.
- * @returns An `insert` operation at the end of the array.
+ * @returns An `insert` operation for adding a value to the end of an 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'}]])
+ * ```
  */
@@ -132,5 +174,12 @@ export function append<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
  * @param items - The items to prepend.
- * @returns An `insert` operation at the beginning of the array.
+ * @returns An `insert` operation for adding a value to the start of an 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'}]])
+ * ```
  */
@@ -147,2 +196,9 @@ export function prepend<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
+ * @public
+ *
+ * @example
+ * ```ts
+ * const insertFooBeforeIndex3 = insertBefore('foo', 3)
+ * const insertObjectBeforeKey = insertBefore({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
@@ -163,2 +219,8 @@ export function insertBefore<
  * @beta
+ *
+ * @example
+ * ```ts
+ * const insertFooAfterIndex3 = insertAfter('foo', 3)
+ * const insertObjectAfterKey = insertAfter({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
@@ -183,2 +245,9 @@ export const insertAfter = <
  * @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
+ * ```
  */
@@ -201,2 +270,9 @@ export function truncate(startIndex: number, endIndex?: number): TruncateOp {
  * @beta
+ *
+ * @example
+ * ```ts
+ * const replaceItem3WithFoo = replace('foo', 3)
+ * const replaceItem3WithFooAndBar = replace(['foo', 'bar'], 3)
+ * const replaceObject = replace({name: 'bar'}, {_key: 'xyz'})
+ * ```
  */
@@ -203,0 +279,0 @@ export function replace<Items extends any[], ReferenceItem extends IndexedSegment | KeyedSegment>(

src/mutations/operations/types.ts

@@ -5,2 +5,7 @@ import {type KeyedSegment} from '@sanity/types'
 
+/**
+ * @public
+ *
+ * Represents an indexed segment in a document.
+ */
 type IndexedSegment = number
@@ -10,2 +15,7 @@
 
+/**
+ * @public
+ *
+ * Represents a set-operation that can be applied to any value
+ */
 export type SetOp<T> = {
@@ -16,2 +26,7 @@ type: 'set'
 
+/**
+ * @public
+ *
+ * Represents an unset operation that can be applied to any value
+ */
 export type UnsetOp = {
@@ -21,2 +36,7 @@ type: 'unset'
 
+/**
+ * @public
+ *
+ * Represents a setIfMissing operation that can be applied to any value
+ */
 export type SetIfMissingOp<T> = {
@@ -27,2 +47,7 @@ type: 'setIfMissing'
 
+/**
+ * @public
+ *
+ * Represents an increment-operation that can be applied to a number
+ */
 export type IncOp<Amount extends number> = {
@@ -33,2 +58,7 @@ type: 'inc'
 
+/**
+ * @public
+ *
+ * Represents a decrement-operation that can be applied to a number
+ */
 export type DecOp<Amount extends number> = {
@@ -39,4 +69,14 @@ type: 'dec'
 
+/**
+ * @public
+ *
+ * Represents a relative position in a document.
+ */
 export type RelativePosition = 'before' | 'after'
 
+/**
+ * @public
+ *
+ * Represents an insert-operation that can be applied to an array
+ */
 export type InsertOp<
@@ -53,2 +93,7 @@ Items extends AnyArray,
 
+/**
+ * @public
+ *
+ * Represents a truncate-operation that can be applied to an array
+ */
 export type TruncateOp = {
@@ -59,2 +104,8 @@ type: 'truncate'
 }
+
+/**
+ * @public
+ *
+ * Represents a replace-operation that can be applied to an array
+ */
 export type ReplaceOp<
@@ -68,23 +119,9 @@ Items extends AnyArray,
 }
-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
-}
-
+/**
+ * @public
+ *
+ * Represents a diff-match-patch operation that can be applied to a string
+ * {@link https://www.npmjs.com/package/@sanity/diff-match-patch}
+ */
 export type DiffMatchPatchOp = {
@@ -95,14 +132,45 @@ type: 'diffMatchPatch'
 
-export type Operation = PrimitiveOp | ArrayOp | ObjectOp
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to values of all types
+ */
+export type Operation = PrimitiveOp | ArrayOp
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to values of all types
+ */
 export type AnyOp = SetOp<unknown> | SetIfMissingOp<unknown> | UnsetOp
+
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to a number
+ */
 export type NumberOp = IncOp<number> | DecOp<number>
+
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to a string
+ */
 export type StringOp = DiffMatchPatchOp
-export type ObjectOp = AssignOp | UnassignOp
+
+/**
+ * @public
+ *
+ * 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
 
+/**
+ * @public
+ *
+ * Represents an operation that can be applied to any primitive value
+ */
 export type PrimitiveOp = AnyOp | StringOp | NumberOp

src/mutations/transaction.ts

@@ -8,3 +8,15 @@ import {type Mutation} from './types'
 }
-export function transaction(id: string, mutations: Mutation[]): Transaction
+
+/**
+ * @public
+ *
+ * Wraps a set of mutations in a transaction.
+ * Note: use with caution. Transactions cannot be optimized and will be submitted one-by-one, which means they will make
+ * your migration run slower and produce more API requests.
+ * @param transactionId - The transaction ID. This is optional and should usually be omitted, as it will be auto-generated by the server if not provided.
+ * @param mutations - The mutations to include in the transaction.
+ *
+ * {@link https://www.sanity.io/docs/http-mutations#afccc1b9ef78}
+ */
+export function transaction(transactionId: string, mutations: Mutation[]): Transaction
 export function transaction(mutations: Mutation[]): Transaction
@@ -11,0 +23,0 @@ export function transaction(

src/mutations/types.ts

@@ -6,2 +6,7 @@ import {type Path} from '@sanity/types'
 
+/**
+ * @public
+ *
+ * A list of {@link NodePatch} objects.
+ */
 export type NodePatchList =
@@ -13,2 +18,7 @@ | [NodePatch, ...NodePatch[]]
 
+/**
+ * @public
+ *
+ * A Sanity Content Lake document
+ */
 export type SanityDocument = {
@@ -22,2 +32,7 @@ _id?: string
 
+/**
+ * @public
+ *
+ * Represents a mutation that creates a new document in the Sanity Content Lake. This mutation will fail if the ID already exist.
+ */
 export type CreateMutation<Doc extends Optional<SanityDocument, '_id'>> = {
@@ -28,2 +43,7 @@ type: 'create'
 
+/**
+ * @public
+ *
+ * Represents a mutation that can create a new document in the Sanity Content Lake if its ID does not exist.
+ */
 export type CreateIfNotExistsMutation<Doc extends SanityDocument> = {
@@ -34,2 +54,7 @@ type: 'createIfNotExists'
 
+/**
+ * @public
+ *
+ * Represents a mutation that can create or replace a document in the Sanity Content Lake given its ID.
+ */
 export type CreateOrReplaceMutation<Doc extends SanityDocument> = {
@@ -40,2 +65,7 @@ type: 'createOrReplace'
 
+/**
+ * @public
+ *
+ * Represents a mutation that can delete a document in the Sanity Content Lake.
+ */
 export type DeleteMutation = {
@@ -46,2 +76,7 @@ type: 'delete'
 
+/**
+ * @public
+ *
+ * Represents a patch mutation that can change a value for a document in the Sanity Content Lake.
+ */
 export type PatchMutation<Patches extends NodePatchList = NodePatchList> = {
@@ -54,2 +89,7 @@ type: 'patch'
 
+/**
+ * @public
+ *
+ * Represents a mutation that can be applied to a document in the Sanity Content Lake.
+ */
 export type Mutation<Doc extends SanityDocument = any> =
@@ -62,2 +102,7 @@ | CreateMutation<Doc>
 
+/**
+ * @public
+ *
+ * A NodePatch represents a single operation that can be applied at a node at a specific path in a Sanity document.
+ */
 export type NodePatch<P extends Path = Path, O extends Operation = Operation> = {
@@ -68,4 +113,12 @@ path: P
 
+/**
+ * @public
+ *
+ * Options for a patch operation.
+ */
 export type PatchOptions = {
+  /**
+   * {@link https://www.sanity.io/docs/http-mutations#26600a871378}
+   */
   ifRevision?: string
 }

src/runner/utils/batchMutations.ts

@@ -17,3 +17,4 @@ import {type Mutation as SanityMutation} from '@sanity/client'
  * @param maxBatchSize - Max batch size in bytes
- * Todo: add support for transaction ids too
+ * @public
+ *
  */
@@ -20,0 +21,0 @@ export async function* batchMutations(

src/types.ts

@@ -16,5 +16,11 @@ import {type MultipleMutationResult, type Mutation as RawMutation} from '@sanity/client'
 
+/**
+ * @public
+ *
+ * Main interface for a content migration definition
+ * {@link https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6}
+ */
 export interface Migration<Def extends MigrateDefinition = MigrateDefinition> {
   /**
-   * The title of the migration
+   * A reader-friendly description of what the content migration does
    */
@@ -24,3 +30,4 @@ title: string
   /**
-   * What document types to use in the migration
+   * An array of document types to run the content migration on. If you don’t define this, the migration type will target all document types.
+   * Note: This reflects the document types your migration will be based on, not necessarily the documents you will modify.
    */
@@ -30,3 +37,6 @@ documentTypes?: string[]
   /**
-   * What document types to use in the migration
+   * A simple GROQ-filter (doesn’t support joins) for documents you want to run the content migration on.
+   * Note: instead of adding `_type == 'yourType'` to the filter, it's better to add its `_type` to `documentTypes`.
+   * Note: `documentTypes` and `filter` are combined with AND. This means a document will only be included in the
+   * migration if its `_type` matches any of the provided `documentTypes` AND it also matches the `filter` (if provided).
    */
@@ -36,4 +46,8 @@ filter?: string
   /**
-   * The actual migration. This can be either a function that returns an async iterable, or an object with hooks for different node types.
-   * Currently only "json"-type hooks are supported
+   * An object of named helper functions corresponding to the primary schema type of the content you want to migrate.
+   * You can also run these functions as async and return the migration instructions as promises if you need to fetch data from elsewhere.
+   * If you want more control, `migrate` can also be an async iterable function that yields mutations or transactions.
+   * {@link NodeMigration}
+   * {@link AsyncIterableMigration}
+   *
    */
@@ -43,4 +57,29 @@ migrate: Def
 
+/**
+ * @public
+ *
+ * Migration context. This will be passed to both async iterable migrations and node migration helper functions
+ */
+export interface MigrationContext {
+  client: RestrictedClient
+  filtered: {
+    getDocument<T extends SanityDocument>(id: string): Promise<T | undefined>
+    getDocuments<T extends SanityDocument>(ids: string[]): Promise<T[]>
+  }
+}
+
+/**
+ * @public
+ *
+ * Interface for `Migration['migrate']`. Either a NodeMigration or an AsyncIterableMigration
+ * {@link NodeMigration}
+ * {@link AsyncIterableMigration}
+ */
 export type MigrateDefinition = NodeMigration | AsyncIterableMigration
 
+/**
+ * Migration progress, only used internally (for now)
+ * @internal
+ * @hidden
+ */
 export type MigrationProgress = {
@@ -56,10 +95,7 @@ documents: number
 
-export interface MigrationContext {
-  client: RestrictedClient
-  filtered: {
-    getDocument<T extends SanityDocument>(id: string): Promise<T | undefined>
-    getDocuments<T extends SanityDocument>(ids: string[]): Promise<T[]>
-  }
-}
-
+/**
+ * API configuration for the migration runner
+ * @internal
+ * @hidden
+ */
 export interface APIConfig {
@@ -73,2 +109,7 @@ projectId: string
 
+/**
+ * API configuration for exports
+ * @internal
+ * @hidden
+ */
 export interface ExportAPIConfig extends APIConfig {
@@ -78,2 +119,8 @@ documentTypes?: string[]
 
+/**
+ * @public
+ *
+ * Possible return values from a migration helper that runs on a document as a whole
+ * Currently, this is only applies to {@link NodeMigration.document}
+ */
 export type DocumentMigrationReturnValue =
@@ -87,5 +134,20 @@ | Mutation
 
+/**
+ * @public
+ *
+ * Possible return values from a migration helper that runs on nodes within a document
+ */
 export type NodeMigrationReturnValue = DocumentMigrationReturnValue | Operation | Operation[]
 
+/**
+ * @public
+ *
+ * Node migration helper functions. As the migration is processing a document, it will visit each node in the document, depth-first, call the appropriate helper function for the node type and collect any mutations returned from it.
+ */
 export interface NodeMigration {
+  /**
+   * Helper function for migrating a document as a whole
+   * @param doc - The document currently being processed
+   * @param context - The {@link MigrationContext} instance
+   */
   document?: <Doc extends SanityDocument>(
@@ -99,2 +161,9 @@ doc: Doc,
     | Promise<DocumentMigrationReturnValue | Transaction>
+
+  /**
+   * Helper function that will be called for each node in each document included in the migration
+   * @param node - The node currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   node?: <Node extends JsonValue>(
@@ -105,2 +174,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each object in each document included in the migration
+   * @param object - The object value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   object?: <Node extends JsonObject>(
@@ -111,2 +187,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each array in each document included in the migration
+   * @param object - The object value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   array?: <Node extends JsonArray>(
@@ -117,2 +200,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each string in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   string?: <Node extends string>(
@@ -123,2 +213,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each number in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   number?: <Node extends number>(
@@ -129,2 +226,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each boolean value in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   boolean?: <Node extends boolean>(
@@ -135,2 +239,9 @@ node: Node,
   ) => void | NodeMigrationReturnValue | Promise<void | NodeMigrationReturnValue>
+
+  /**
+   * Helper function that will be called for each `null` value in each document included in the migration
+   * @param string - The string value currently being visited
+   * @param path - The path to the node within the document. See {@link Path}
+   * @param context - The {@link MigrationContext} instance
+   */
   null?: <Node extends null>(
@@ -137,0 +248,0 @@ node: Node,

New alerts

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

6630282

increased by7.3%

Number of package files

368

increased by318.18%

Lines of code

12519

increased by57.95%

Worsened metrics

Number of low quality alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

5

increased by66.67%

Dependency changes

• - Removed@sanity/types@3.30.0(transitive)

• - Removed@sanity/util@3.30.0(transitive)

• - Removed@types/prop-types@15.7.12(transitive)

• - Removed@types/react@18.3.3(transitive)

• - Removedcsstype@3.1.3(transitive)

• - Removeddom-walk@0.1.2(transitive)

• - Removedget-random-values@1.2.2(transitive)

• - Removedget-random-values-esm@1.0.0(transitive)

• - Removedglobal@4.4.0(transitive)

• - Removedmin-document@2.19.0(transitive)

• - Removedmoment@2.30.1(transitive)

• - Removedprocess@0.11.10(transitive)

• Updated@sanity/types@3.30.1-cds-unstable.30+f3a9c9bb4c

• Updated@sanity/util@3.30.1-cds-unstable.30+f3a9c9bb4c