@aikirun/workflow 0.23.1 → 0.24.0

package/README.md

@@ -32,10 +32,9 @@ Run with a client:
 ```typescript
 import { client } from "@aikirun/client";
 
-// Set AIKI_API_KEY env variable or pass apiKey option
 const aikiClient = client({
 	url: "http://localhost:9850",
-	redis: { host: "localhost", port: 6379 },
+	apiKey: "your-api-key",
 });
 
 const handle = await onboardingWorkflowV1.start(aikiClient, {

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 import { WorkflowName, WorkflowVersionId } from '@aikirun/types/workflow';
-import { Client, Logger, ApiClient } from '@aikirun/types/client';
+import { DistributiveOmit, RequireAtLeastOneProp } from '@aikirun/types/property';
+import { Client, ApiClient } from '@aikirun/types/client';
 import { INTERNAL } from '@aikirun/types/symbols';
-import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowRunAddress, ChildWorkflowRunInfo, WorkflowStartOptions, WorkflowDefinitionOptions } from '@aikirun/types/workflow-run';
+import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowStartOptions, WorkflowDefinitionOptions } from '@aikirun/types/workflow-run';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DurationObject, Duration } from '@aikirun/types/duration';
+import { Logger } from '@aikirun/types/logger';
+import { ReplayManifest } from '@aikirun/types/replay-manifest';
 import { SleepResult } from '@aikirun/types/sleep';
 import { EventSendOptions, EventWaitOptions, EventWaitResult } from '@aikirun/types/event';
 import { Serializable } from '@aikirun/types/serializable';
-import { DistributiveOmit, RequireAtLeastOneProp } from '@aikirun/types/utils';
-import { TaskInfo, TaskAddress } from '@aikirun/types/task';
+import { TaskInfo } from '@aikirun/types/task';
 import { WorkflowRunStateRequest, WorkflowRunTransitionTaskStateRequestV1 } from '@aikirun/types/workflow-run-api';
 import { ScheduleOverlapPolicy, ScheduleActivateOptions, ScheduleId } from '@aikirun/types/schedule';
 
@@ -117,7 +119,7 @@ type WorkflowRunWaitResult<Status extends TerminalWorkflowRunStatus, Output, Tim
  *
  * @template Data - Type of event data (must be JSON serializable)
  * @param params - Optional event configuration
- * @param opts.schema - Optional schema for runtime validation
+ * @param params.schema - Optional schema for runtime validation
  * @returns EventDefinition for use in workflows
  *
  * @example
@@ -176,21 +178,7 @@ interface EventMulticasterBuilder<Data> {
 declare function createEventWaiters<TEvents extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, unknown, TEvents>, eventsDefinition: TEvents, logger: Logger): EventWaiters<TEvents>;
 declare function createEventSenders<TEvents extends EventsDefinition>(api: ApiClient, workflowRunId: string, eventsDefinition: TEvents, logger: Logger): EventSenders<TEvents>;
 
-/** biome-ignore-all lint/style/noNonNullAssertion: Manifest boundaries are tracked, hence, we never exceed array boundaries */
-
-interface ReplayManifest {
-    consumeNextTask(address: TaskAddress): TaskInfo | undefined;
-    consumeNextChildWorkflowRun(address: WorkflowRunAddress): ChildWorkflowRunInfo | undefined;
-    hasUnconsumedEntries(): boolean;
-    getUnconsumedEntries(): UnconsumedManifestEntries;
-}
-interface UnconsumedManifestEntries {
-    taskIds: string[];
-    childWorkflowRunIds: string[];
-}
-declare function createReplayManifest(run: WorkflowRun): ReplayManifest;
-
-interface WorkflowRunContext<Input, AppContext, TEvents extends EventsDefinition> {
+interface WorkflowRunContext<Input, AppContext, TEvents extends EventsDefinition = EventsDefinition> {
     id: WorkflowRunId;
     name: WorkflowName;
     versionId: WorkflowVersionId;
@@ -255,7 +243,7 @@ interface ChildWorkflowRunWaitOptions<Timed extends boolean> {
 interface WorkflowVersionParams<Input, Output, AppContext, TEvents extends EventsDefinition> {
     handler: (run: Readonly<WorkflowRunContext<Input, AppContext, TEvents>>, input: Input, context: AppContext) => Promise<Output>;
     events?: TEvents;
-    opts?: WorkflowDefinitionOptions;
+    options?: WorkflowDefinitionOptions;
     schema?: RequireAtLeastOneProp<{
         input?: StandardSchemaV1<Input>;
         output?: StandardSchemaV1<Output>;
@@ -275,28 +263,8 @@ interface WorkflowVersion<Input, Output, AppContext, TEvents extends EventsDefin
         handler: (run: WorkflowRunContext<Input, AppContext, TEvents>, input: Input, context: AppContext) => Promise<void>;
     };
 }
-declare class WorkflowVersionImpl<Input, Output, AppContext, TEvents extends EventsDefinition> implements WorkflowVersion<Input, Output, AppContext, TEvents> {
-    readonly name: WorkflowName;
-    readonly versionId: WorkflowVersionId;
-    private readonly params;
-    readonly events: EventMulticasters<TEvents>;
-    readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext, TEvents>[typeof INTERNAL];
-    constructor(name: WorkflowName, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEvents>);
-    with(): WorkflowBuilder<Input, Output, AppContext, TEvents>;
-    start(client: Client<AppContext>, ...args: Input extends void ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    startWithOpts(client: Client<AppContext>, startOpts: WorkflowStartOptions, ...args: Input extends void ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    startAsChild(parentRun: WorkflowRunContext<unknown, AppContext, EventsDefinition>, ...args: Input extends void ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    startAsChildWithOpts(parentRun: WorkflowRunContext<unknown, AppContext, EventsDefinition>, startOpts: WorkflowStartOptions, ...args: Input extends void ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    private throwNonDeterminismError;
-    getHandleById(client: Client<AppContext>, runId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    getHandleByReferenceId(client: Client<AppContext>, referenceId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    private handler;
-    private tryExecuteWorkflow;
-    private assertRetryAllowed;
-    private parse;
-    private createFailedState;
-    private createAwaitingRetryState;
-}
+type AnyWorkflowVersion = WorkflowVersion<any, any, any, any>;
+type UnknownWorkflowVersion = WorkflowVersion<unknown, unknown, unknown>;
 interface WorkflowBuilder<Input, Output, AppContext, TEvents extends EventsDefinition> {
     opt<Path extends PathFromObject<WorkflowStartOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowStartOptions, Path>): WorkflowBuilder<Input, Output, AppContext, TEvents>;
     start: WorkflowVersion<Input, Output, AppContext, TEvents>["start"];
@@ -304,17 +272,42 @@ interface WorkflowBuilder<Input, Output, AppContext, TEvents extends EventsDefin
 }
 
 declare function workflowRegistry(): WorkflowRegistry;
-type Workflow$1 = WorkflowVersion<unknown, unknown, unknown>;
 interface WorkflowRegistry {
-    add: (workflow: Workflow$1) => WorkflowRegistry;
-    addMany: (workflows: Workflow$1[]) => WorkflowRegistry;
-    remove: (workflow: Workflow$1) => WorkflowRegistry;
-    removeMany: (workflows: Workflow$1[]) => WorkflowRegistry;
+    add: (workflow: UnknownWorkflowVersion) => WorkflowRegistry;
+    addMany: (workflows: UnknownWorkflowVersion[]) => WorkflowRegistry;
+    remove: (workflow: UnknownWorkflowVersion) => WorkflowRegistry;
+    removeMany: (workflows: UnknownWorkflowVersion[]) => WorkflowRegistry;
     removeAll: () => WorkflowRegistry;
-    getAll(): Workflow$1[];
-    get: (name: WorkflowName, versionId: WorkflowVersionId) => Workflow$1 | undefined;
+    getAll(): UnknownWorkflowVersion[];
+    get: (name: WorkflowName, versionId: WorkflowVersionId) => UnknownWorkflowVersion | undefined;
 }
 
+interface ExecuteWorkflowParams<AppContext> {
+    client: Client<AppContext>;
+    workflowRun: WorkflowRun;
+    workflowVersion: UnknownWorkflowVersion;
+    logger: Logger;
+    options: Required<WorkflowExecutionOptions>;
+    heartbeat?: () => Promise<void>;
+}
+interface WorkflowExecutionOptions {
+    heartbeatIntervalMs?: number;
+    /**
+     * Threshold for spinning vs persisting task retry delays (default: 10ms).
+     *
+     * Delays <= threshold: In-memory wait (fast, no task history entry)
+     * Delays > threshold: Server state transition (recorded in task history)
+     *
+     * Set to 0 to record all task delays in transition history.
+     */
+    spinThresholdMs?: number;
+}
+declare function executeWorkflowRun<AppContext>(params: ExecuteWorkflowParams<AppContext>): Promise<boolean>;
+
+/** biome-ignore-all lint/style/noNonNullAssertion: Manifest boundaries are tracked, hence, we never exceed array boundaries */
+
+declare function createReplayManifest(run: WorkflowRun): ReplayManifest;
+
 declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unknown>, logger: Logger): (name: string, duration: Duration) => Promise<SleepResult>;
 
 interface CronScheduleParams {
@@ -345,6 +338,8 @@ type ScheduleDefinition = ScheduleParams & {
 };
 declare function schedule(params: ScheduleParams): ScheduleDefinition;
 
+declare function getSystemWorkflows(api: ApiClient): AnyWorkflowVersion[];
+
 /**
  * Defines a durable workflow with versioning and multiple task execution.
  *
@@ -400,9 +395,9 @@ interface Workflow {
     name: WorkflowName;
     v: <Input extends Serializable, Output extends Serializable, AppContext = null, TEvents extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEvents>) => WorkflowVersion<Input, Output, AppContext, TEvents>;
     [INTERNAL]: {
-        getAllVersions: () => WorkflowVersion<unknown, unknown, unknown>[];
-        getVersion: (versionId: WorkflowVersionId) => WorkflowVersion<unknown, unknown, unknown> | undefined;
+        getAllVersions: () => UnknownWorkflowVersion[];
+        getVersion: (versionId: WorkflowVersionId) => UnknownWorkflowVersion | undefined;
     };
 }
 
-export { type EventDefinition, type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ReplayManifest, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createReplayManifest, createSleeper, event, schedule, workflow, workflowRegistry, workflowRunHandle };
+export { type AnyWorkflowVersion, type EventDefinition, type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ExecuteWorkflowParams, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Workflow, type WorkflowExecutionOptions, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, type WorkflowVersionParams, createEventSenders, createEventWaiters, createReplayManifest, createSleeper, event, executeWorkflowRun, getSystemWorkflows, schedule, workflow, workflowRegistry, workflowRunHandle };