@sanity/workflow-engine-test 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -3,15 +3,16 @@ import { Actor } from "@sanity/workflow-engine";
 import type { CompleteEffectArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
-import { DispatchResult } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
+import { InitialFieldValue } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
+import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
@@ -51,21 +52,16 @@ export declare type Bench = BenchState &
   EngineWrappers &
   ReadHelpers &
   GuardHelpers &
-  QueryHelpers;
+  QueryHelpers &
+  ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<
-  CompleteEffectArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchCompleteEffectArgs = Omit<CompleteEffectArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
 };
 
-declare type BenchEditFieldArgs = Omit<
-  EditFieldArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEditFieldArgs = Omit<EditFieldArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -73,10 +69,7 @@ declare type BenchEditFieldArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchEvaluateArgs = Omit<
-  EvaluateArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEvaluateArgs = Omit<EvaluateArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -84,10 +77,7 @@ declare type BenchEvaluateArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchFireActionArgs = Omit<
-  FireActionArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchFireActionArgs = Omit<FireActionArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -95,10 +85,7 @@ declare type BenchFireActionArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchStartInstanceArgs = Omit<
-  StartInstanceArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchStartInstanceArgs = Omit<StartInstanceArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -142,10 +129,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<
-  OperationArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchTickArgs = Omit<OperationArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -171,6 +155,21 @@ declare interface CallRecord {
   dataset: string;
 }
 
