@temelj/workflow 0.0.0-alpha.1

package/dist/types/client.d.mts

@@ -0,0 +1,270 @@
+import { RunId } from "./run-id.mjs";
+import { CleanupMarkerRecord, CleanupRunsOptions, CleanupRunsResult, RetentionPolicyOptions } from "./cleanup.mjs";
+import { PageOptions, WorkflowPage } from "./pagination.mjs";
+import { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleConfig, ScheduleId, ScheduleRecord, TickSchedulesOptions, TickSchedulesResult } from "./schedule.mjs";
+import { WorkflowMissingImplementationRetryConfig } from "./retry.mjs";
+import { WorkflowDefinition, WorkflowHandler, WorkflowImplementation, WorkflowStartTarget } from "./definition.mjs";
+import { HookInspection, ResumeHookOptions, ResumeWebhookOptions } from "./hook.mjs";
+import { AcquireLockOptions, LockRecord, ReleaseLockOptions, ReleaseStaleLockOptions } from "./lock.mjs";
+import { WorkflowListRunsOptions, WorkflowListRunsPageOptions, WorkflowListStepAttemptsPageOptions } from "./run-list.mjs";
+import { BroadcastMessageChannelOptions, BroadcastMessageInput, BroadcastMessageResult, MessageChannel, SendMessageChannelOptions, SendMessageInput } from "./message.mjs";
+import { StreamIdOrName } from "./stream-id.mjs";
+import { FollowStreamOptions, ReadStreamOptions, ReadStreamPageOptions, StreamChunk, StreamInfo, StreamPage, StreamState, StreamUpdate, WaitStreamOptions } from "./stream.mjs";
+import { WorkflowRecoverySummary, WorkflowRecoverySummaryOptions, WorkflowRunSummary, WorkflowRunSummaryOptions } from "./summary.mjs";
+import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord, WorkflowStepAttemptSummary } from "./step-attempts.mjs";
+import { WorkerId } from "./worker-id.mjs";
+import { Timeline } from "./timeline.mjs";
+import { ResultOptions } from "./result.mjs";
+import { WorkflowAttributePatch, WorkflowRunRecord, WorkflowRunStatus } from "./run.mjs";
+import { EventRecord } from "./events.mjs";
+import { ScheduleNextOptions, WorkflowBatchStartItem, WorkflowMarkRunPermanentlyFailedOptions, WorkflowReleaseStaleLeaseOptions, WorkflowRerunOptions, WorkflowRescheduleRunOptions, WorkflowRetryFailedRunOptions, WorkflowRunArguments, WorkflowStartOptions } from "./run-options.mjs";
+import { WorkflowWakeDueRunsOptions, WorkflowWorker, WorkflowWorkerRunFilterOptions, WorkflowWorkerRunResult } from "./worker.mjs";
+//#region src/types/client.d.ts
+/** Function shape emitted by the directive compiler for workflow and step functions. */
+type CompiledWorkflowFunction<TArgs extends readonly unknown[], TOutput> = (...args: TArgs) => Promise<TOutput> | TOutput;
+/** Client-level handle for awaiting output and inspecting a workflow run. */
+interface WorkflowRunHandle<TOutput = unknown> {
+  /** ID of the workflow run represented by this handle. */
+  readonly runId: RunId;
+  /** Workflow definition name stored on the run. */
+  readonly workflowName: string;
+  /** Workflow version stored on the run, when one was resolved. */
+  readonly workflowVersion?: string;
+  /** Returns the latest run record. */
+  getRun(): Promise<WorkflowRunRecord>;
+  /** Returns the latest run status. */
+  status(): Promise<WorkflowRunStatus>;
+  /** Returns all durable events recorded for the run. */
+  events(): Promise<readonly EventRecord[]>;
+  /** Returns a timeline projection of the run's event history. */
+  timeline(): Promise<Timeline>;
+  /** Waits for and returns the completed workflow output. */
+  result(options?: ResultOptions): Promise<TOutput>;
+  /** Returns metadata for a durable stream on this run. */
+  getStreamInfo(streamIdOrName: StreamIdOrName): Promise<StreamInfo>;
+  /** Follows durable stream updates from this run. */
+  followStream<TChunk = unknown>(streamIdOrName: StreamIdOrName, options?: FollowStreamOptions): AsyncIterable<StreamUpdate<TChunk>>;
+  /** Waits until a durable stream exists on this run. */
+  waitForStream(streamIdOrName: StreamIdOrName, options?: WaitStreamOptions): Promise<StreamInfo | undefined>;
+  /** Waits for the next durable stream chunk after an index. */
+  waitForStreamChunk<TChunk = unknown>(streamIdOrName: StreamIdOrName, afterIndex: number, options?: WaitStreamOptions): Promise<StreamChunk<TChunk> | undefined>;
+  /** Waits until a durable stream is closed or failed. */
+  waitForStreamTerminal(streamIdOrName: StreamIdOrName, options?: WaitStreamOptions): Promise<StreamInfo | undefined>;
+  /** Reads all currently stored chunks for a durable stream. */
+  readStream<TChunk = unknown>(streamIdOrName: StreamIdOrName, options?: ReadStreamOptions): Promise<StreamState<TChunk>>;
+  /** Reads one page of currently stored chunks for a durable stream. */
+  readStreamPage<TChunk = unknown>(streamIdOrName: StreamIdOrName, options?: ReadStreamPageOptions): Promise<StreamPage<TChunk>>;
+  /** Moves the run back to pending at an optional new availability time. */
+  reschedule(options?: WorkflowRescheduleRunOptions): Promise<WorkflowRunRecord>;
+  /** Releases this run's worker lease when it is stale. */
+  releaseStaleLease(options?: WorkflowReleaseStaleLeaseOptions): Promise<WorkflowRunRecord>;
+  /** Retries this failed run. */
+  retryFailed(options?: WorkflowRetryFailedRunOptions): Promise<WorkflowRunRecord>;
+  /** Marks this run as permanently failed with an operator reason. */
+  markPermanentlyFailed(options: WorkflowMarkRunPermanentlyFailedOptions): Promise<WorkflowRunRecord>;
+  /** Replaces this run's metadata value. */
+  setMetadata(metadata: unknown): Promise<WorkflowRunRecord>;
+  /** Applies an attribute patch to this run. */
+  setAttributes(attributes: WorkflowAttributePatch): Promise<WorkflowRunRecord>;
+  /** Cancels this run if it has not already reached a terminal status. */
+  cancel(): Promise<WorkflowRunRecord>;
+}
+/** Runnable wrapper that starts a workflow definition through a bound client. */
+interface WorkflowRunnable<TInput = unknown, TOutput = unknown, TRawInput = TInput> {
+  /** Workflow definition that will be started by run. */
+  readonly definition: WorkflowDefinition<TInput, TOutput, TRawInput>;
+  /** Starts the workflow through the bound client and returns a run handle. */
+  run(...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+}
+/** Describes the workflow client contract. */
+interface WorkflowClient {
+  /** Grouped run inspection and history operations. */
+  readonly runs: WorkflowClientRunsApi;
+  /** Grouped administrative run maintenance operations. */
+  readonly admin: WorkflowClientAdminApi;
+  /** Grouped schedule management operations. */
+  readonly schedules: WorkflowClientSchedulesApi;
+  /** Grouped workflow lock operations. */
+  readonly locks: WorkflowClientLocksApi;
+  /** Grouped external resume hook operations. */
+  readonly hooks: WorkflowClientHooksApi;
+  /** Grouped durable stream read operations. */
+  readonly streams: WorkflowClientStreamsApi;
+  /** Grouped message send operations. */
+  readonly messages: WorkflowClientMessagesApi;
+  /** Grouped worker creation and wake operations. */
+  readonly workers: WorkflowClientWorkersApi;
+  /** Flushes resources owned by the underlying engine when it supports explicit shutdown. */
+  close(): Promise<void>;
+  /** Registers a workflow implementation in the client's registry. */
+  implementWorkflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowImplementation<TInput, TOutput, TRawInput>;
+  /** Registers an existing workflow implementation in the client's registry. */
+  register<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>): void;
+  /** Registers a workflow implementation and returns a client-bound runnable. */
+  workflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowRunnable<TInput, TOutput, TRawInput>;
+}
+/** Describes the workflow client runs API contract. */
+interface WorkflowClientRunsApi {
+  /** Starts one workflow run and returns a typed handle. */
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+  /** Starts multiple workflow runs for the same definition. */
+  startBatch<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, items: readonly WorkflowBatchStartItem<TRawInput>[]): Promise<readonly WorkflowRunHandle<TOutput>[]>;
+  /** Returns a workflow run by ID, if it exists. */
+  get(runId: RunId): Promise<WorkflowRunRecord | undefined>;
+  /** Returns all durable events recorded for a run. */
+  events(runId: RunId): Promise<readonly EventRecord[]>;
+  /** Lists one page of durable events recorded for a run. */
+  eventsPage(runId: RunId, options?: PageOptions): Promise<WorkflowPage<EventRecord>>;
+  /** Lists workflow runs matching optional filters. */
+  list(options?: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+  /** Lists one page of workflow runs matching optional filters. */
+  page(options?: WorkflowListRunsPageOptions): Promise<WorkflowPage<WorkflowRunRecord>>;
+  /** Counts workflow runs matching optional filters. */
+  count(options?: WorkflowListRunsOptions): Promise<number>;
+  /** Returns aggregate run metrics for runs matching optional filters. */
+  summary(options?: WorkflowRunSummaryOptions): Promise<WorkflowRunSummary>;
+  /** Returns recovery-oriented aggregate metrics for runs matching optional filters. */
+  recovery(options?: WorkflowRecoverySummaryOptions): Promise<WorkflowRecoverySummary>;
+  /** Returns a timeline projection for one run. */
+  timeline(runId: RunId): Promise<Timeline>;
+  /** Lists materialized step attempts for a run. */
+  listStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<readonly WorkflowStepAttemptRecord[]>;
+  /** Lists one page of materialized step attempts for a run. */
+  listStepAttemptsPage(runId: RunId, options?: WorkflowListStepAttemptsPageOptions): Promise<WorkflowPage<WorkflowStepAttemptRecord>>;
+  /** Counts materialized step attempts for a run. */
+  countStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<number>;
+  /** Returns aggregate step-attempt metrics for a run. */
+  stepAttemptSummary(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<WorkflowStepAttemptSummary>;
+}
+/** Describes the workflow client admin API contract. */
+interface WorkflowClientAdminApi {
+  /** Deletes terminal run data according to cleanup options. */
+  cleanup(options: CleanupRunsOptions): Promise<CleanupRunsResult>;
+  /** Lists cleanup marker records. */
+  cleanupMarkers(): Promise<readonly CleanupMarkerRecord[]>;
+  /** Deletes terminal run data according to a retention policy. */
+  applyRetentionPolicy(options: RetentionPolicyOptions): Promise<CleanupRunsResult>;
+  /** Creates a new run from an existing run record and returns its handle. */
+  rerun(runId: RunId, options?: WorkflowRerunOptions): Promise<WorkflowRunHandle<unknown>>;
+  /** Moves a run back to pending at an optional new availability time. */
+  reschedule(runId: RunId, options?: WorkflowRescheduleRunOptions): Promise<WorkflowRunRecord>;
+  /** Releases a run's worker lease when it is stale. */
+  releaseStaleLease(runId: RunId, options?: WorkflowReleaseStaleLeaseOptions): Promise<WorkflowRunRecord>;
+  /** Retries a failed workflow run. */
+  retryFailed(runId: RunId, options?: WorkflowRetryFailedRunOptions): Promise<WorkflowRunRecord>;
+  /** Marks a workflow run as permanently failed with an operator reason. */
+  markPermanentlyFailed(runId: RunId, options: WorkflowMarkRunPermanentlyFailedOptions): Promise<WorkflowRunRecord>;
+  /** Replaces a workflow run's metadata value. */
+  updateMetadata(runId: RunId, metadata: unknown): Promise<WorkflowRunRecord>;
+  /** Applies an attribute patch to a workflow run. */
+  setAttributes(runId: RunId, attributes: WorkflowAttributePatch): Promise<WorkflowRunRecord>;
+  /** Cancels a workflow run if it has not already reached a terminal status. */
+  cancel(runId: RunId): Promise<WorkflowRunRecord>;
+}
+/** Describes the workflow client schedules API contract. */
+interface WorkflowClientSchedulesApi {
+  /** Schedules one workflow run at the next interval boundary. */
+  next<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options: ScheduleNextOptions): Promise<WorkflowRunHandle<TOutput>>;
+  /** Creates a recurring workflow schedule. */
+  create<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, options: ScheduleConfig<TInput, TRawInput>): Promise<ScheduleRecord<TInput>>;
+  /** Creates or updates a recurring workflow schedule. */
+  upsert<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, options: ScheduleConfig<TInput, TRawInput>): Promise<ScheduleRecord<TInput>>;
+  /** Returns a schedule by ID, if it exists. */
+  get(scheduleId: ScheduleId): Promise<ScheduleRecord | undefined>;
+  /** Lists schedules matching optional filters. */
+  list(options?: ListSchedulesOptions): Promise<readonly ScheduleRecord[]>;
+  /** Lists one page of schedules matching optional filters. */
+  page(options?: ListSchedulesPageOptions): Promise<WorkflowPage<ScheduleRecord>>;
+  /** Pauses an active schedule. */
+  pause(scheduleId: ScheduleId): Promise<ScheduleRecord>;
+  /** Resumes a paused or archived schedule. */
+  resume(scheduleId: ScheduleId): Promise<ScheduleRecord>;
+  /** Archives a schedule without deleting its record. */
+  archive(scheduleId: ScheduleId): Promise<ScheduleRecord>;
+  /** Marks a schedule as deleted. */
+  delete(scheduleId: ScheduleId): Promise<ScheduleRecord>;
+  /** Starts runs for schedules that are due. */
+  tick(options?: TickSchedulesOptions): Promise<TickSchedulesResult>;
+}
+/** Describes the workflow client locks API contract. */
+interface WorkflowClientLocksApi {
+  /** Acquires a workflow lock. */
+  acquire(key: string, options: AcquireLockOptions): Promise<LockRecord>;
+  /** Returns a workflow lock by key, if it exists. */
+  get(key: string): Promise<LockRecord | undefined>;
+  /** Lists workflow locks. */
+  list(): Promise<readonly LockRecord[]>;
+  /** Releases a workflow lock held by the supplied holder. */
+  release(key: string, options: ReleaseLockOptions): Promise<LockRecord>;
+  /** Releases a workflow lock only when its lease is stale. */
+  releaseStale(key: string, options?: ReleaseStaleLockOptions): Promise<LockRecord>;
+}
+/** Describes the workflow client external hook API contract. */
+interface WorkflowClientHooksApi {
+  /** Completes a pending message-backed external resume hook. */
+  resume(token: string, options?: ResumeHookOptions): Promise<void>;
+  /** Completes a pending webhook-labeled external resume hook. */
+  resumeWebhook(token: string, options?: ResumeWebhookOptions): Promise<void>;
+  /** Disposes a pending message-backed external resume hook. */
+  dispose(token: string): Promise<HookInspection>;
+  /** Disposes a pending webhook-labeled external resume hook. */
+  disposeWebhook(token: string): Promise<HookInspection>;
+  /** Returns inspection data for an external resume hook token. */
+  getByToken(token: string): Promise<HookInspection>;
+}
+/** Describes the workflow client streams API contract. */
+interface WorkflowClientStreamsApi {
+  /** Returns metadata for a durable stream on a run. */
+  getInfo(runId: RunId, streamIdOrName: StreamIdOrName): Promise<StreamInfo>;
+  /** Follows durable stream updates from a run. */
+  follow<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, options?: FollowStreamOptions): AsyncIterable<StreamUpdate<TChunk>>;
+  /** Waits until a durable stream exists on a run. */
+  wait(runId: RunId, streamIdOrName: StreamIdOrName, options?: WaitStreamOptions): Promise<StreamInfo | undefined>;
+  /** Waits for the next durable stream chunk after an index. */
+  waitForChunk<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, afterIndex: number, options?: WaitStreamOptions): Promise<StreamChunk<TChunk> | undefined>;
+  /** Waits until a durable stream is closed or failed. */
+  waitForTerminal(runId: RunId, streamIdOrName: StreamIdOrName, options?: WaitStreamOptions): Promise<StreamInfo | undefined>;
+  /** Reads all currently stored chunks for a durable stream. */
+  read<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, options?: ReadStreamOptions): Promise<StreamState<TChunk>>;
+  /** Reads one page of currently stored chunks for a durable stream. */
+  readPage<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, options?: ReadStreamPageOptions): Promise<StreamPage<TChunk>>;
+}
+/** Describes the workflow client messages API contract. */
+interface WorkflowClientMessagesApi {
+  /** Sends a named message to a workflow run. */
+  send(runId: RunId, options: SendMessageInput): Promise<void>;
+  /** Sends a typed message channel payload to a workflow run. */
+  send<TPayload, TKey = void>(runId: RunId, channel: MessageChannel<TPayload, TKey>, options?: SendMessageChannelOptions<TPayload, TKey>): Promise<void>;
+  /** Broadcasts a named message to runs matching the target options. */
+  broadcast(options: BroadcastMessageInput): Promise<BroadcastMessageResult>;
+  /** Broadcasts a typed message channel payload to runs matching the target options. */
+  broadcast<TPayload, TKey = void>(channel: MessageChannel<TPayload, TKey>, options?: BroadcastMessageChannelOptions<TPayload, TKey>): Promise<BroadcastMessageResult>;
+}
+/** Describes the workflow client worker API contract. */
+interface WorkflowClientWorkersApi {
+  /** Creates a worker bound to this client engine and registry. */
+  create(options?: WorkflowClientWorkerOptions): WorkflowWorker;
+  /** Processes a specific run once by ID. */
+  processRun(runId: RunId, options?: WorkflowClientProcessRunOptions): Promise<void>;
+  /** Processes currently due runs matching optional filters. */
+  wakeDueRuns(options?: WorkflowWakeDueRunsOptions): Promise<WorkflowWorkerRunResult>;
+}
+/** Options for creating a worker from the grouped client worker API. */
+interface WorkflowClientWorkerOptions {
+  readonly workerId?: WorkerId;
+  readonly leaseDuration?: Temporal.Duration;
+  readonly pollInterval?: Temporal.Duration;
+  readonly heartbeatInterval?: Temporal.Duration;
+  readonly stopDrainTimeout?: Temporal.Duration;
+  readonly missingImplementationRetry?: WorkflowMissingImplementationRetryConfig;
+}
+/** Options for processing one run through a client worker facet. */
+interface WorkflowClientProcessRunOptions extends WorkflowWorkerRunFilterOptions {
+  readonly workerId?: string;
+  readonly leaseDuration?: Temporal.Duration;
+  readonly heartbeatInterval?: Temporal.Duration;
+  readonly missingImplementationRetry?: WorkflowMissingImplementationRetryConfig;
+  readonly signal?: AbortSignal;
+}
+//#endregion
+export { CompiledWorkflowFunction, WorkflowClient, WorkflowClientAdminApi, WorkflowClientHooksApi, WorkflowClientLocksApi, WorkflowClientMessagesApi, WorkflowClientProcessRunOptions, WorkflowClientRunsApi, WorkflowClientSchedulesApi, WorkflowClientStreamsApi, WorkflowClientWorkerOptions, WorkflowClientWorkersApi, WorkflowRunHandle, WorkflowRunnable };

