@nanobpm/bojtos-react 0.4.0 → 0.6.0

package/src/useBojtos.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
+  type ActivateInstruction,
   type AgentResult,
   type BojtosSession,
   createBojtosSession,
@@ -12,13 +13,20 @@ import {
   type WasmEvent,
   type WasmSource,
 } from "@nanobpm/bojtos-kit";
+import { bpmnKey, capEvents, resourceList } from "./runState.js";
 
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
 
 export interface UseBojtosOptions {
-  /** The BPMN diagram XML to deploy. Re-deploys on a fresh engine when it changes. */
-  bpmn: string;
+  /**
+   * The BPMN to deploy. Re-deploys on a fresh engine when it changes.
+   *
+   * Pass an array to deploy several resources into one engine — a called
+   * process alongside its parent, say. `processIds` then lists every deployable
+   * process across all of them, in deployment order.
+   */
+  bpmn: string | string[];
   /**
    * Optional engine wasm source. Pass a `URL` / bytes / `WebAssembly.Module`
    * when the default `import.meta.url` loader can't resolve the binary (the
@@ -29,6 +37,15 @@ export interface UseBojtosOptions {
    * reload the module.
    */
   wasm?: WasmSource;
+  /**
+   * Cap the reactive `events` log at the most recent N entries.
+   *
+   * Every command re-reads the engine's full event log into React state, so a
+   * long-running demo copies an ever-growing array on each step. Set this when
+   * a page runs for a while and only shows a tail; leave it unset to keep the
+   * whole log, which stays the default so existing consumers are unaffected.
+   */
+  maxEvents?: number;
 }
 
 export interface BojtosControls {
@@ -66,6 +83,74 @@ export interface BojtosControls {
   ): Snapshot | null;
   /** Advance the virtual clock. */
   advanceTime(byMs: number): Snapshot | null;
+  /**
+   * Throw a BPMN business error from a waiting job: interrupts the activity via
+   * a matching error boundary/event-subprocess catch, or raises an incident if
+   * uncaught. The job is consumed either way.
+   */
+  throwError(
+    jobKey: string,
+    errorCode: string,
+    errorMessage: string,
+  ): Snapshot | null;
+  /**
+   * Set a job's remaining retries. Used to recover a job parked on a no-retries
+   * incident before resolving that incident; does not itself unblock the job.
+   */
+  updateRetries(jobKey: string, retries: number): Snapshot | null;
+  /**
+   * Resolve an open incident by key, retrying the work that failed. Pair with
+   * {@link updateRetries} to make a failed job activatable again — the
+   * incident/retry loop a demo needs to show recovery.
+   */
+  resolveIncident(incidentKey: string): Snapshot | null;
+  /**
+   * Merge variables into a scope (a process-instance or element-instance key).
+   * With `local`, they are written strictly into that scope; otherwise they
+   * propagate up to the nearest ancestor defining each name.
+   */
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot | null;
+  /** Broadcast a signal by name to every matching open subscription. */
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot | null;
+  /** Cancel (terminate) a running process instance. */
+  cancelInstance(instanceKey: string): Snapshot | null;
+  /**
+   * Modify a running instance: terminate element instances and/or activate new
+   * ones (Zeebe "modify process instance").
+   */
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot | null;
+  /**
+   * Complete a waiting user task, merging output variables.
+   *
+   * A `userTask` produces no job, so the dispatch loop cannot advance one: this
+   * is the only way a model with a human step reaches its end event. Drive it
+   * from `snapshot.userTasks`.
+   */
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot | null;
+  /**
+   * Assign a user task. With `allowOverride` false the command is rejected if
+   * the task already has an assignee.
+   */
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot | null;
+  /** Clear a user task's assignee. */
+  unassignUserTask(userTaskKey: string): Snapshot | null;
+  /**
+   * Update a user task's attributes from a JSON changeset (`candidateGroups`,
+   * `candidateUsers`, `dueDate`, `followUpDate`, `priority`).
+   */
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot | null;
   /**
    * Run the registered worker handlers until the process settles (activate →
    * handler → complete/fail), then reflect the resulting snapshot/events.
@@ -92,6 +177,29 @@ export interface BojtosControls {
   reset(): void;
 }
 
+/**
+ * Session members the hook deliberately does not re-export: the deployment
+ * lifecycle it owns itself, and the low-level activate primitive the dispatch
+ * loop owns.
+ */
+type NotReExported = "deploy" | "free" | "activateJobs";
+
+/**
+ * Compile-time guard. `useBojtos` keeps its session private, so a command it
+ * doesn't re-export is *unreachable* for a consumer rather than merely
+ * inconvenient — which is how `completeUserTask` went missing and left any model
+ * with a user task unfinishable (#1).
+ *
+ * Adding a command to {@link BojtosSession} without a binding here now fails the
+ * build with the offending name, instead of shipping a hole.
+ */
+type UnboundCommands = Exclude<
+  keyof BojtosSession,
+  NotReExported | keyof BojtosControls
+>;
+type AssertNever<T extends never> = T;
+type _EverySessionCommandIsBound = AssertNever<UnboundCommands>;
+
 /**
  * React binding over a headless {@link BojtosSession}: owns the engine's
  * lifecycle and the reactive `snapshot` / `events` / `processIds` state, and
@@ -103,7 +211,11 @@ export interface BojtosControls {
  * test-run panel is its first consumer (§8 step 2 — dogfooding is the acceptance
  * test).
  */
-export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
+export function useBojtos({
+  bpmn,
+  wasm,
+  maxEvents,
+}: UseBojtosOptions): BojtosControls {
   const sessionRef = useRef<BojtosSession | null>(null);
   const [phase, setPhase] = useState<BojtosPhase>("loading");
   const [error, setError] = useState<string | null>(null);
@@ -117,15 +229,34 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
   const wasmRef = useRef(wasm);
   wasmRef.current = wasm;
 
+  // An array prop has a fresh identity every render, which would re-create the
+  // engine on each one. Key the deploy effect on the content instead — see
+  // `bpmnKey` for why this is a boundary-preserving serialization, not a join.
+  const deployKey = bpmnKey(bpmn);
+  const bpmnRef = useRef(bpmn);
+  bpmnRef.current = bpmn;
+
+  // Trim the reactive event log when the consumer asked for a cap.
+  const maxEventsRef = useRef(maxEvents);
+  maxEventsRef.current = maxEvents;
+  const readEvents = useCallback((session: BojtosSession): WasmEvent[] => {
+    return capEvents(session.events(), maxEventsRef.current);
+  }, []);
+
   const deployInto = useCallback(
     (session: BojtosSession) => {
-      const res = session.deploy(bpmn);
-      setProcessIds(res.processIds);
+      const resources = resourceList(bpmnRef.current);
+      // Deploy in order, collecting every deployable process id. A later
+      // resource can reference an earlier one (a call activity's child).
+      const ids: string[] = [];
+      for (const xml of resources) ids.push(...session.deploy(xml).processIds);
+      setProcessIds(ids);
       setSnapshot(null);
       setEvents([]);
       setError(null);
     },
-    [bpmn],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [deployKey],
   );
 
   useEffect(() => {
@@ -178,7 +309,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
       try {
         const snap = fn(session);
         setSnapshot(snap);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return snap;
       } catch (e) {
@@ -218,6 +349,68 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
       run((s) => s.correlateMessage(messageName, correlationKey, variablesJson)),
     [run],
   );
+  const throwError = useCallback(
+    (jobKey: string, errorCode: string, errorMessage: string) =>
+      run((s) => s.throwError(jobKey, errorCode, errorMessage)),
+    [run],
+  );
+  const updateRetries = useCallback(
+    (jobKey: string, retries: number) =>
+      run((s) => s.updateRetries(jobKey, retries)),
+    [run],
+  );
+  const resolveIncident = useCallback(
+    (incidentKey: string) => run((s) => s.resolveIncident(incidentKey)),
+    [run],
+  );
+  const setVariables = useCallback(
+    (scopeKey: string, variablesJson: string, local: boolean) =>
+      run((s) => s.setVariables(scopeKey, variablesJson, local)),
+    [run],
+  );
+  const broadcastSignal = useCallback(
+    (signalName: string, variablesJson: string) =>
+      run((s) => s.broadcastSignal(signalName, variablesJson)),
+    [run],
+  );
+  const cancelInstance = useCallback(
+    (instanceKey: string) => run((s) => s.cancelInstance(instanceKey)),
+    [run],
+  );
+  const modify = useCallback(
+    (
+      instanceKey: string,
+      activateInstructions: ActivateInstruction[],
+      terminateElementInstanceKeys: string[],
+    ) =>
+      run((s) =>
+        s.modify(
+          instanceKey,
+          activateInstructions,
+          terminateElementInstanceKeys,
+        ),
+      ),
+    [run],
+  );
+  const completeUserTask = useCallback(
+    (userTaskKey: string, variablesJson: string) =>
+      run((s) => s.completeUserTask(userTaskKey, variablesJson)),
+    [run],
+  );
+  const assignUserTask = useCallback(
+    (userTaskKey: string, assignee: string, allowOverride: boolean) =>
+      run((s) => s.assignUserTask(userTaskKey, assignee, allowOverride)),
+    [run],
+  );
+  const unassignUserTask = useCallback(
+    (userTaskKey: string) => run((s) => s.unassignUserTask(userTaskKey)),
+    [run],
+  );
+  const updateUserTask = useCallback(
+    (userTaskKey: string, changesetJson: string) =>
+      run((s) => s.updateUserTask(userTaskKey, changesetJson)),
+    [run],
+  );
 
   const runWorkers = useCallback(
     async (
@@ -236,7 +429,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // while we awaited — don't publish stale state or read a freed session.
         if (sessionRef.current !== session) return null;
         setSnapshot(settled);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return settled;
       } catch (e) {
@@ -244,7 +437,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // Reflect whatever state the engine reached before the drain aborted
         // (e.g. the maxRounds guard) so the view isn't left stale.
         setSnapshot(session.snapshot());
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(String(e));
         return null;
       }
@@ -264,13 +457,13 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
         // Bail if the session was replaced/freed while we awaited the round.
         if (sessionRef.current !== session) return null;
         setSnapshot(round.snapshot);
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(null);
         return round;
       } catch (e) {
         if (sessionRef.current !== session) return null;
         setSnapshot(session.snapshot());
-        setEvents(session.events());
+        setEvents(readEvents(session));
         setError(String(e));
         return null;
       }
@@ -304,6 +497,17 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
     failJob,
     advanceTime,
     correlateMessage,
+    throwError,
+    updateRetries,
+    resolveIncident,
+    setVariables,
+    broadcastSignal,
+    cancelInstance,
+    modify,
+    completeUserTask,
+    assignUserTask,
+    unassignUserTask,
+    updateUserTask,
     runWorkers,
     stepWorkers,
     reset,