+/** Helpers composed across the wrapper + read groups at bench assembly. */
+declare interface ComposedHelpers {
+  /**
+   * Complete the pending effect named `effect` — {@link EngineWrappers.completeEffect}
+   * with the `effectKey` looked up by name, throwing loud when no such effect
+   * is pending. The idiomatic way to play an external handler reporting its
+   * result; pass `ops` to write outcome fields in the same commit.
+   */
+  completePendingEffect: (
+    args: Omit<BenchCompleteEffectArgs, "effectKey"> & {
+      effect: string;
+    },
+  ) => Promise<OperationResult>;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tag`
@@ -282,13 +281,13 @@ declare type DocumentValuePermission = "create" | "read" | "update";
 /** Engine-call wrappers that inject the bench-owned client + tag + access. */
 declare type EngineWrappers = {
   deployDefinitions: (
-    args: Omit<DeployDefinitionsArgs, "client" | "tag" | "workflowResource">,
+    args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
-  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
-  editField: (args: BenchEditFieldArgs) => Promise<DispatchResult>;
-  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
-  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
+  editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
   guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
@@ -382,7 +381,7 @@ declare interface Grant_2 {
 }
 
 declare type GuardHelpers = {
-  /** All deployed `temp.system.guard` docs in the store. */
+  /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
   /**
    * Guards that would deny an arbitrary edit to `documentId` right now (i.e.
@@ -394,11 +393,11 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Write to a document through the client's enforced write seam — the bench
+   * Write to a document through the client's guarded write seam — the bench
    * client gates the write against deployed guards (incl. `identity()`) and
-   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
-   * `as` routes the write through a token-scoped sibling so `identity()`
-   * resolves to that actor.
+   * throws `MutationGuardDeniedError` on denial — the lake's intended
+   * rejection, simulated by the bench. `as` routes the write through a
+   * token-scoped sibling so `identity()` resolves to that actor.
    */
   editDocument: (opts: {
     documentId: string;
@@ -650,6 +649,18 @@ declare interface ReleaseDocument extends SanityDocument {
   publishAt?: string;
 }
 
+/**
+ * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
+ * default resource — what a release-targeting workflow's `release` field
+ * expects at start.
+ */
+export declare function releaseField(
+  releaseName: string,
+  opts?: {
+    name?: string;
+  },
+): InitialFieldValue;
+
 declare interface ReleaseMetadata {
   title?: string;
   description?: string;
@@ -737,6 +748,19 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+/**
+ * The conventional workflow-scope `subject` doc.ref entry, keyed by a bare
+ * doc id in the bench's default resource. `type` defaults to `'document'`;
+ * pass the subject's schema type when a filter or projection reads it.
+ */
+export declare function subjectField(
+  documentId: string,
+  opts?: {
+    name?: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 declare interface SystemFields {
   _rev: string;
   _createdAt: string;

package/dist/index.d.ts

@@ -3,15 +3,16 @@ import { Actor } from "@sanity/workflow-engine";
 import type { CompleteEffectArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsArgs } from "@sanity/workflow-engine";
 import { DeployDefinitionsResult } from "@sanity/workflow-engine";
-import { DispatchResult } from "@sanity/workflow-engine";
 import type { EditFieldArgs } from "@sanity/workflow-engine";
 import type { EvaluateArgs } from "@sanity/workflow-engine";
 import type { FireActionArgs } from "@sanity/workflow-engine";
 import { GdrUri } from "@sanity/workflow-engine";
 import type { Grant } from "@sanity/workflow-engine";
+import { InitialFieldValue } from "@sanity/workflow-engine";
 import { MutationGuardAction } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-engine";
 import type { OperationArgs } from "@sanity/workflow-engine";
+import { OperationResult } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
@@ -51,21 +52,16 @@ export declare type Bench = BenchState &
   EngineWrappers &
   ReadHelpers &
   GuardHelpers &
-  QueryHelpers;
+  QueryHelpers &
+  ComposedHelpers;
 
-declare type BenchCompleteEffectArgs = Omit<
-  CompleteEffectArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchCompleteEffectArgs = Omit<CompleteEffectArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
 };
 
-declare type BenchEditFieldArgs = Omit<
-  EditFieldArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEditFieldArgs = Omit<EditFieldArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -73,10 +69,7 @@ declare type BenchEditFieldArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchEvaluateArgs = Omit<
-  EvaluateArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchEvaluateArgs = Omit<EvaluateArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -84,10 +77,7 @@ declare type BenchEvaluateArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchFireActionArgs = Omit<
-  FireActionArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchFireActionArgs = Omit<FireActionArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -95,10 +85,7 @@ declare type BenchFireActionArgs = Omit<
   grants?: Grant[];
 };
 
-declare type BenchStartInstanceArgs = Omit<
-  StartInstanceArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchStartInstanceArgs = Omit<StartInstanceArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -142,10 +129,7 @@ declare interface BenchState {
   advance: (ms: number) => void;
 }
 
-declare type BenchTickArgs = Omit<
-  OperationArgs,
-  "client" | "tag" | "workflowResource" | "access"
-> & {
+declare type BenchTickArgs = Omit<OperationArgs, "access"> & {
   access?: WorkflowAccess;
   /** Shortcut for `access.actor`. */
   actor?: Actor;
@@ -171,6 +155,21 @@ declare interface CallRecord {
   dataset: string;
 }
 
+/** Helpers composed across the wrapper + read groups at bench assembly. */
+declare interface ComposedHelpers {
+  /**
+   * Complete the pending effect named `effect` — {@link EngineWrappers.completeEffect}
+   * with the `effectKey` looked up by name, throwing loud when no such effect
+   * is pending. The idiomatic way to play an external handler reporting its
+   * result; pass `ops` to write outcome fields in the same commit.
+   */
+  completePendingEffect: (
+    args: Omit<BenchCompleteEffectArgs, "effectKey"> & {
+      effect: string;
+    },
+  ) => Promise<OperationResult>;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tag`
@@ -282,13 +281,13 @@ declare type DocumentValuePermission = "create" | "read" | "update";
 /** Engine-call wrappers that inject the bench-owned client + tag + access. */
 declare type EngineWrappers = {
   deployDefinitions: (
-    args: Omit<DeployDefinitionsArgs, "client" | "tag" | "workflowResource">,
+    args: DeployDefinitionsArgs,
   ) => Promise<DeployDefinitionsResult>;
-  startInstance: (args: BenchStartInstanceArgs) => Promise<WorkflowInstance>;
-  fireAction: (args: BenchFireActionArgs) => Promise<DispatchResult>;
-  editField: (args: BenchEditFieldArgs) => Promise<DispatchResult>;
-  completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
-  tick: (args: BenchTickArgs) => Promise<DispatchResult>;
+  startInstance: (args: BenchStartInstanceArgs) => Promise<OperationResult>;
+  fireAction: (args: BenchFireActionArgs) => Promise<OperationResult>;
+  editField: (args: BenchEditFieldArgs) => Promise<OperationResult>;
+  completeEffect: (args: BenchCompleteEffectArgs) => Promise<OperationResult>;
+  tick: (args: BenchTickArgs) => Promise<OperationResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
   guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
   guardsForDefinition: (definition: string) => Promise<MutationGuardDoc[]>;
@@ -382,7 +381,7 @@ declare interface Grant_2 {
 }
 
 declare type GuardHelpers = {
-  /** All deployed `temp.system.guard` docs in the store. */
+  /** All deployed guard docs ({@link MutationGuardDoc}) in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
   /**
    * Guards that would deny an arbitrary edit to `documentId` right now (i.e.
@@ -394,11 +393,11 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Write to a document through the client's enforced write seam — the bench
+   * Write to a document through the client's guarded write seam — the bench
    * client gates the write against deployed guards (incl. `identity()`) and
-   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
-   * `as` routes the write through a token-scoped sibling so `identity()`
-   * resolves to that actor.
+   * throws `MutationGuardDeniedError` on denial — the lake's intended
+   * rejection, simulated by the bench. `as` routes the write through a
+   * token-scoped sibling so `identity()` resolves to that actor.
    */
   editDocument: (opts: {
     documentId: string;
@@ -650,6 +649,18 @@ declare interface ReleaseDocument extends SanityDocument {
   publishAt?: string;
 }
 
+/**
+ * A `release.ref` entry pointing at `_.releases.<releaseName>` in the bench's
+ * default resource — what a release-targeting workflow's `release` field
+ * expects at start.
+ */
+export declare function releaseField(
+  releaseName: string,
+  opts?: {
+    name?: string;
+  },
+): InitialFieldValue;
+
 declare interface ReleaseMetadata {
   title?: string;
   description?: string;
@@ -737,6 +748,19 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+/**
+ * The conventional workflow-scope `subject` doc.ref entry, keyed by a bare
+ * doc id in the bench's default resource. `type` defaults to `'document'`;
+ * pass the subject's schema type when a filter or projection reads it.
+ */
+export declare function subjectField(
+  documentId: string,
+  opts?: {
+    name?: string;
+    type?: string;
+  },
+): InitialFieldValue;
+
 declare interface SystemFields {
   _rev: string;
   _createdAt: string;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectsContextMap, validateTag } from "@sanity/workflow-engine";
+import { guardsForResource, denyingGuards, MutationGuardDeniedError, workflow, instancesQuery, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, effectsContextMap, gdrFromResource, gdrRef, validateTag } from "@sanity/workflow-engine";
 import require$$0 from "tty";
 import require$$1 from "util";
 function escapeRegExp(string2) {
@@ -5010,7 +5010,7 @@ const DEFAULT_WORKFLOW_RESOURCE = {
   type: "dataset",
   id: "test.test"
 }, ALL_ACCESS_USER = {
-  kind: "user",
+  kind: "person",
   id: "bench-user",
   roles: ["*"]
 }, WILDCARD_GRANTS = [
@@ -5181,17 +5181,38 @@ function createReadHelpers(scope) {
       )
     ),
     instancesByStage: async ({ workflowName, stage, openOnly }) => {
-      const filter = openOnly ? " && completedAt == null" : "";
-      return client.fetch(
-        `*[_type == "${WORKFLOW_INSTANCE_TYPE}" && definition == $wf && currentStage == $stage && ${tagScopeFilter()}${filter}]
-          | order(startedAt asc)`,
-        { wf: workflowName, stage, tag }
-      );
+      const { query, params } = instancesQuery({
+        tag,
+        filter: { definition: workflowName, stage, includeCompleted: !openOnly }
+      });
+      return client.fetch(query, params);
     },
     instancesForDocument: async (document2) => workflow.instancesForDocument({ ...scope, document: document2 }),
     snapshot: () => client.snapshot()
   };
 }
+function subjectField(documentId, opts) {
+  return {
+    type: "doc.ref",
+    name: opts?.name ?? "subject",
+    value: gdrRef({
+      res: DEFAULT_WORKFLOW_RESOURCE,
+      documentId,
+      type: opts?.type ?? "document"
+    })
+  };
+}
+function releaseField(releaseName, opts) {
+  return {
+    type: "release.ref",
+    name: opts?.name ?? "release",
+    value: {
+      id: gdrFromResource(DEFAULT_WORKFLOW_RESOURCE, `_.releases.${releaseName}`),
+      type: "system.release",
+      releaseName
+    }
+  };
+}
 function createBench(options = {}) {
   const tag = options.tag ?? "bench";
   validateTag(tag);
@@ -5201,7 +5222,7 @@ function createBench(options = {}) {
     workflowResource
   }, access = resolveBenchAccess(options);
   let frozenNow = options.now !== void 0 ? assertIsoInstant(options.now) : void 0;
-  const clock = () => frozenNow ?? (/* @__PURE__ */ new Date()).toISOString();
+  const clock = () => frozenNow ?? (/* @__PURE__ */ new Date()).toISOString(), engine = createEngineWrappers({ scope, access, clock }), reads = createReadHelpers(scope);
   return {
     client,
     access,
@@ -5217,10 +5238,16 @@ function createBench(options = {}) {
         throw new Error(`bench.advance: ms must be a finite number, got ${ms2}`);
       frozenNow = new Date(Date.parse(frozenNow ?? (/* @__PURE__ */ new Date()).toISOString()) + ms2).toISOString();
     },
-    ...createEngineWrappers({ scope, access, clock }),
-    ...createReadHelpers(scope),
+    ...engine,
+    ...reads,
     ...createGuardHelpers(client),
-    ...createQueryHelpers(scope)
+    ...createQueryHelpers(scope),
+    completePendingEffect: async ({ effect, ...rest }) => {
+      const match = (await reads.pendingEffects(rest.instanceId)).find((e) => e.name === effect);
+      if (match === void 0)
+        throw new Error(`completePendingEffect: no pending effect named "${effect}"`);
+      return engine.completeEffect({ ...rest, effectKey: match._key });
+    }
   };
 }
 function assertIsoInstant(iso) {
@@ -5234,6 +5261,8 @@ export {
   ALL_ACCESS_USER,
   DEFAULT_WORKFLOW_RESOURCE,
   WILDCARD_GRANTS,
-  createBench
+  createBench,
+  releaseField,
+  subjectField
 };
 //# sourceMappingURL=index.js.map