package/dist/types/client.mjs

@@ -0,0 +1 @@
+export {};

package/dist/types/common.d.mts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+//#region src/types/common.d.ts
+declare const temporalInstantSchema: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+declare const temporalDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const temporalPositiveDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const temporalPositiveSafeDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const temporalNonNegativeDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const temporalNonNegativeSafeDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const nonBlankStringSchema: z.ZodString;
+declare const nonBlankStringListSchema: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+declare const positiveSafeIntegerSchema: z.ZodNumber;
+declare const nonNegativeSafeIntegerSchema: z.ZodNumber;
+/** Timer delay after validation and runtime clamping. */
+interface TimerDelay {
+  readonly duration: Temporal.Duration;
+  readonly clampedDelay: number;
+}
+//#endregion
+export { TimerDelay, nonBlankStringListSchema, nonBlankStringSchema, nonNegativeSafeIntegerSchema, positiveSafeIntegerSchema, temporalDurationSchema, temporalInstantSchema, temporalNonNegativeDurationSchema, temporalNonNegativeSafeDurationSchema, temporalPositiveDurationSchema, temporalPositiveSafeDurationSchema };

package/dist/types/common.mjs

@@ -0,0 +1,15 @@
+import { durationTotal } from "../utility.mjs";
+import { z } from "zod";
+//#region src/types/common.ts
+const temporalInstantSchema = z.instanceof(Temporal.Instant, { error: "Expected a Temporal.Instant" });
+const temporalDurationSchema = z.instanceof(Temporal.Duration, { error: "Expected a Temporal.Duration" });
+const temporalPositiveDurationSchema = temporalDurationSchema.refine((value) => durationTotal(value) > 0, { error: "Expected a positive duration" });
+const temporalPositiveSafeDurationSchema = temporalPositiveDurationSchema.refine((value) => Number.isSafeInteger(durationTotal(value)), { error: "Expected a positive safe duration" });
+const temporalNonNegativeDurationSchema = temporalDurationSchema.refine((value) => durationTotal(value) >= 0, { error: "Expected a non-negative duration" });
+const temporalNonNegativeSafeDurationSchema = temporalNonNegativeDurationSchema.refine((value) => Number.isSafeInteger(durationTotal(value)), { error: "Expected a non-negative safe duration" });
+const nonBlankStringSchema = z.string().refine((value) => value.trim().length > 0, "Expected a non-blank string");
+const nonBlankStringListSchema = z.array(nonBlankStringSchema).readonly();
+const positiveSafeIntegerSchema = z.number().int().positive();
+const nonNegativeSafeIntegerSchema = z.number().int().nonnegative();
+//#endregion
+export { nonBlankStringListSchema, nonBlankStringSchema, nonNegativeSafeIntegerSchema, positiveSafeIntegerSchema, temporalDurationSchema, temporalInstantSchema, temporalNonNegativeDurationSchema, temporalNonNegativeSafeDurationSchema, temporalPositiveDurationSchema, temporalPositiveSafeDurationSchema };

