@sanity-labs/client-fake-for-test 0.6.0 → 0.7.1

package/dist/index.d.cts

@@ -1,5 +1,11 @@
 export declare type Action = ReleaseAction | VersionAction;
 
+/** Options for `action()`. Only `tag` is meaningful to the fake. */
+export declare interface ActionOptions {
+  /** Request tag, recorded on the {@link CallRecord} (`null` = explicit suppression). */
+  tag?: string | null;
+}
+
 export declare interface ActionResult {
   transactionId: string;
 }
@@ -51,6 +57,8 @@ export declare interface CallRecord {
   result?: unknown;
   /** Thrown or rejected value, set if the call failed. */
   error?: unknown;
+  /** Request tag from the call's options, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
   projectId: string;
   dataset: string;
 }
@@ -321,8 +329,12 @@ export declare interface FetchOptions {
    * raw response. Ignored when `filterResponse` is not `false`.
    */
   returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  /**
+   * Request tag, recorded on the {@link CallRecord} for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
   signal?: AbortSignal;
 }
@@ -429,6 +441,8 @@ export declare interface MutationLogEntry {
   projectId: string;
   dataset: string;
   mutations: TxnMutation[];
+  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
 }
 
 /** The operation recorded per affected document, matching `@sanity/client`. */
@@ -456,8 +470,21 @@ export declare interface MutationOptions {
   visibility?: "sync" | "async" | "deferred";
   /** Accepted for signature parity; not simulated. */
   autoGenerateArrayKeys?: boolean;
+  /**
+   * Request tag, recorded on the {@link CallRecord} and the
+   * {@link MutationLogEntry} for assertions. `null` mirrors
+   * `@sanity/client`'s explicit-suppression form and is recorded as-is.
+   * No other behavior is simulated.
+   */
+  tag?: string | null;
+}
+
+/** Options for `PatchHandle.commit()`. Only `tag` is meaningful to the fake. */
+export declare interface PatchCommitOptions {
+  /** Request tag, recorded on the mutation log entry (`null` = explicit suppression). */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  visibility?: "sync" | "async" | "deferred";
 }
 
 export declare interface PatchExecutor {
@@ -465,6 +492,7 @@ export declare interface PatchExecutor {
     documentId: string,
     ops: PatchOp[],
     ifRev: string | undefined,
+    options: PatchCommitOptions | undefined,
   ) => Promise<SanityDocument>;
 }
 
@@ -480,7 +508,7 @@ export declare interface PatchHandle {
     items: unknown[],
   ) => PatchHandle;
   ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: PatchCommitOptions) => Promise<SanityDocument>;
   /** Test-only introspection — not on real Patch */
   toJSON: () => {
     id: string;
@@ -727,7 +755,7 @@ export declare interface TestClient {
     url?: string;
     uri?: string;
     signal?: AbortSignal;
-    tag?: string;
+    tag?: string | null;
   }) => Promise<T>;
   create: <T extends SanityDocumentLike>(
     doc: T,
@@ -765,7 +793,10 @@ export declare interface TestClient {
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
    * atomically — any failure rolls back the batch.
    */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
+  action: (
+    action: Action | Action[],
+    options?: ActionOptions,
+  ) => Promise<ActionResult>;
   /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
   releases: ReleasesHandle;
   /** Helper for `sanity.action.document.version.create`. */
@@ -987,6 +1018,12 @@ export declare interface TxnCommitOptions {
   returnFirst?: boolean;
   /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
   transactionId?: string;
+  /**
+   * Request tag, recorded on the mutation log entry for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
 }
 
 export declare type TxnCommitResult =

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export declare type Action = ReleaseAction | VersionAction;
 
+/** Options for `action()`. Only `tag` is meaningful to the fake. */
+export declare interface ActionOptions {
+  /** Request tag, recorded on the {@link CallRecord} (`null` = explicit suppression). */
+  tag?: string | null;
+}
+
 export declare interface ActionResult {
   transactionId: string;
 }
@@ -51,6 +57,8 @@ export declare interface CallRecord {
   result?: unknown;
   /** Thrown or rejected value, set if the call failed. */
   error?: unknown;
+  /** Request tag from the call's options, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
   projectId: string;
   dataset: string;
 }
@@ -321,8 +329,12 @@ export declare interface FetchOptions {
    * raw response. Ignored when `filterResponse` is not `false`.
    */
   returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  /**
+   * Request tag, recorded on the {@link CallRecord} for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
   signal?: AbortSignal;
 }
@@ -429,6 +441,8 @@ export declare interface MutationLogEntry {
   projectId: string;
   dataset: string;
   mutations: TxnMutation[];
+  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
 }
 
 /** The operation recorded per affected document, matching `@sanity/client`. */
@@ -456,8 +470,21 @@ export declare interface MutationOptions {
   visibility?: "sync" | "async" | "deferred";
   /** Accepted for signature parity; not simulated. */
   autoGenerateArrayKeys?: boolean;
+  /**
+   * Request tag, recorded on the {@link CallRecord} and the
+   * {@link MutationLogEntry} for assertions. `null` mirrors
+   * `@sanity/client`'s explicit-suppression form and is recorded as-is.
+   * No other behavior is simulated.
+   */
+  tag?: string | null;
+}
+
+/** Options for `PatchHandle.commit()`. Only `tag` is meaningful to the fake. */
+export declare interface PatchCommitOptions {
+  /** Request tag, recorded on the mutation log entry (`null` = explicit suppression). */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  visibility?: "sync" | "async" | "deferred";
 }
 
 export declare interface PatchExecutor {
@@ -465,6 +492,7 @@ export declare interface PatchExecutor {
     documentId: string,
     ops: PatchOp[],
     ifRev: string | undefined,
+    options: PatchCommitOptions | undefined,
   ) => Promise<SanityDocument>;
 }
 
@@ -480,7 +508,7 @@ export declare interface PatchHandle {
     items: unknown[],
   ) => PatchHandle;
   ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: PatchCommitOptions) => Promise<SanityDocument>;
   /** Test-only introspection — not on real Patch */
   toJSON: () => {
     id: string;
@@ -727,7 +755,7 @@ export declare interface TestClient {
     url?: string;
     uri?: string;
     signal?: AbortSignal;
-    tag?: string;
+    tag?: string | null;
   }) => Promise<T>;
   create: <T extends SanityDocumentLike>(
     doc: T,
@@ -765,7 +793,10 @@ export declare interface TestClient {
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
    * atomically — any failure rolls back the batch.
    */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
+  action: (
+    action: Action | Action[],
+    options?: ActionOptions,
+  ) => Promise<ActionResult>;
   /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
   releases: ReleasesHandle;
   /** Helper for `sanity.action.document.version.create`. */
@@ -987,6 +1018,12 @@ export declare interface TxnCommitOptions {
   returnFirst?: boolean;
   /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
   transactionId?: string;
+  /**
+   * Request tag, recorded on the mutation log entry for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
 }
 
 export declare type TxnCommitResult =

package/dist/index.js

@@ -136,7 +136,7 @@ function createPatch(documentId, executor) {
     dec: (props) => (ops.push({ kind: "dec", props }), handle),
     insert: (position, anchor, items) => (ops.push({ kind: "insert", position, anchor, items }), handle),
     ifRevisionId: (rev) => (ifRev = rev, handle),
-    commit: () => executor.apply(documentId, ops, ifRev),
+    commit: (options) => executor.apply(documentId, ops, ifRev, options),
     toJSON: () => ({
       id: documentId,
       ops: [...ops],
@@ -837,6 +837,25 @@ function wrapWithGuards(client, config) {
     }
   });
 }
+const OPTIONS_ARG_POSITION = {
+  fetch: 2,
+  getDocument: 1,
+  getDocuments: 1,
+  create: 1,
+  createOrReplace: 1,
+  createIfNotExists: 1,
+  delete: 1,
+  mutate: 1,
+  action: 1,
+  request: 0
+};
+function tagFromArgs(method, args) {
+  const position = OPTIONS_ARG_POSITION[method];
+  if (position === void 0) return;
+  const options = args[position];
+  if (!(typeof options != "object" || options === null || !("tag" in options)))
+    return options.tag;
+}
 const RECORDED_METHODS = /* @__PURE__ */ new Set([
   "fetch",
   "getDocument",
@@ -854,6 +873,15 @@ const RECORDED_METHODS = /* @__PURE__ */ new Set([
   "unpublishVersion",
   "request"
 ]), DEFAULT_PROJECT_ID = "test", DEFAULT_DATASET = "test";
+function serializeWrite(backend, run) {
+  const result = backend.writeChain.then(run);
+  return backend.writeChain = result.then(
+    () => {
+    },
+    () => {
+    }
+  ), result;
+}
 function requireIdentity(backend, token, site) {
   if (backend.identities.has(token)) return;
   const known = [...backend.identities.keys()];
@@ -878,7 +906,8 @@ function createTestClient(options = {}) {
     stubs: /* @__PURE__ */ new Map(),
     calls: [],
     concurrentEdits: /* @__PURE__ */ new Map(),
-    identities: new Map(Object.entries(options.identities ?? {}))
+    identities: new Map(Object.entries(options.identities ?? {})),
+    writeChain: Promise.resolve()
   }, registry = backend.registry;
   rejectAmbiguousIdentity("createTestClient()", options), options.token !== void 0 && requireIdentity(backend, options.token, "createTestClient()");
   const ensureStore = (projectId, dataset) => {
@@ -967,8 +996,14 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
     const key = registryKey(projectId, dataset);
     let s = registry.get(key);
     return s === void 0 && (s = createTestStore(), registry.set(key, s)), s;
-  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations) => {
-    backend.log.push({ transactionId, projectId, dataset, mutations });
+  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations, tag) => {
+    backend.log.push({
+      transactionId,
+      projectId,
+      dataset,
+      mutations,
+      ...tag !== void 0 ? { tag } : {}
+    });
   }, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
     documents,
     results,
@@ -1092,7 +1127,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
         doc === void 0 ? store.remove(id) : store.put(doc);
       throw error;
     }
-    record(transactionId, mutations);
+    record(transactionId, mutations, txnOptions?.tag);
     const documents = touchedIds.map((id) => store.get(id)).filter((d) => d !== void 0);
     return formatMutationResult(
       documents,
@@ -1101,7 +1136,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       txnOptions?.returnDocuments ?? !1,
       txnOptions?.returnFirst ?? !1
     );
-  }, accessVisibleDocs = async () => {
+  }, runAction = (actions) => serializeWrite(backend, async () => applyActions(store, actions)), accessVisibleDocs = async () => {
     const all = store.all();
     if (activeAccess() === void 0) return all;
     const out = [];
@@ -1145,7 +1180,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       const view = await visibleDocs(effective);
       return ids.map((id) => resolveDocument(view, id, effective) ?? null);
     },
-    create: async (doc, opts) => {
+    create: (doc, opts) => serializeWrite(backend, async () => {
       if (checkRevision(doc._id, opts?.ifRevisionId), store.get(doc._id) !== void 0)
         throw fakeError(
           `create() failed: a document with _id "${doc._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
@@ -1153,19 +1188,19 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       const promoted = promote2(doc);
       await gate(promoted, "create"), await guardGate("create", null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
-      return opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "create", doc }])), writeResult(
+      return opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "create", doc }], opts?.tag)), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
         opts
       );
-    },
-    createOrReplace: async (doc, opts) => {
+    }),
+    createOrReplace: (doc, opts) => serializeWrite(backend, async () => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const promoted = promote2(doc), existing = store.get(doc._id);
       await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardGate(existing !== void 0 ? "update" : "create", existing ?? null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
-      opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createOrReplace", doc }]));
+      opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createOrReplace", doc }], opts?.tag));
       const operation = existing !== void 0 ? "update" : "create";
       return writeResult(
         [promoted],
@@ -1173,8 +1208,8 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
         transactionId,
         opts
       );
-    },
-    createIfNotExists: async (doc, opts) => {
+    }),
+    createIfNotExists: (doc, opts) => serializeWrite(backend, async () => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const existing = store.get(doc._id), transactionId = opts?.transactionId ?? cryptoRandomKey();
       if (existing !== void 0)
@@ -1185,41 +1220,55 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
           opts
         );
       const promoted = promote2(doc);
-      return await gate(promoted, "create"), await guardGate("create", null, promoted), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }])), writeResult(
+      return await gate(promoted, "create"), await guardGate("create", null, promoted), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }], opts?.tag)), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
         opts
       );
-    },
-    delete: async (id, opts) => {
+    }),
+    delete: (id, opts) => serializeWrite(backend, async () => {
       checkRevision(id, opts?.ifRevisionId);
       const existing = store.get(id);
       existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardGate("delete", existing, null);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       let removed = existing;
-      return opts?.dryRun !== !0 && (removed = store.remove(id), removed !== void 0 && record(transactionId, [{ kind: "delete", id }])), opts?.returnDocuments === void 0 && opts?.returnFirst === void 0 ? removed !== void 0 ? { _id: id } : null : formatMutationResult(
+      return opts?.dryRun !== !0 && (removed = store.remove(id), removed !== void 0 && record(transactionId, [{ kind: "delete", id }], opts?.tag)), opts?.returnDocuments === void 0 && opts?.returnFirst === void 0 ? removed !== void 0 ? { _id: id } : null : formatMutationResult(
         removed !== void 0 ? [removed] : [],
         removed !== void 0 ? [{ id, operation: "delete" }] : [],
         transactionId,
         opts.returnDocuments ?? !0,
         opts.returnFirst ?? !0
       );
-    },
+    }),
     patch: (documentId) => createPatch(documentId, {
-      apply: async (docId, ops, ifRev) => {
+      apply: (docId, ops, ifRev, options) => serializeWrite(backend, async () => {
         const doc = await applyPatch(docId, ops, ifRev);
-        return record(cryptoRandomKey(), [
-          { kind: "patch", documentId: docId, ops, ...ifRev !== void 0 ? { ifRev } : {} }
-        ]), doc;
-      }
+        return record(
+          cryptoRandomKey(),
+          [
+            {
+              kind: "patch",
+              documentId: docId,
+              ops,
+              ...ifRev !== void 0 ? { ifRev } : {}
+            }
+          ],
+          options?.tag
+        ), doc;
+      })
+    }),
+    transaction: () => createTransaction({
+      apply: (mutations, txnOptions) => serializeWrite(backend, () => applyTransaction(mutations, txnOptions))
     }),
-    transaction: () => createTransaction({ apply: applyTransaction }),
-    mutate: async (operations, options) => applyTransaction(toTxnMutations(operations), options),
-    action: async (action) => applyActions(store, action),
+    mutate: (operations, options) => serializeWrite(backend, () => applyTransaction(toTxnMutations(operations), options)),
+    // Synchronous writes still take the lock: an action landing while a
+    // guarded patch is parked in its gate would otherwise be clobbered
+    // when that patch resumes over its pre-action snapshot.
+    action: (action) => runAction(action),
     releases: {
       create: async ({ releaseId, metadata }) => {
-        const result = applyActions(store, {
+        const result = await runAction({
           actionType: "sanity.action.release.create",
           releaseId,
           ...metadata !== void 0 ? { metadata } : {}
@@ -1230,30 +1279,30 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
           metadata: doc?.metadata ?? { releaseType: "undecided" }
         };
       },
-      edit: async ({ releaseId, patch }) => applyActions(store, { actionType: "sanity.action.release.edit", releaseId, patch }),
+      edit: ({ releaseId, patch }) => runAction({ actionType: "sanity.action.release.edit", releaseId, patch }),
       get: async ({ releaseId }) => store.get(`_.releases.${releaseId}`),
       fetchDocuments: async ({ releaseId }) => {
         const prefix = `versions.${releaseId}.`;
         return store.all().filter((d) => d._id.startsWith(prefix));
       },
-      schedule: async ({ releaseId, publishAt }) => applyActions(store, {
+      schedule: ({ releaseId, publishAt }) => runAction({
         actionType: "sanity.action.release.schedule",
         releaseId,
         publishAt
       }),
-      unschedule: async ({ releaseId }) => applyActions(store, { actionType: "sanity.action.release.unschedule", releaseId }),
-      publish: async ({ releaseId }) => applyActions(store, { actionType: "sanity.action.release.publish", releaseId }),
-      archive: async ({ releaseId }) => applyActions(store, { actionType: "sanity.action.release.archive", releaseId }),
-      unarchive: async ({ releaseId }) => applyActions(store, { actionType: "sanity.action.release.unarchive", releaseId }),
-      delete: async ({ releaseId }) => applyActions(store, { actionType: "sanity.action.release.delete", releaseId })
+      unschedule: ({ releaseId }) => runAction({ actionType: "sanity.action.release.unschedule", releaseId }),
+      publish: ({ releaseId }) => runAction({ actionType: "sanity.action.release.publish", releaseId }),
+      archive: ({ releaseId }) => runAction({ actionType: "sanity.action.release.archive", releaseId }),
+      unarchive: ({ releaseId }) => runAction({ actionType: "sanity.action.release.unarchive", releaseId }),
+      delete: ({ releaseId }) => runAction({ actionType: "sanity.action.release.delete", releaseId })
     },
-    createVersion: async ({ releaseId, publishedId, document }) => applyActions(store, {
+    createVersion: ({ releaseId, publishedId, document }) => runAction({
       actionType: "sanity.action.document.version.create",
       releaseId,
       publishedId,
       document
     }),
-    unpublishVersion: async ({ releaseId, publishedId }) => applyActions(store, {
+    unpublishVersion: ({ releaseId, publishedId }) => runAction({
       actionType: "sanity.action.document.version.unpublish",
       versionId: `versions.${releaseId}.${publishedId}`,
       publishedId
@@ -1305,8 +1354,8 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
   return wrapWithGuards(client, {
     getStub: (name) => backend.stubs.get(name),
     onCall: (method, args) => {
-      const rec = { method, args, projectId, dataset };
-      return backend.calls.push(rec), (outcome) => {
+      const rec = { method, args, projectId, dataset }, tag = tagFromArgs(method, args);
+      return tag !== void 0 && (rec.tag = tag), backend.calls.push(rec), (outcome) => {
         "error" in outcome ? rec.error = outcome.error : rec.result = outcome.result;
       };
     },