@temelj/workflow 0.0.0-alpha.1

package/dist/types/runtime.d.mts

@@ -0,0 +1,143 @@
+import { RunId } from "./run-id.mjs";
+import { WorkflowPage } from "./pagination.mjs";
+import { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleConfig, ScheduleId, ScheduleRecord, TickSchedulesOptions, TickSchedulesResult } from "./schedule.mjs";
+import { RegistryLike, WorkflowDefinition, WorkflowHandler, WorkflowImplementation, WorkflowStartTarget } from "./definition.mjs";
+import { AcquireLockOptions, LockRecord, ReleaseLockOptions, ReleaseStaleLockOptions } from "./lock.mjs";
+import { WorkflowListRunsOptions } from "./run-list.mjs";
+import { Telemetry } from "./telemetry.mjs";
+import { WorkflowLifecycleCallback, WorkflowRunRecord } from "./run.mjs";
+import { ScheduleNextOptions, WorkflowRunArguments, WorkflowStartOptions } from "./run-options.mjs";
+import { WorkflowDeterministicBytesContext, WorkflowDeterministicValueContext, WorkflowExecutionLimits, WorkflowRecordedIdContext } from "./engine-options.mjs";
+import { WorkflowClientEngine, WorkflowWorkerEngine } from "./engine.mjs";
+import { CompiledWorkflowFunction, WorkflowClientWorkersApi, WorkflowRunHandle } from "./client.mjs";
+import { z } from "zod";
+import { Logger } from "@temelj/log";
+//#region src/types/runtime.d.ts
+declare const workflowRuntimeSchema: z.ZodObject<{
+  runs: z.ZodObject<{}, z.core.$strip>;
+  schedules: z.ZodObject<{}, z.core.$strip>;
+  locks: z.ZodObject<{}, z.core.$strip>;
+  workers: z.ZodObject<{}, z.core.$strip>;
+  close: z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>;
+  implementWorkflow: z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>;
+  register: z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>;
+  start: z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>;
+}, z.core.$strip>;
+/** Asserts that a value has the minimum shape required by runtime helper functions. */
+declare function parseWorkflowRuntime(value: unknown): asserts value is WorkflowRuntime;
+/** Options for workflow creation runtime. */
+interface CreateWorkflowRuntimeOptions extends WorkflowExecutionLimits {
+  readonly engine?: WorkflowClientEngine;
+  readonly workerEngine?: WorkflowWorkerEngine;
+  readonly registry?: RegistryLike;
+  /**
+   * 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;
+}
+/** Describes the workflow runtime contract. */
+interface WorkflowRuntime {
+  /** Grouped run handle and run listing operations. */
+  readonly runs: WorkflowRuntimeRunsApi;
+  /** Grouped schedule management operations. */
+  readonly schedules: WorkflowRuntimeSchedulesApi;
+  /** Grouped workflow lock operations. */
+  readonly locks: WorkflowRuntimeLocksApi;
+  /** Grouped worker operations. */
+  readonly workers: WorkflowClientWorkersApi;
+  /** Flushes resources owned by this runtime. */
+  close(): Promise<void>;
+  /** 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;
+  /** Starts a registered workflow definition. */
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowDefinition<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+  /** Registers and starts a workflow implementation. */
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowImplementation<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+  /** Starts a compiled workflow function produced by the workflow transform. */
+  start<TArgs extends readonly unknown[], TOutput>(workflow: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<WorkflowRunHandle<Awaited<TOutput>>>;
+}
+/** Describes runtime-level run operations. */
+interface WorkflowRuntimeRunsApi {
+  /** Returns a typed handle for an existing run. */
+  getHandle<TOutput = unknown>(runId: RunId): Promise<WorkflowRunHandle<TOutput>>;
+  /** Lists workflow runs visible to the runtime client. */
+  list(options?: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+}
+/** Describes runtime-level schedule operations. */
+interface WorkflowRuntimeSchedulesApi {
+  /** 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 runtime-level workflow lock operations. */
+interface WorkflowRuntimeLocksApi {
+  /** 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>;
+}
+//#endregion
+export { CreateWorkflowRuntimeOptions, WorkflowRuntime, WorkflowRuntimeLocksApi, WorkflowRuntimeRunsApi, WorkflowRuntimeSchedulesApi, parseWorkflowRuntime, workflowRuntimeSchema };

package/dist/types/runtime.mjs

@@ -0,0 +1,21 @@
+import { WorkflowRuntimeError } from "../errors/runtime.mjs";
+import { z } from "zod";
+//#region src/types/runtime.ts
+const workflowRuntimeObjectPropertySchema = z.object({});
+const workflowRuntimeFunctionPropertySchema = z.custom((value) => typeof value === "function");
+const workflowRuntimeSchema = z.object({
+	runs: workflowRuntimeObjectPropertySchema,
+	schedules: workflowRuntimeObjectPropertySchema,
+	locks: workflowRuntimeObjectPropertySchema,
+	workers: workflowRuntimeObjectPropertySchema,
+	close: workflowRuntimeFunctionPropertySchema,
+	implementWorkflow: workflowRuntimeFunctionPropertySchema,
+	register: workflowRuntimeFunctionPropertySchema,
+	start: workflowRuntimeFunctionPropertySchema
+});
+/** Asserts that a value has the minimum shape required by runtime helper functions. */
+function parseWorkflowRuntime(value) {
+	if (!workflowRuntimeSchema.safeParse(value).success) WorkflowRuntimeError.invalid();
+}
+//#endregion
+export { parseWorkflowRuntime, workflowRuntimeSchema };

package/dist/types/schedule.d.mts

@@ -0,0 +1,127 @@
+import { RunId } from "./run-id.mjs";
+import { PageOptions } from "./pagination.mjs";
+import "./run.mjs";
+import { StorageValue } from "@temelj/storage";
+import { z } from "zod";
+//#region src/types/schedule.d.ts
+declare const scheduleIdSchema: z.ZodString;
+declare const workflowScheduleStatusSchema: z.ZodEnum<{
+  active: "active";
+  archived: "archived";
+  deleted: "deleted";
+  paused: "paused";
+}>;
+declare const workflowScheduleCatchUpPolicySchema: z.ZodEnum<{
+  all: "all";
+  one: "one";
+  skip: "skip";
+}>;
+declare const workflowScheduleOverlapPolicySchema: z.ZodEnum<{
+  allow: "allow";
+  buffer: "buffer";
+  cancel: "cancel";
+  skip: "skip";
+}>;
+declare const workflowSchedulePositiveDurationSchema: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+declare const workflowScheduleRecordSchema: z.ZodObject<{
+  id: z.ZodString;
+  namespace: z.ZodString;
+  workflowName: z.ZodString;
+  workflowVersion: z.ZodOptional<z.ZodString>;
+  input: z.ZodOptional<z.ZodType<StorageValue, unknown, z.core.$ZodTypeInternals<StorageValue, unknown>>>;
+  context: z.ZodOptional<z.ZodType<StorageValue, unknown, z.core.$ZodTypeInternals<StorageValue, unknown>>>;
+  status: z.ZodEnum<{
+    active: "active";
+    archived: "archived";
+    deleted: "deleted";
+    paused: "paused";
+  }>;
+  every: z.ZodCustom<Temporal.Duration, Temporal.Duration>;
+  catchUp: z.ZodEnum<{
+    all: "all";
+    one: "one";
+    skip: "skip";
+  }>;
+  maxCatchUpRuns: z.ZodOptional<z.ZodNumber>;
+  maxLateness: z.ZodOptional<z.ZodCustom<Temporal.Duration, Temporal.Duration>>;
+  overlap: z.ZodEnum<{
+    allow: "allow";
+    buffer: "buffer";
+    cancel: "cancel";
+    skip: "skip";
+  }>;
+  createdAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  updatedAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  nextFireAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  endAt: z.ZodOptional<z.ZodCustom<Temporal.Instant, Temporal.Instant>>;
+  bufferedFireAt: z.ZodOptional<z.ZodCustom<Temporal.Instant, Temporal.Instant>>;
+  lastFireAt: z.ZodOptional<z.ZodCustom<Temporal.Instant, Temporal.Instant>>;
+  lastRunId: z.ZodOptional<z.ZodString>;
+  tickCount: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<0>]>;
+}, z.core.$strip>;
+type ScheduleId = string;
+/** Lifecycle status of a stored recurring workflow schedule. */
+type ScheduleStatus = "active" | "paused" | "archived" | "deleted";
+/** Policy for handling missed recurring schedule fire times. */
+type ScheduleCatchUpPolicy = "skip" | "one" | "all";
+/** Policy for handling schedule ticks while a prior scheduled run is still active. */
+type ScheduleOverlapPolicy = "allow" | "skip" | "buffer" | "cancel";
+/** Stored recurring workflow schedule state. */
+interface ScheduleRecord<TInput = StorageValue> {
+  readonly id: ScheduleId;
+  readonly namespace: string;
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly input?: TInput;
+  readonly context?: StorageValue;
+  readonly status: ScheduleStatus;
+  readonly every: Temporal.Duration;
+  readonly catchUp: ScheduleCatchUpPolicy;
+  readonly maxCatchUpRuns?: number;
+  readonly maxLateness?: Temporal.Duration;
+  readonly overlap: ScheduleOverlapPolicy;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly nextFireAt: Temporal.Instant;
+  readonly endAt?: Temporal.Instant;
+  readonly bufferedFireAt?: Temporal.Instant;
+  readonly lastFireAt?: Temporal.Instant;
+  readonly lastRunId?: RunId;
+  readonly tickCount: number;
+}
+/** Configuration for creating or replacing a recurring workflow schedule. */
+interface ScheduleConfig<TInput = unknown, TRawInput = TInput> {
+  readonly id: ScheduleId;
+  readonly every: Temporal.Duration;
+  readonly input: TRawInput;
+  readonly context?: unknown;
+  readonly from?: Temporal.Instant;
+  readonly endAt?: Temporal.Instant;
+  readonly catchUp?: ScheduleCatchUpPolicy;
+  readonly maxCatchUpRuns?: number;
+  readonly maxLateness?: Temporal.Duration;
+  readonly overlap?: ScheduleOverlapPolicy;
+}
+/** Filters for listing recurring workflow schedules. */
+interface ListSchedulesOptions {
+  readonly status?: ScheduleStatus | readonly ScheduleStatus[];
+  readonly workflowName?: string;
+  readonly workflowVersion?: string;
+  readonly limit?: number;
+}
+/** Paginated filters for listing recurring workflow schedules. */
+type ListSchedulesPageOptions = ListSchedulesOptions & PageOptions;
+/** Options for advancing due recurring workflow schedules. */
+interface TickSchedulesOptions {
+  readonly now?: Temporal.Instant;
+  readonly limit?: number;
+}
+/** Summary returned after advancing due recurring workflow schedules. */
+interface TickSchedulesResult {
+  readonly ticked: number;
+  readonly runIds: readonly RunId[];
+  readonly scheduleIds: readonly ScheduleId[];
+  readonly nextScheduleAt?: Temporal.Instant;
+}
+//#endregion
+export { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleCatchUpPolicy, ScheduleConfig, ScheduleId, ScheduleOverlapPolicy, ScheduleRecord, ScheduleStatus, TickSchedulesOptions, TickSchedulesResult, scheduleIdSchema, workflowScheduleCatchUpPolicySchema, workflowScheduleOverlapPolicySchema, workflowSchedulePositiveDurationSchema, workflowScheduleRecordSchema, workflowScheduleStatusSchema };

package/dist/types/schedule.mjs

@@ -0,0 +1,48 @@
+import { nonBlankStringSchema, positiveSafeIntegerSchema, temporalDurationSchema, temporalInstantSchema } from "./common.mjs";
+import { runIdSchema } from "./run-id.mjs";
+import { workflowPersistedValueSchema } from "./run.mjs";
+import { z } from "zod";
+//#region src/types/schedule.ts
+const scheduleIdSchema = z.string().refine((value) => value.trim().length > 0, "Expected an ID");
+const workflowScheduleStatusSchema = z.enum([
+	"active",
+	"paused",
+	"archived",
+	"deleted"
+]);
+const workflowScheduleCatchUpPolicySchema = z.enum([
+	"skip",
+	"one",
+	"all"
+]);
+const workflowScheduleOverlapPolicySchema = z.enum([
+	"allow",
+	"skip",
+	"buffer",
+	"cancel"
+]);
+const workflowSchedulePositiveDurationSchema = temporalDurationSchema.refine((value) => value.total({ unit: "millisecond" }) > 0, { error: "Expected a positive duration" });
+const workflowScheduleRecordSchema = z.object({
+	id: scheduleIdSchema,
+	namespace: nonBlankStringSchema,
+	workflowName: nonBlankStringSchema,
+	workflowVersion: nonBlankStringSchema.optional(),
+	input: workflowPersistedValueSchema.optional(),
+	context: workflowPersistedValueSchema.optional(),
+	status: workflowScheduleStatusSchema,
+	every: workflowSchedulePositiveDurationSchema,
+	catchUp: workflowScheduleCatchUpPolicySchema,
+	maxCatchUpRuns: positiveSafeIntegerSchema.optional(),
+	maxLateness: workflowSchedulePositiveDurationSchema.optional(),
+	overlap: workflowScheduleOverlapPolicySchema,
+	createdAt: temporalInstantSchema,
+	updatedAt: temporalInstantSchema,
+	nextFireAt: temporalInstantSchema,
+	endAt: temporalInstantSchema.optional(),
+	bufferedFireAt: temporalInstantSchema.optional(),
+	lastFireAt: temporalInstantSchema.optional(),
+	lastRunId: runIdSchema.optional(),
+	tickCount: z.union([positiveSafeIntegerSchema, z.literal(0)])
+});
+//#endregion
+export { scheduleIdSchema, workflowScheduleCatchUpPolicySchema, workflowScheduleOverlapPolicySchema, workflowSchedulePositiveDurationSchema, workflowScheduleRecordSchema, workflowScheduleStatusSchema };