package/dist/types/definition.d.mts

@@ -0,0 +1,92 @@
+import { WorkflowRetryConfig } from "./retry.mjs";
+import { WorkflowDeterministicApi, WorkflowStepApi } from "./step.mjs";
+import { Schema, SchemaOutput } from "@temelj/standard-schema";
+import { Logger } from "@temelj/log";
+//#region src/types/definition.d.ts
+/** Configuration used to name, version, validate, and retry a workflow definition. */
+interface WorkflowDefinitionConfig<TSchema extends Schema | undefined = undefined> {
+  readonly name: string;
+  readonly version?: string;
+  readonly schema?: TSchema;
+  readonly retry?: WorkflowRetryConfig;
+}
+/** Infers the parsed workflow input type from a schema, falling back when no schema is present. */
+type WorkflowInputFromSchema<TSchema extends Schema | undefined, TFallback> = TSchema extends Schema ? SchemaOutput<TSchema> : TFallback;
+/** Infers the raw workflow input accepted before schema parsing, falling back when no schema is present. */
+type WorkflowRawInputFromSchema<TSchema extends Schema | undefined, TFallback> = TSchema extends Schema<infer TInput, unknown> ? TInput : TFallback;
+/** Durable workflow contract identified by name, optional version, and typed input/output markers. */
+interface WorkflowDefinition<TInput = unknown, TOutput = unknown, TRawInput = TInput> {
+  readonly kind: "definition";
+  readonly config: WorkflowDefinitionConfig<Schema | undefined>;
+  readonly name: string;
+  readonly version?: string;
+  readonly types?: WorkflowDefinitionTypes<TInput, TOutput, TRawInput>;
+}
+/** Compile-time type markers carried by workflow definitions without affecting runtime behavior. */
+interface WorkflowDefinitionTypes<TInput, TOutput, TRawInput> {
+  /** Parsed input type received by the workflow handler. */
+  readonly input: TInput;
+  /** Output type returned by the workflow handler. */
+  readonly output: TOutput;
+  /** Raw input type accepted before schema validation. */
+  readonly rawInput: TRawInput;
+}
+/** Executable workflow implementation that binds a durable definition to a handler. */
+interface WorkflowImplementation<TInput = unknown, TOutput = unknown, TRawInput = TInput> {
+  readonly kind: "implementation";
+  readonly definition: WorkflowDefinition<TInput, TOutput, TRawInput>;
+  readonly config: WorkflowDefinitionConfig<Schema | undefined>;
+  readonly name: string;
+  readonly version?: string;
+  readonly handler: WorkflowHandler<TInput, TOutput>;
+}
+/** Function that runs workflow logic with a replay-safe workflow context. */
+type WorkflowHandler<TInput, TOutput> = (context: WorkflowContext<TInput>) => Promise<TOutput> | TOutput;
+/** Context passed to a workflow handler during execution and replay. */
+interface WorkflowContext<TInput> {
+  /** Parsed workflow input for the current run. */
+  readonly input: TInput;
+  /** Durable command API for workflow code. */
+  readonly step: WorkflowStepApi;
+  /** Replay-safe time, random, ID, and byte sources for workflow orchestration code. */
+  readonly deterministic: WorkflowDeterministicApi;
+  /** Scoped operational logger for workflow orchestration code. */
+  readonly log: Logger;
+  /** Stable identity and creation metadata for the current run. */
+  readonly run: WorkflowRunContext;
+  /** Abort signal for workflow cancellation. */
+  readonly signal: AbortSignal;
+  /** Workflow version stored on the current run, if any. */
+  readonly version: string | undefined;
+}
+/** Stable identity and creation metadata for the currently executing run. */
+interface WorkflowRunContext {
+  readonly id: string;
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly createdAt: Temporal.Instant;
+}
+/** Workflow target accepted by start and schedule APIs. */
+type WorkflowStartTarget<TInput = unknown, TOutput = unknown, TRawInput = TInput> = WorkflowDefinition<TInput, TOutput, TRawInput> | WorkflowImplementation<TInput, TOutput, TRawInput>;
+/** Registry surface required by clients, workers, and runtimes. */
+interface RegistryLike {
+  /** Creates and registers a workflow implementation. */
+  implementWorkflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowImplementation<TInput, TOutput, TRawInput>;
+  /** Registers an existing workflow implementation. */
+  register<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>): void;
+  /** Returns the implementation registered for a definition, if present. */
+  get<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>): WorkflowImplementation<TInput, TOutput, TRawInput> | undefined;
+  /** Returns the implementation registered for a workflow name and optional version. */
+  getByName(name: string, version?: string): WorkflowImplementation<unknown, unknown> | undefined;
+  /** Returns the latest registered implementation for a workflow name. */
+  latest(name: string): WorkflowImplementation<unknown, unknown> | undefined;
+}
+/** In-memory workflow registry contract. */
+interface Registry extends RegistryLike {
+  /** Returns all registered workflow implementations. */
+  entries(): readonly WorkflowImplementation<unknown, unknown>[];
+  /** Returns the latest registered implementation for a workflow name. */
+  latest(name: string): WorkflowImplementation<unknown, unknown> | undefined;
+}
+//#endregion
+export { Registry, RegistryLike, WorkflowContext, WorkflowDefinition, WorkflowDefinitionConfig, WorkflowDefinitionTypes, WorkflowHandler, WorkflowImplementation, WorkflowInputFromSchema, WorkflowRawInputFromSchema, WorkflowRunContext, WorkflowStartTarget };

