@fluidgrids/workflows 2026.1029.1 → 2026.1030.1

package/dist/interceptors-CNcr2dlk.d.ts

@@ -0,0 +1,159 @@
+import { a as Json, J as JsonObject } from './types-V7jEEUaL.js';
+import { ad as RunTarget, M as Headers } from './types-DGx-b9eq.js';
+
+/**
+ * Interceptors (11 §2.10): middleware around what workflow code receives
+ * (inbound) and issues (outbound), and around activity execution. A `headers`
+ * map travels with starts, signals, updates, activities and children, so one
+ * interceptor can hand context (trace ids, tenant hints) to the next one in
+ * another run or on a worker.
+ *
+ * A managed bundle registers workflow interceptors by exporting
+ * `interceptors` (made with {@link workflowInterceptors}, or a plain factory
+ * function) from any module; the factory runs once per workflow task inside
+ * the isolate, so it must be deterministic. Self-hosted workers and clients
+ * register theirs on the worker or client (C-R2).
+ *
+ * Every chain is composed in list order: the first interceptor is the
+ * outermost and calls `next` to reach the second, the last one reaches the
+ * runtime. Outbound methods should call `next` synchronously, before any
+ * await, so the command is issued where the code issued it.
+ *
+ * Pure JavaScript; it runs inside the isolate.
+ */
+
+/** The workflow function is about to run. */
+interface WorkflowExecuteInput {
+    readonly workflowFn: string;
+    input: Json;
+    /** The start's headers (`WORKFLOW_STARTED.headers`). */
+    readonly headers: Headers;
+}
+/** A signal is about to reach its handler. */
+interface SignalInput {
+    readonly name: string;
+    payload: Json;
+    readonly headers: Headers;
+}
+/** A query is about to reach its handler. */
+interface QueryInput {
+    readonly queryId: string;
+    readonly name: string;
+    args: Json;
+}
+/** An update is about to be validated or handled. */
+interface UpdateInput {
+    readonly updateId: string;
+    readonly name: string;
+    args: Json;
+    readonly headers: Headers;
+}
+/** An activity (`ctx.run` or `ctx.activity`) is about to be scheduled. */
+interface ScheduleActivityInput {
+    readonly activityId: string;
+    readonly kind: 'node' | 'user';
+    /** The node type, or the user activity's name. */
+    readonly name: string;
+    /** The node operation; absent for a user activity. */
+    readonly operation?: string;
+    args: Json;
+    headers: Headers;
+}
+/** A local activity is about to be run. Its headers do not leave the task. */
+interface ScheduleLocalActivityInput {
+    readonly localActivityId: string;
+    readonly nodeType: string;
+    readonly operation: string;
+    args: Json;
+}
+/** A durable timer (`ctx.sleep`) is about to start. */
+interface StartTimerInput {
+    durationMs: number;
+    summary?: string;
+}
+/** A child run is about to start. */
+interface StartChildInput {
+    readonly workflowKey?: string;
+    readonly workflowFn?: string;
+    input: Json;
+    headers: Headers;
+}
+/** A signal to another run is about to be sent. */
+interface SignalRunInput {
+    readonly target: RunTarget;
+    readonly name: string;
+    payload: Json;
+    headers: Headers;
+}
+/** A cancel request to another run is about to be sent. */
+interface CancelRunInput {
+    readonly target: RunTarget;
+}
+/** The run is about to continue as new. */
+interface ContinueAsNewInput {
+    input: Json;
+    options: JsonObject;
+    headers: Headers;
+}
+/** Search attributes are about to be upserted. */
+interface UpsertSearchAttributesInput {
+    attributes: JsonObject;
+}
+/** Context (memo) entries are about to be upserted. */
+interface UpsertContextInput {
+    entries: JsonObject;
+}
+/** Interceptors of what reaches workflow code. */
+interface WorkflowInboundInterceptor {
+    execute?(input: WorkflowExecuteInput, next: (input: WorkflowExecuteInput) => Promise<unknown>): Promise<unknown>;
+    handleSignal?(input: SignalInput, next: (input: SignalInput) => unknown): unknown;
+    /** Synchronous: a query handler must not wait. */
+    handleQuery?(input: QueryInput, next: (input: QueryInput) => unknown): unknown;
+    /** Synchronous: throw to reject the update (nothing is written to history). */
+    validateUpdate?(input: UpdateInput, next: (input: UpdateInput) => void): void;
+    handleUpdate?(input: UpdateInput, next: (input: UpdateInput) => unknown): unknown;
+}
+/** Interceptors of what workflow code issues. */
+interface WorkflowOutboundInterceptor {
+    scheduleActivity?(input: ScheduleActivityInput, next: (input: ScheduleActivityInput) => Promise<unknown>): Promise<unknown>;
+    scheduleLocalActivity?(input: ScheduleLocalActivityInput, next: (input: ScheduleLocalActivityInput) => Promise<unknown>): Promise<unknown>;
+    startTimer?(input: StartTimerInput, next: (input: StartTimerInput) => Promise<void>): Promise<void>;
+    startChild?(input: StartChildInput, next: (input: StartChildInput) => Promise<unknown>): Promise<unknown>;
+    signalRun?(input: SignalRunInput, next: (input: SignalRunInput) => Promise<void>): Promise<void>;
+    cancelRun?(input: CancelRunInput, next: (input: CancelRunInput) => Promise<void>): Promise<void>;
+    sideEffect?(input: Record<string, never>, next: () => Json): Json;
+    continueAsNew?(input: ContinueAsNewInput, next: (input: ContinueAsNewInput) => Promise<never>): Promise<never>;
+    upsertSearchAttributes?(input: UpsertSearchAttributesInput, next: (input: UpsertSearchAttributesInput) => void): void;
+    upsertContext?(input: UpsertContextInput, next: (input: UpsertContextInput) => void): void;
+    /** Attributes added to every `ctx.log` line's data. */
+    getLogAttributes?(input: Record<string, Json>, next: (input: Record<string, Json>) => Record<string, Json>): Record<string, Json>;
+}
+/** The workflow interceptors of a bundle. */
+interface WorkflowInterceptors {
+    inbound?: WorkflowInboundInterceptor[];
+    outbound?: WorkflowOutboundInterceptor[];
+}
+/** Makes the interceptors of one workflow task. */
+type WorkflowInterceptorsFactory = () => WorkflowInterceptors;
+declare const INTERCEPTORS_MARKER = "fluidgrids.workflow-interceptors";
+/** A factory marked by {@link workflowInterceptors}. */
+interface MarkedInterceptorsFactory {
+    readonly __fluidgrids: typeof INTERCEPTORS_MARKER;
+    readonly factory: WorkflowInterceptorsFactory;
+}
+/**
+ * Declare the workflow interceptors of a bundle; export the value as
+ * `interceptors` from any module.
+ */
+declare function workflowInterceptors(factory: WorkflowInterceptorsFactory): MarkedInterceptorsFactory;
+/** The factory of an `interceptors` export, or undefined when the value is not one. */
+declare function interceptorsFactoryOf(value: unknown): WorkflowInterceptorsFactory | undefined;
+/** Run every factory and concatenate their lists, in factory order. */
+declare function resolveWorkflowInterceptors(factories: readonly WorkflowInterceptorsFactory[]): Required<WorkflowInterceptors>;
+/**
+ * Compose `method` of each interceptor around `terminal`, first interceptor
+ * outermost. Interceptors without the method are skipped.
+ */
+declare function compose<I, O, T extends object>(interceptors: readonly T[], method: keyof T, terminal: (input: I) => O): (input: I) => O;
+
+export { type CancelRunInput as C, INTERCEPTORS_MARKER as I, type MarkedInterceptorsFactory as M, type QueryInput as Q, type ScheduleActivityInput as S, type UpdateInput as U, type WorkflowExecuteInput as W, type ContinueAsNewInput as a, type ScheduleLocalActivityInput as b, type SignalInput as c, type SignalRunInput as d, type StartChildInput as e, type StartTimerInput as f, type UpsertContextInput as g, type UpsertSearchAttributesInput as h, type WorkflowInboundInterceptor as i, type WorkflowInterceptors as j, type WorkflowInterceptorsFactory as k, type WorkflowOutboundInterceptor as l, compose as m, interceptorsFactoryOf as n, resolveWorkflowInterceptors as r, workflowInterceptors as w };

