@temelj/workflow 0.0.0-alpha.3 → 0.0.0-alpha.4

package/dist/types/runtime.d.mts

@@ -1,151 +1,39 @@
-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 { WorkflowBundle } from "../bundle.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";
+import { RunId } from "./ids.mjs";
+import { RegistryLike, WorkflowDefinition, WorkflowImplementation } from "./definition.mjs";
+import { ResultOptions } from "./result.mjs";
+import { RunRecord, RunStatus } from "./run.mjs";
+import { RunArguments, StartOptions } from "./run-options.mjs";
+import { CompiledWorkflowFunction } from "./client.mjs";
 //#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 CreateWorkflowRuntimeBaseOptions extends WorkflowExecutionLimits {
-  readonly engine?: WorkflowClientEngine;
-  readonly workerEngine?: WorkflowWorkerEngine;
-  /**
-   * 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;
+/** What every host can do with a run it started. */
+export interface RunHandle<TOutput = unknown> {
+  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;
+  getRun(): Promise<RunRecord>;
+  status(): Promise<RunStatus>;
+  /** Waits for and returns the completed workflow output. */
+  result(options?: ResultOptions): Promise<TOutput>;
+  /** Cancels this run if it has not already reached a terminal status. */
+  cancel(): Promise<RunRecord>;
 }
-/** Options for creating a workflow runtime with either a registry or an immutable bundle. */
-type CreateWorkflowRuntimeOptions = CreateWorkflowRuntimeBaseOptions & ({
-  readonly registry?: RegistryLike;
-  readonly workflows?: never;
-} | {
-  readonly registry?: never;
-  readonly workflows?: WorkflowBundle;
-});
-/** 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;
+/**
+ * What every host offers: the local client and the Cloudflare runtime both implement it, so
+ * application code that sticks to it runs on either. Each host adds its own capabilities on top.
+ */
+export interface WorkflowRuntime extends Pick<RegistryLike, "implementWorkflow" | "register"> {
+  readonly runs: RuntimeRunsApi;
   /** 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>;
+export interface RuntimeRunsApi {
+  /** Starts a run of a definition. */
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowDefinition<TInput, TOutput, TRawInput>, ...args: RunArguments<TRawInput, StartOptions>): Promise<RunHandle<TOutput>>;
+  /** Registers an implementation when needed, then starts a run of it. */
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowImplementation<TInput, TOutput, TRawInput>, ...args: RunArguments<TRawInput, StartOptions>): Promise<RunHandle<TOutput>>;
+  /** Starts a compiled workflow function produced by the workflow transform. */
+  start<TArgs extends readonly unknown[], TOutput>(workflow: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<RunHandle<Awaited<TOutput>>>;
 }
-//#endregion
-export { CreateWorkflowRuntimeOptions, WorkflowRuntime, WorkflowRuntimeLocksApi, WorkflowRuntimeRunsApi, WorkflowRuntimeSchedulesApi, parseWorkflowRuntime, workflowRuntimeSchema };
+//#endregion

package/dist/types/runtime.mjs

@@ -1,21 +1 @@
-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 };
+export {};

package/dist/types/schedule.d.mts

@@ -1,78 +1,21 @@
-import { RunId } from "./run-id.mjs";
+import { RunId } from "./ids.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;
+export type ScheduleId = string;
 /** Lifecycle status of a stored recurring workflow schedule. */
-type ScheduleStatus = "active" | "paused" | "archived" | "deleted";
+export type ScheduleStatus = "active" | "paused" | "archived" | "deleted";
 /** Policy for handling missed recurring schedule fire times. */
-type ScheduleCatchUpPolicy = "skip" | "one" | "all";
+export type ScheduleCatchUpPolicy = "skip" | "one" | "all";
 /** Policy for handling schedule ticks while a prior scheduled run is still active. */
-type ScheduleOverlapPolicy = "allow" | "skip" | "buffer" | "cancel";
+export type ScheduleOverlapPolicy = "allow" | "skip" | "buffer" | "cancel";
 /** Stored recurring workflow schedule state. */
-interface ScheduleRecord<TInput = StorageValue> {
+export interface ScheduleRecord {
   readonly id: ScheduleId;
   readonly namespace: string;
   readonly workflowName: string;
   readonly workflowVersion?: string;
-  readonly input?: TInput;
+  readonly input?: StorageValue;
   readonly context?: StorageValue;
   readonly status: ScheduleStatus;
   readonly every: Temporal.Duration;
@@ -90,7 +33,7 @@ interface ScheduleRecord<TInput = StorageValue> {
   readonly tickCount: number;
 }
 /** Configuration for creating or replacing a recurring workflow schedule. */
-interface ScheduleConfig<TInput = unknown, TRawInput = TInput> {
+export interface ScheduleConfig<TInput = unknown, TRawInput = TInput> {
   readonly id: ScheduleId;
   readonly every: Temporal.Duration;
   readonly input: TRawInput;
@@ -102,26 +45,24 @@ interface ScheduleConfig<TInput = unknown, TRawInput = TInput> {
   readonly maxLateness?: Temporal.Duration;
   readonly overlap?: ScheduleOverlapPolicy;
 }
-/** Filters for listing recurring workflow schedules. */
-interface ListSchedulesOptions {
+export 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;
+export type ListSchedulesPageOptions = ListSchedulesOptions & PageOptions;
 /** Options for advancing due recurring workflow schedules. */
-interface TickSchedulesOptions {
+export interface TickSchedulesOptions {
   readonly now?: Temporal.Instant;
   readonly limit?: number;
 }
 /** Summary returned after advancing due recurring workflow schedules. */
-interface TickSchedulesResult {
+export 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 };
+//#endregion

package/dist/types/schedule.mjs

@@ -1,48 +1 @@
-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 };
+export {};