package/dist/types/definition.mjs

@@ -0,0 +1 @@
+export {};

package/dist/types/engine-options.d.mts

@@ -0,0 +1,76 @@
+import { RunId } from "./run-id.mjs";
+import { Telemetry } from "./telemetry.mjs";
+import { WorkflowLifecycleCallback } from "./run.mjs";
+import { WorkflowStorage, WorkflowStore } from "./store.mjs";
+import { Logger } from "@temelj/log";
+//#region src/types/engine-options.d.ts
+/** Options for creating the storage-backed workflow engine. */
+interface CreateWorkflowEngineOptions extends WorkflowExecutionLimits {
+  readonly storage?: WorkflowStorage;
+  readonly store?: WorkflowStore;
+  /**
+   * Clock used for workflow timestamps and the first value recorded by
+   * deterministic time commands.
+   *
+   * Hosts that patch `Date.now()` during workflow execution should route
+   * patched calls through the same durable recording path.
+   */
+  readonly now?: () => Temporal.Instant;
+  readonly createRunId?: () => string;
+  readonly createRecordedId?: (context: WorkflowRecordedIdContext) => string;
+  /**
+   * Creates the first value recorded by deterministic random commands.
+   *
+   * Hosts that patch `Math.random()` during workflow execution should route
+   * patched calls through the same durable recording path.
+   */
+  readonly createDeterministicRandom?: (context: WorkflowDeterministicValueContext) => number;
+  /**
+   * Creates the first value recorded by deterministic UUID commands.
+   *
+   * Hosts that patch `crypto.randomUUID()` during workflow execution should
+   * route patched calls through the same durable recording path.
+   */
+  readonly createDeterministicUuid?: (context: WorkflowDeterministicValueContext) => string;
+  /**
+   * Creates the first value recorded by deterministic byte commands.
+   *
+   * Hosts that patch `crypto.getRandomValues()` during workflow execution
+   * should route patched calls through the same durable recording path.
+   */
+  readonly createDeterministicBytes?: (context: WorkflowDeterministicBytesContext) => Uint8Array;
+  readonly onLifecycleEvent?: WorkflowLifecycleCallback;
+  readonly onRunCompleted?: WorkflowLifecycleCallback;
+  readonly onRunFailed?: WorkflowLifecycleCallback;
+  readonly onRunCanceled?: WorkflowLifecycleCallback;
+  readonly onRunWaiting?: WorkflowLifecycleCallback;
+  readonly onRunRetry?: WorkflowLifecycleCallback;
+  readonly maximumStepAttemptsPerRun?: number;
+  readonly telemetry?: Telemetry | false;
+  readonly logger?: Logger | false;
+}
+/** Runtime limits applied while executing workflows. */
+interface WorkflowExecutionLimits {
+  readonly maximumPersistedValueBytes?: number;
+  readonly maximumEventHistoryEvents?: number;
+  readonly maximumStreamChunks?: number;
+}
+/** Runtime limits that affect persisted value serialization. */
+interface WorkflowEngineSerializationLimits {
+  readonly maximumPersistedValueBytes?: number;
+}
+/** Context passed to custom deterministic ID generators. */
+interface WorkflowRecordedIdContext {
+  readonly runId: RunId;
+  readonly commandId: string;
+  readonly commandName: string;
+  readonly commandCount: number;
+}
+/** Context passed to custom deterministic first-run value generators. */
+type WorkflowDeterministicValueContext = WorkflowRecordedIdContext;
+/** Context passed to custom deterministic byte generators. */
+interface WorkflowDeterministicBytesContext extends WorkflowDeterministicValueContext {
+  readonly length: number;
+}
+//#endregion
+export { CreateWorkflowEngineOptions, WorkflowDeterministicBytesContext, WorkflowDeterministicValueContext, WorkflowEngineSerializationLimits, WorkflowExecutionLimits, WorkflowRecordedIdContext };

package/dist/types/engine-options.mjs

@@ -0,0 +1 @@
+export {};