package/dist/interceptors-CqkNZVfI.d.cts

@@ -0,0 +1,159 @@
+import { a as Json, J as JsonObject } from './types-V7jEEUaL.cjs';
+import { ad as RunTarget, M as Headers } from './types-Bv2i4cBX.cjs';
+
+/**
+ * Interceptors (11 §2.10): middleware around what workflow code receives
+ * (inbound) and issues (outbound), and around activity execution. A `headers`
+ * map travels with starts, signals, updates, activities and children, so one
+ * interceptor can hand context (trace ids, tenant hints) to the next one in
+ * another run or on a worker.
+ *
+ * A managed bundle registers workflow interceptors by exporting
+ * `interceptors` (made with {@link workflowInterceptors}, or a plain factory
+ * function) from any module; the factory runs once per workflow task inside
+ * the isolate, so it must be deterministic. Self-hosted workers and clients
+ * register theirs on the worker or client (C-R2).
+ *
+ * Every chain is composed in list order: the first interceptor is the
+ * outermost and calls `next` to reach the second, the last one reaches the
+ * runtime. Outbound methods should call `next` synchronously, before any
+ * await, so the command is issued where the code issued it.
+ *
+ * Pure JavaScript; it runs inside the isolate.
+ */
+
+/** The workflow function is about to run. */
+interface WorkflowExecuteInput {
+    readonly workflowFn: string;
+    input: Json;
+    /** The start's headers (`WORKFLOW_STARTED.headers`). */
+    readonly headers: Headers;
+}
+/** A signal is about to reach its handler. */
+interface SignalInput {
+    readonly name: string;
+    payload: Json;
+    readonly headers: Headers;
+}
+/** A query is about to reach its handler. */
+interface QueryInput {
+    readonly queryId: string;
+    readonly name: string;
+    args: Json;
+}
+/** An update is about to be validated or handled. */
+interface UpdateInput {
+    readonly updateId: string;
+    readonly name: string;
+    args: Json;
+    readonly headers: Headers;
+}
+/** An activity (`ctx.run` or `ctx.activity`) is about to be scheduled. */
+interface ScheduleActivityInput {
+    readonly activityId: string;
+    readonly kind: 'node' | 'user';
+    /** The node type, or the user activity's name. */
+    readonly name: string;
+    /** The node operation; absent for a user activity. */
+    readonly operation?: string;
+    args: Json;
+    headers: Headers;
+}
+/** A local activity is about to be run. Its headers do not leave the task. */
+interface ScheduleLocalActivityInput {
+    readonly localActivityId: string;
+    readonly nodeType: string;
+    readonly operation: string;
+    args: Json;
+}
+/** A durable timer (`ctx.sleep`) is about to start. */
+interface StartTimerInput {
+    durationMs: number;
+    summary?: string;
+}
+/** A child run is about to start. */
+interface StartChildInput {
+    readonly workflowKey?: string;
+    readonly workflowFn?: string;
+    input: Json;
+    headers: Headers;
+}
+/** A signal to another run is about to be sent. */
+interface SignalRunInput {
+    readonly target: RunTarget;
+    readonly name: string;
+    payload: Json;
+    headers: Headers;
+}
+/** A cancel request to another run is about to be sent. */
+interface CancelRunInput {
+    readonly target: RunTarget;
+}
+/** The run is about to continue as new. */
+interface ContinueAsNewInput {
+    input: Json;
+    options: JsonObject;
+    headers: Headers;
+}
+/** Search attributes are about to be upserted. */
+interface UpsertSearchAttributesInput {
+    attributes: JsonObject;
+}
+/** Context (memo) entries are about to be upserted. */
+interface UpsertContextInput {
+    entries: JsonObject;
+}
+/** Interceptors of what reaches workflow code. */
+interface WorkflowInboundInterceptor {
+    execute?(input: WorkflowExecuteInput, next: (input: WorkflowExecuteInput) => Promise<unknown>): Promise<unknown>;
+    handleSignal?(input: SignalInput, next: (input: SignalInput) => unknown): unknown;
+    /** Synchronous: a query handler must not wait. */
+    handleQuery?(input: QueryInput, next: (input: QueryInput) => unknown): unknown;
+    /** Synchronous: throw to reject the update (nothing is written to history). */
+    validateUpdate?(input: UpdateInput, next: (input: UpdateInput) => void): void;
+    handleUpdate?(input: UpdateInput, next: (input: UpdateInput) => unknown): unknown;
+}
+/** Interceptors of what workflow code issues. */
+interface WorkflowOutboundInterceptor {
+    scheduleActivity?(input: ScheduleActivityInput, next: (input: ScheduleActivityInput) => Promise<unknown>): Promise<unknown>;
+    scheduleLocalActivity?(input: ScheduleLocalActivityInput, next: (input: ScheduleLocalActivityInput) => Promise<unknown>): Promise<unknown>;
+    startTimer?(input: StartTimerInput, next: (input: StartTimerInput) => Promise<void>): Promise<void>;
+    startChild?(input: StartChildInput, next: (input: StartChildInput) => Promise<unknown>): Promise<unknown>;
+    signalRun?(input: SignalRunInput, next: (input: SignalRunInput) => Promise<void>): Promise<void>;
+    cancelRun?(input: CancelRunInput, next: (input: CancelRunInput) => Promise<void>): Promise<void>;
+    sideEffect?(input: Record<string, never>, next: () => Json): Json;
+    continueAsNew?(input: ContinueAsNewInput, next: (input: ContinueAsNewInput) => Promise<never>): Promise<never>;
+    upsertSearchAttributes?(input: UpsertSearchAttributesInput, next: (input: UpsertSearchAttributesInput) => void): void;
+    upsertContext?(input: UpsertContextInput, next: (input: UpsertContextInput) => void): void;
+    /** Attributes added to every `ctx.log` line's data. */
+    getLogAttributes?(input: Record<string, Json>, next: (input: Record<string, Json>) => Record<string, Json>): Record<string, Json>;
+}
+/** The workflow interceptors of a bundle. */
+interface WorkflowInterceptors {
+    inbound?: WorkflowInboundInterceptor[];
+    outbound?: WorkflowOutboundInterceptor[];
+}
+/** Makes the interceptors of one workflow task. */
+type WorkflowInterceptorsFactory = () => WorkflowInterceptors;
+declare const INTERCEPTORS_MARKER = "fluidgrids.workflow-interceptors";
+/** A factory marked by {@link workflowInterceptors}. */
+interface MarkedInterceptorsFactory {
+    readonly __fluidgrids: typeof INTERCEPTORS_MARKER;
+    readonly factory: WorkflowInterceptorsFactory;
+}
+/**
+ * Declare the workflow interceptors of a bundle; export the value as
+ * `interceptors` from any module.
+ */
+declare function workflowInterceptors(factory: WorkflowInterceptorsFactory): MarkedInterceptorsFactory;
+/** The factory of an `interceptors` export, or undefined when the value is not one. */
+declare function interceptorsFactoryOf(value: unknown): WorkflowInterceptorsFactory | undefined;
+/** Run every factory and concatenate their lists, in factory order. */
+declare function resolveWorkflowInterceptors(factories: readonly WorkflowInterceptorsFactory[]): Required<WorkflowInterceptors>;
+/**
+ * Compose `method` of each interceptor around `terminal`, first interceptor
+ * outermost. Interceptors without the method are skipped.
+ */
+declare function compose<I, O, T extends object>(interceptors: readonly T[], method: keyof T, terminal: (input: I) => O): (input: I) => O;
+
+export { type CancelRunInput as C, INTERCEPTORS_MARKER as I, type MarkedInterceptorsFactory as M, type QueryInput as Q, type ScheduleActivityInput as S, type UpdateInput as U, type WorkflowExecuteInput as W, type ContinueAsNewInput as a, type ScheduleLocalActivityInput as b, type SignalInput as c, type SignalRunInput as d, type StartChildInput as e, type StartTimerInput as f, type UpsertContextInput as g, type UpsertSearchAttributesInput as h, type WorkflowInboundInterceptor as i, type WorkflowInterceptors as j, type WorkflowInterceptorsFactory as k, type WorkflowOutboundInterceptor as l, compose as m, interceptorsFactoryOf as n, resolveWorkflowInterceptors as r, workflowInterceptors as w };