@sanity/diff-patch 5.0.0 → 6.0.0

package/dist/index.d.cts

@@ -13,91 +13,36 @@ export declare class DiffError extends Error {
 }
 
 /**
- * Diffs two items and returns an array of patches.
- * Note that this is different from `diffPatch`, which generates _mutations_.
+ * Generates an array of mutations for Sanity, based on the differences between
+ * the two passed documents/trees.
  *
- * @param itemA - The first item to compare
- * @param itemB - The second item to compare
+ * @param source - The first document/tree to compare
+ * @param target - The second document/tree to compare
  * @param opts - Options for the diff generation
- * @param path - Path to the current item
- * @param patches - Array of patches to append the results to. Note that this is MUTATED.
- * @returns Array of patches
- * @public
- */
-export declare function diffItem(
-  itemA: unknown,
-  itemB: unknown,
-  opts?: DiffOptions,
-  path?: Path,
-  patches?: Patch[],
-): Patch[]
-
-/**
- * A `diffMatchPatch` operation
- * Applies the given `value` (unidiff format) to the given path. Must be a string.
- * Note: NOT a serializable mutation, see {@link SanityDiffMatchPatch} for that
- *
- * @public
- */
-export declare interface DiffMatchPatch {
-  op: 'diffMatchPatch'
-  path: Path
-  value: string
-}
-
-/**
- * Options for the diff-match-patch algorithm.
- *
- * @public
- */
-export declare interface DiffMatchPatchOptions {
-  /**
-   * Whether or not to use diff-match-patch at all
-   *
-   * @defaultValue `true`
-   */
-  enabled: boolean
-  /**
-   * Threshold at which to start using diff-match-patch instead of a regular `set` patch.
-   *
-   * @defaultValue `30`
-   */
-  lengthThresholdAbsolute: number
-  /**
-   * Only use generated diff-match-patch if the patch length is less than or equal to
-   * (targetString * relative). Example: A 100 character target with a relative factor
-   * of 1.2 will allow a 120 character diff-match-patch. If larger than this number,
-   * it will fall back to a regular `set` patch.
-   *
-   * @defaultValue `1.2`
-   */
-  lengthThresholdRelative: number
-}
-
-/**
- * Options for diff generation, where all DMP properties are required
- *
+ * @returns Array of mutations
  * @public
  */
-export declare type DiffOptions = PatchOptions & {
-  diffMatchPatch: Required<DiffMatchPatchOptions>
-}
+export declare function diffPatch(
+  source: DocumentStub,
+  target: DocumentStub,
+  options?: PatchOptions,
+): SanityPatchMutation[]
 
 /**
- * Generates an array of mutations for Sanity, based on the differences between
- * the two passed documents/trees.
+ * Generates an array of patch operation objects for Sanity, based on the
+ * differences between the two passed values
  *
- * @param itemA - The first document/tree to compare
- * @param itemB - The second document/tree to compare
- * @param opts - Options for the diff generation
+ * @param source - The source value to start off with
+ * @param target - The target value that the patch operations will aim to create
+ * @param basePath - An optional path that will be prefixed to all subsequent patch operations
  * @returns Array of mutations
  * @public
  */
-export declare function diffPatch(
-  itemA: DocumentStub,
-  itemB: DocumentStub,
-  opts?: PatchOptions,
-): SanityPatchMutation[]
+export declare function diffValue(
+  source: unknown,
+  target: unknown,
+  basePath?: Path,
+): SanityPatchOperations[]
 
 /**
  * Represents a partial Sanity document (eg a "stub").
@@ -113,26 +58,6 @@ export declare interface DocumentStub {
   [key: string]: unknown
 }
 
-/**
- * A `insert` operation
- * Inserts the given items _after_ the given path
- * Note: NOT a serializable mutation, see {@link SanityInsertPatch} for that
- *
- * @public
- */
-export declare interface InsertAfterPatch {
-  op: 'insert'
-  after: Path
-  items: any[]
-}
-
-/**
- * A patch containing either a Sanity set, unset, insert or diffMatchPatch operation
- *
- * @public
- */
-export declare type Patch = SetPatch | UnsetPatch | InsertAfterPatch | DiffMatchPatch
-
 /**
  * Options for the patch generator
  *
@@ -159,16 +84,6 @@ export declare interface PatchOptions {
    * @defaultValue `undefined` (do not apply revision check)
    */
   ifRevisionID?: string | true
-  /**
-   * Whether or not to hide warnings during the diff process.
-   *
-   * @defaultValue `false`
-   */
-  hideWarnings?: boolean
-  /**
-   * Options for the diff-match-patch algorithm.
-   */
-  diffMatchPatch?: Partial<DiffMatchPatchOptions>
 }
 
 /**
@@ -197,11 +112,8 @@ export declare type PathSegment =
  *
  * @public
  */
-export declare interface SanityDiffMatchPatch {
-  id: string
-  diffMatchPatch: {
-    [key: string]: string
-  }
+declare interface SanityDiffMatchPatchOperation {
+  diffMatchPatch: Record<string, string>
 }
 
 /**
@@ -210,33 +122,34 @@ export declare interface SanityDiffMatchPatch {
  *
  * @public
  */
-export declare interface SanityInsertPatch {
-  id: string
+declare interface SanityInsertPatchOperation {
   insert:
     | {
         before: string
-        items: any[]
+        items: unknown[]
       }
     | {
         after: string
-        items: any[]
+        items: unknown[]
       }
     | {
         replace: string
-        items: any[]
+        items: unknown[]
       }
 }
 
 /**
- * A patch containing either a set, unset, insert or diffMatchPatch operation
+ * Meant to be used as the body of a {@link SanityPatchMutation}'s `patch` key.
+ *
+ * Contains additional properties to target a particular ID and optionally add
+ * an optimistic lock via [`ifRevisionID`](https://www.sanity.io/docs/content-lake/transactions#k29b2c75639d5).
  *
  * @public
  */
-export declare type SanityPatch =
-  | SanitySetPatch
-  | SanityUnsetPatch
-  | SanityInsertPatch
-  | SanityDiffMatchPatch
+export declare interface SanityPatch extends SanityPatchOperations {
+  id: string
+  ifRevisionID?: string
+}
 
 /**
  * A mutation containing a single patch
@@ -248,52 +161,35 @@ export declare interface SanityPatchMutation {
 }
 
 /**
- * A Sanity `set` patch mutation operation
- * Replaces the current path, does not merge
+ * Serializable patch operations that can be applied to a Sanity document.
  *
  * @public
  */
-export declare interface SanitySetPatch {
-  id: string
-  set: {
-    [key: string]: any
-  }
-}
+export declare type SanityPatchOperations = Partial<
+  SanitySetPatchOperation &
+    SanityUnsetPatchOperation &
+    SanityInsertPatchOperation &
+    SanityDiffMatchPatchOperation
+>
 
 /**
- * A Sanity `unset` patch mutation operation
- * Unsets the entire value of the given path
- *
- * @public
- */
-export declare interface SanityUnsetPatch {
-  id: string
-  unset: string[]
-}
-
-/**
- * A `set` operation
+ * A Sanity `set` patch mutation operation
  * Replaces the current path, does not merge
- * Note: NOT a serializable mutation, see {@link SanitySetPatch} for that
  *
  * @public
  */
-export declare interface SetPatch {
-  op: 'set'
-  path: Path
-  value: unknown
+declare interface SanitySetPatchOperation {
+  set: Record<string, unknown>
 }
 
 /**
- * A `unset` operation
+ * A Sanity `unset` patch mutation operation
  * Unsets the entire value of the given path
- * Note: NOT a serializable mutation, see {@link SanityUnsetPatch} for that
  *
  * @public
  */
-export declare interface UnsetPatch {
-  op: 'unset'
-  path: Path
+declare interface SanityUnsetPatchOperation {
+  unset: string[]
 }
 
 export {}

package/dist/index.d.ts

@@ -13,91 +13,36 @@ export declare class DiffError extends Error {
 }
 
 /**
- * Diffs two items and returns an array of patches.
- * Note that this is different from `diffPatch`, which generates _mutations_.
+ * Generates an array of mutations for Sanity, based on the differences between
+ * the two passed documents/trees.
  *
- * @param itemA - The first item to compare
- * @param itemB - The second item to compare
+ * @param source - The first document/tree to compare
+ * @param target - The second document/tree to compare
  * @param opts - Options for the diff generation
- * @param path - Path to the current item
- * @param patches - Array of patches to append the results to. Note that this is MUTATED.
- * @returns Array of patches
- * @public
- */
-export declare function diffItem(
-  itemA: unknown,
-  itemB: unknown,
-  opts?: DiffOptions,
-  path?: Path,
-  patches?: Patch[],
-): Patch[]
-
-/**
- * A `diffMatchPatch` operation
- * Applies the given `value` (unidiff format) to the given path. Must be a string.
- * Note: NOT a serializable mutation, see {@link SanityDiffMatchPatch} for that
- *
- * @public
- */
-export declare interface DiffMatchPatch {
-  op: 'diffMatchPatch'
-  path: Path
-  value: string
-}
-
-/**
- * Options for the diff-match-patch algorithm.
- *
- * @public
- */
-export declare interface DiffMatchPatchOptions {
-  /**
-   * Whether or not to use diff-match-patch at all
-   *
-   * @defaultValue `true`
-   */
-  enabled: boolean
-  /**
-   * Threshold at which to start using diff-match-patch instead of a regular `set` patch.
-   *
-   * @defaultValue `30`
-   */
-  lengthThresholdAbsolute: number
-  /**
-   * Only use generated diff-match-patch if the patch length is less than or equal to
-   * (targetString * relative). Example: A 100 character target with a relative factor
-   * of 1.2 will allow a 120 character diff-match-patch. If larger than this number,
-   * it will fall back to a regular `set` patch.
-   *
-   * @defaultValue `1.2`
-   */
-  lengthThresholdRelative: number
-}
-
-/**
- * Options for diff generation, where all DMP properties are required
- *
+ * @returns Array of mutations
  * @public
  */
-export declare type DiffOptions = PatchOptions & {
-  diffMatchPatch: Required<DiffMatchPatchOptions>
-}
+export declare function diffPatch(
+  source: DocumentStub,
+  target: DocumentStub,
+  options?: PatchOptions,
+): SanityPatchMutation[]
 
 /**
- * Generates an array of mutations for Sanity, based on the differences between
- * the two passed documents/trees.
+ * Generates an array of patch operation objects for Sanity, based on the
+ * differences between the two passed values
  *
- * @param itemA - The first document/tree to compare
- * @param itemB - The second document/tree to compare
- * @param opts - Options for the diff generation
+ * @param source - The source value to start off with
+ * @param target - The target value that the patch operations will aim to create
+ * @param basePath - An optional path that will be prefixed to all subsequent patch operations
  * @returns Array of mutations
  * @public
  */
-export declare function diffPatch(
-  itemA: DocumentStub,
-  itemB: DocumentStub,
-  opts?: PatchOptions,
-): SanityPatchMutation[]
+export declare function diffValue(
+  source: unknown,
+  target: unknown,
+  basePath?: Path,
+): SanityPatchOperations[]
 
 /**
  * Represents a partial Sanity document (eg a "stub").
@@ -113,26 +58,6 @@ export declare interface DocumentStub {
   [key: string]: unknown
 }
 
-/**
- * A `insert` operation
- * Inserts the given items _after_ the given path
- * Note: NOT a serializable mutation, see {@link SanityInsertPatch} for that
- *
- * @public
- */
-export declare interface InsertAfterPatch {
-  op: 'insert'
-  after: Path
-  items: any[]
-}
-
-/**
- * A patch containing either a Sanity set, unset, insert or diffMatchPatch operation
- *
- * @public
- */
-export declare type Patch = SetPatch | UnsetPatch | InsertAfterPatch | DiffMatchPatch
-
 /**
  * Options for the patch generator
  *
@@ -159,16 +84,6 @@ export declare interface PatchOptions {
    * @defaultValue `undefined` (do not apply revision check)
    */
   ifRevisionID?: string | true
-  /**
-   * Whether or not to hide warnings during the diff process.
-   *
-   * @defaultValue `false`
-   */
-  hideWarnings?: boolean
-  /**
-   * Options for the diff-match-patch algorithm.
-   */
-  diffMatchPatch?: Partial<DiffMatchPatchOptions>
 }
 
 /**
@@ -197,11 +112,8 @@ export declare type PathSegment =
  *
  * @public
  */
-export declare interface SanityDiffMatchPatch {
-  id: string
-  diffMatchPatch: {
-    [key: string]: string
-  }
+declare interface SanityDiffMatchPatchOperation {
+  diffMatchPatch: Record<string, string>
 }
 
 /**
@@ -210,33 +122,34 @@ export declare interface SanityDiffMatchPatch {
  *
  * @public
  */
-export declare interface SanityInsertPatch {
-  id: string
+declare interface SanityInsertPatchOperation {
   insert:
     | {
         before: string
-        items: any[]
+        items: unknown[]
       }
     | {
         after: string
-        items: any[]
+        items: unknown[]
       }
     | {
         replace: string
-        items: any[]
+        items: unknown[]
       }
 }
 
 /**
- * A patch containing either a set, unset, insert or diffMatchPatch operation
+ * Meant to be used as the body of a {@link SanityPatchMutation}'s `patch` key.
+ *
+ * Contains additional properties to target a particular ID and optionally add
+ * an optimistic lock via [`ifRevisionID`](https://www.sanity.io/docs/content-lake/transactions#k29b2c75639d5).
  *
  * @public
  */
-export declare type SanityPatch =
-  | SanitySetPatch
-  | SanityUnsetPatch
-  | SanityInsertPatch
-  | SanityDiffMatchPatch
+export declare interface SanityPatch extends SanityPatchOperations {
+  id: string
+  ifRevisionID?: string
+}
 
 /**
  * A mutation containing a single patch
@@ -248,52 +161,35 @@ export declare interface SanityPatchMutation {
 }
 
 /**
- * A Sanity `set` patch mutation operation
- * Replaces the current path, does not merge
+ * Serializable patch operations that can be applied to a Sanity document.
  *
  * @public
  */
-export declare interface SanitySetPatch {
-  id: string
-  set: {
-    [key: string]: any
-  }
-}
+export declare type SanityPatchOperations = Partial<
+  SanitySetPatchOperation &
+    SanityUnsetPatchOperation &
+    SanityInsertPatchOperation &
+    SanityDiffMatchPatchOperation
+>
 
 /**
- * A Sanity `unset` patch mutation operation
- * Unsets the entire value of the given path
- *
- * @public
- */
-export declare interface SanityUnsetPatch {
-  id: string
-  unset: string[]
-}
-
-/**
- * A `set` operation
+ * A Sanity `set` patch mutation operation
  * Replaces the current path, does not merge
- * Note: NOT a serializable mutation, see {@link SanitySetPatch} for that
  *
  * @public
  */
-export declare interface SetPatch {
-  op: 'set'
-  path: Path
-  value: unknown
+declare interface SanitySetPatchOperation {
+  set: Record<string, unknown>
 }
 
 /**
- * A `unset` operation
+ * A Sanity `unset` patch mutation operation
  * Unsets the entire value of the given path
- * Note: NOT a serializable mutation, see {@link SanityUnsetPatch} for that
  *
  * @public
  */
-export declare interface UnsetPatch {
-  op: 'unset'
-  path: Path
+declare interface SanityUnsetPatchOperation {
+  unset: string[]
 }
 
 export {}