@temelj/workflow 0.0.0-alpha.1

package/dist/types/store.d.mts

@@ -0,0 +1,254 @@
+import { MessageId } from "./message-id.mjs";
+import { RunId } from "./run-id.mjs";
+import { CleanupMarkerRecord, CleanupRunsOptions, CleanupRunsResult } from "./cleanup.mjs";
+import { PageOptions, WorkflowPage } from "./pagination.mjs";
+import { ListSchedulesOptions, ScheduleId, ScheduleRecord } from "./schedule.mjs";
+import { LockRecord } from "./lock.mjs";
+import { WorkflowListRunsOptions } from "./run-list.mjs";
+import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord } from "./step-attempts.mjs";
+import { WorkflowRunRecord } from "./run.mjs";
+import { EventRecord } from "./events.mjs";
+import { WorkflowWorkerRunFilterOptions } from "./worker.mjs";
+import { Storage, StorageValue, StoredValue } from "@temelj/storage";
+//#region src/types/store.d.ts
+/** Type used for workflow storage values. */
+type WorkflowStorage = Storage<Record<string, StorageValue>, StorageValue, StoredValue>;
+/** Storage value stored for cleanup index entries. */
+type WorkflowCleanupIndexValue = StorageValue;
+/** Storage index entry removed during workflow cleanup. */
+interface WorkflowCleanupIndexKey {
+  readonly key: string;
+  readonly value: WorkflowCleanupIndexValue;
+}
+/** Index entry used to detect duplicate messageId delivery idempotency keys. */
+interface WorkflowMessageIdempotencyIndex {
+  readonly runId: RunId;
+  readonly messageId: MessageId;
+  readonly timestamp: Temporal.Instant;
+}
+/** Options for workflow creation store. */
+interface CreateWorkflowStoreOptions {
+  readonly storage?: WorkflowStorage;
+  readonly namespace?: string;
+}
+/** Exposes workflow store namespace identity. */
+interface WorkflowStoreNamespace {
+  /** Namespace prefix used to isolate workflow records in storage. */
+  readonly namespace: string;
+}
+/** Exposes workflow store storage identity. */
+interface WorkflowStoreStorageContext extends WorkflowStoreNamespace {
+  /** Underlying key-value storage used by the workflow store. */
+  readonly storage: WorkflowStorage;
+}
+/** Shared workflow store metadata needed by default repository implementations. */
+interface WorkflowStoreMetadata extends WorkflowStoreStorageContext, WorkflowStoreCapabilitiesSource {}
+/** Exposes workflow store capability flags. */
+interface WorkflowStoreCapabilitiesSource {
+  /** Store capability flags used by engine services to choose safe coordination code paths. */
+  readonly capabilities: WorkflowStoreCapabilities;
+}
+/** Creates workflow run records. */
+interface WorkflowRunCreationRepository {
+  /** Creates a workflow run record. */
+  createRun(run: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+}
+/** Reads workflow run records. */
+interface WorkflowRunReaderRepository {
+  /** Returns a workflow run by ID, if it exists. */
+  getRun(runId: RunId): Promise<WorkflowRunRecord | undefined>;
+}
+/** Updates workflow run records conditionally. */
+interface WorkflowRunConditionalWriterRepository {
+  /** Replaces a workflow run only when the stored record still matches the current value. */
+  updateRunIfCurrent(current: WorkflowRunRecord, next: WorkflowRunRecord): Promise<WorkflowRunRecord | undefined>;
+}
+/** Updates workflow run records unconditionally. */
+interface WorkflowRunUnconditionalWriterRepository {
+  /** Replaces a workflow run record. */
+  updateRun(run: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+}
+/** Updates workflow run records. */
+interface WorkflowRunWriterRepository extends WorkflowRunUnconditionalWriterRepository, WorkflowRunConditionalWriterRepository {}
+/** Lists workflow run records. */
+interface WorkflowRunListerRepository {
+  /** Lists workflow runs matching optional filters. */
+  listRuns(options?: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+}
+/** Queries workflow run records. */
+interface WorkflowRunQueryRepository extends WorkflowRunReaderRepository, WorkflowRunListerRepository {
+  /** Lists one page of workflow runs matching optional filters. */
+  listRunsPage(options?: WorkflowListRunsOptions & PageOptions): Promise<WorkflowPage<WorkflowRunRecord>>;
+  /** Counts workflow runs matching optional filters. */
+  countRuns(options?: WorkflowListRunsOptions): Promise<number>;
+}
+/** Coordinates workflow run worker leases. */
+interface WorkflowRunLeaseRepository {
+  /** Claims a pending or reclaimable run for a worker. */
+  claimRun(options: WorkflowClaimRunOptions): Promise<WorkflowRunRecord | undefined>;
+  /** Extends the lease for a run already claimed by a worker. */
+  extendRunLease(options: WorkflowExtendRunLeaseOptions): Promise<WorkflowRunRecord | undefined>;
+  /** Releases the lease for a run claimed by a worker. */
+  releaseRunLease(options: WorkflowReleaseRunLeaseOptions): Promise<WorkflowRunRecord | undefined>;
+}
+/** Stores workflow run records and run leases. */
+interface WorkflowRunRepository extends WorkflowRunCreationRepository, WorkflowRunReaderRepository, WorkflowRunUnconditionalWriterRepository, WorkflowRunConditionalWriterRepository, WorkflowRunWriterRepository, WorkflowRunListerRepository, WorkflowRunQueryRepository, WorkflowRunLeaseRepository {}
+/** Stores workflow-scoped idempotency indexes for run creation. */
+interface WorkflowIdempotencyIndex {
+  /** Returns a workflow run by its workflow-scoped idempotency key, if it exists. */
+  getRunByIdempotencyKey(options: WorkflowIdempotencyKeyOptions): Promise<WorkflowRunRecord | undefined>;
+}
+/** Repairs duplicate-delivery idempotency indexes for messages sent to workflow runs. */
+interface WorkflowMessageIdempotencyRepairModel {
+  /** Rebuilds message idempotency indexes for a run from its event history. */
+  repairMessageIdempotencyIndexes(runId: RunId): Promise<readonly WorkflowMessageIdempotencyIndex[]>;
+}
+/** Looks up duplicate-delivery idempotency indexes for messages sent to workflow runs. */
+interface WorkflowMessageIdempotencyIndexLookup {
+  /** Returns true when a message idempotency key is already claimed for a run. */
+  hasMessageIdempotencyKey(runId: RunId, idempotencyKey: string): Promise<boolean>;
+}
+/** Appends durable workflow events. */
+interface WorkflowEventAppender {
+  /** Appends one durable event to a run's history. */
+  appendEvent(runId: RunId, event: EventRecord): Promise<readonly EventRecord[]>;
+}
+/** Appends durable workflow events conditionally on the current run record. */
+interface WorkflowConditionalEventAppender {
+  /** Appends one durable event only when the stored run still matches the current value. */
+  appendEventIfRunCurrent(current: WorkflowRunRecord, event: EventRecord): Promise<readonly EventRecord[] | undefined>;
+}
+/** Reads durable workflow event history. */
+interface WorkflowEventReader {
+  /** Returns all durable events recorded for a run. */
+  getEvents(runId: RunId): Promise<readonly EventRecord[]>;
+}
+/** Waits for durable workflow event history changes. */
+interface WorkflowEventHistoryWatcher {
+  /** Resolves after the durable event history for a run changes or the optional signal aborts. */
+  waitForEventHistoryChange(runId: RunId, options?: WorkflowEventHistoryChangeWaitOptions): Promise<void>;
+}
+/** Stores durable workflow event history. */
+interface WorkflowEventLog extends WorkflowEventAppender, WorkflowConditionalEventAppender, WorkflowEventReader, WorkflowEventHistoryWatcher {}
+/** Options for waiting for durable event history changes. */
+interface WorkflowEventHistoryChangeWaitOptions {
+  readonly signal?: AbortSignal;
+}
+/** Looks up materialized step-attempt read models for runtime coordination. */
+interface WorkflowStepAttemptLookup {
+  /** Lists materialized step attempts for a run. */
+  listStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<readonly WorkflowStepAttemptRecord[]>;
+}
+/** Stores materialized step-attempt read models. */
+interface WorkflowStepAttemptReadModel extends WorkflowStepAttemptLookup {
+  /** Lists one page of materialized step attempts for a run. */
+  listStepAttemptsPage(runId: RunId, options?: WorkflowListStepAttemptsOptions & PageOptions): Promise<WorkflowPage<WorkflowStepAttemptRecord>>;
+  /** Counts materialized step attempts for a run. */
+  countStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<number>;
+  /** Rebuilds materialized step attempts for a run from its event history. */
+  repairStepAttempts(runId: RunId): Promise<readonly WorkflowStepAttemptRecord[]>;
+}
+/** Stores workflow cleanup markers and terminal-run cleanup operations. */
+interface WorkflowCleanupRepository {
+  /** Deletes terminal run data according to cleanup options. */
+  cleanupRuns(options: CleanupRunsOptions): Promise<CleanupRunsResult>;
+  /** Lists cleanup marker records. */
+  listCleanupMarkers(): Promise<readonly CleanupMarkerRecord[]>;
+}
+/** Creates workflow schedule records. */
+interface WorkflowScheduleCreationRepository {
+  /** Creates a workflow schedule record. */
+  createSchedule<TInput = StorageValue>(schedule: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput>>;
+}
+/** Reads workflow schedule records. */
+interface WorkflowScheduleReaderRepository {
+  /** Returns a workflow schedule by ID, if it exists. */
+  getSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord | undefined>;
+}
+/** Updates workflow schedule records conditionally. */
+interface WorkflowScheduleConditionalWriterRepository {
+  /** Replaces a schedule only when the stored record still matches the current value. */
+  updateScheduleIfCurrent<TInput = StorageValue>(current: ScheduleRecord, next: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput> | undefined>;
+}
+/** Lists workflow schedule records. */
+interface WorkflowScheduleListerRepository {
+  /** Lists workflow schedules matching optional filters. */
+  listSchedules(options?: ListSchedulesOptions): Promise<readonly ScheduleRecord[]>;
+}
+/** Queries workflow schedule records. */
+interface WorkflowScheduleQueryRepository extends WorkflowScheduleListerRepository {
+  /** Lists one page of workflow schedules matching optional filters. */
+  listSchedulesPage(options?: ListSchedulesOptions & PageOptions): Promise<WorkflowPage<ScheduleRecord>>;
+}
+/** Stores workflow schedules. */
+interface WorkflowScheduleRepository extends WorkflowScheduleCreationRepository, WorkflowScheduleReaderRepository, WorkflowScheduleConditionalWriterRepository, WorkflowScheduleQueryRepository {}
+/** Reads workflow lock records. */
+interface WorkflowLockReaderRepository {
+  /** Returns a workflow lock by key, if it exists. */
+  getLock(key: string): Promise<LockRecord | undefined>;
+}
+/** Lists workflow lock records. */
+interface WorkflowLockListerRepository {
+  /** Lists workflow locks. */
+  listLocks(): Promise<readonly LockRecord[]>;
+}
+/** Updates workflow lock records conditionally. */
+interface WorkflowLockConditionalWriterRepository {
+  /** Replaces or creates a lock only when the stored record still matches the current value. */
+  updateLockIfCurrent(current: LockRecord | undefined, next: LockRecord): Promise<LockRecord | undefined>;
+}
+/** Stores workflow lock records. */
+interface WorkflowLockRepository extends WorkflowLockReaderRepository, WorkflowLockListerRepository, WorkflowLockConditionalWriterRepository {}
+/** Describes the full workflow store contract implemented by the default store. */
+interface WorkflowStore extends WorkflowStoreMetadata, WorkflowRunRepository, WorkflowIdempotencyIndex, WorkflowMessageIdempotencyIndexLookup, WorkflowMessageIdempotencyRepairModel, WorkflowEventLog, WorkflowStepAttemptReadModel, WorkflowCleanupRepository, WorkflowScheduleRepository, WorkflowLockRepository {}
+/** Describes the workflow store capabilities contract. */
+interface WorkflowStoreCapabilities {
+  readonly conditionalWrites: boolean;
+  readonly conditionalRunClaims: boolean;
+  readonly conditionalRunUpdates: boolean;
+  readonly conditionalRunLeaseExtensions: boolean;
+  readonly conditionalRunLeaseReleases: boolean;
+  readonly conditionalEventAppends: boolean;
+  readonly conditionalStepAttemptMaterialization: boolean;
+  readonly atomicRunCreation: boolean;
+  readonly atomicEventAndStepAttemptMaterialization: boolean;
+  readonly messageIdempotencyIndexes: boolean;
+  readonly indexedRunQueries: boolean;
+  readonly indexedRunCounts: boolean;
+  readonly indexedClaimableRunQueries: boolean;
+  readonly indexedStepAttemptQueries: boolean;
+  readonly indexedScheduleQueries: boolean;
+  readonly indexedLockQueries: boolean;
+  readonly rollsBackEventsOnMaterializationFailure: boolean;
+  readonly reconcilesStepAttemptsFromEvents: boolean;
+}
+/** Options for workflow idempotency key. */
+interface WorkflowIdempotencyKeyOptions {
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly idempotencyKey: string;
+}
+/** Options for workflow claim run. */
+interface WorkflowClaimRunOptions extends WorkflowWorkerRunFilterOptions {
+  readonly runId?: RunId;
+  readonly workerId: string;
+  readonly now: Temporal.Instant;
+  readonly leaseDuration: Temporal.Duration;
+}
+/** Options for workflow extend run lease. */
+interface WorkflowExtendRunLeaseOptions {
+  readonly runId: RunId;
+  readonly workerId: string;
+  readonly attempts?: number;
+  readonly now: Temporal.Instant;
+  readonly leaseDuration: Temporal.Duration;
+}
+/** Options for workflow release run lease. */
+interface WorkflowReleaseRunLeaseOptions {
+  readonly runId: RunId;
+  readonly workerId: string;
+  readonly attempts?: number;
+  readonly now: Temporal.Instant;
+}
+//#endregion
+export { CreateWorkflowStoreOptions, WorkflowClaimRunOptions, WorkflowCleanupIndexKey, WorkflowCleanupIndexValue, WorkflowCleanupRepository, WorkflowConditionalEventAppender, WorkflowEventAppender, WorkflowEventHistoryChangeWaitOptions, WorkflowEventHistoryWatcher, WorkflowEventLog, WorkflowEventReader, WorkflowExtendRunLeaseOptions, WorkflowIdempotencyIndex, WorkflowIdempotencyKeyOptions, WorkflowLockConditionalWriterRepository, WorkflowLockListerRepository, WorkflowLockReaderRepository, WorkflowLockRepository, WorkflowMessageIdempotencyIndex, WorkflowMessageIdempotencyIndexLookup, WorkflowMessageIdempotencyRepairModel, WorkflowReleaseRunLeaseOptions, WorkflowRunConditionalWriterRepository, WorkflowRunCreationRepository, WorkflowRunLeaseRepository, WorkflowRunListerRepository, WorkflowRunQueryRepository, WorkflowRunReaderRepository, WorkflowRunRepository, WorkflowRunUnconditionalWriterRepository, WorkflowRunWriterRepository, WorkflowScheduleConditionalWriterRepository, WorkflowScheduleCreationRepository, WorkflowScheduleListerRepository, WorkflowScheduleQueryRepository, WorkflowScheduleReaderRepository, WorkflowScheduleRepository, WorkflowStepAttemptLookup, WorkflowStepAttemptReadModel, WorkflowStorage, WorkflowStore, WorkflowStoreCapabilities, WorkflowStoreCapabilitiesSource, WorkflowStoreMetadata, WorkflowStoreNamespace, WorkflowStoreStorageContext };

package/dist/types/store.mjs

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

package/dist/types/stream-id.d.mts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+//#region src/types/stream-id.d.ts
+declare const streamIdSchema: z.ZodString;
+type StreamId = string;
+type StreamIdOrName = string;
+//#endregion
+export { StreamId, StreamIdOrName, streamIdSchema };

package/dist/types/stream-id.mjs

@@ -0,0 +1,5 @@
+import { z } from "zod";
+//#region src/types/stream-id.ts
+const streamIdSchema = z.string().refine((value) => value.trim().length > 0, "Expected an ID");
+//#endregion
+export { streamIdSchema };

package/dist/types/stream.d.mts

@@ -0,0 +1,126 @@
+import { RunId } from "./run-id.mjs";
+import { PageOptions, WorkflowPage } from "./pagination.mjs";
+import { StreamId } from "./stream-id.mjs";
+import "./run.mjs";
+import { WorkflowErrorRecord } from "./error.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/types/stream.d.ts
+/** Writable durable stream created by workflow code and persisted in run history. */
+interface Stream<TChunk = unknown> {
+  /** Stable stream ID recorded in workflow history. */
+  readonly id: StreamId;
+  /** User-facing stream name used to look up the stream. */
+  readonly name: string;
+  /** Optional MIME type or content type associated with stream chunks. */
+  readonly contentType?: string;
+  /** Optional persisted stream metadata. */
+  readonly metadata?: unknown;
+  /** Appends one chunk to the stream. */
+  write(chunk: TChunk): Promise<void>;
+  /** Closes the stream successfully. */
+  close(): Promise<void>;
+  /** Fails the stream with an error that readers can observe. */
+  error(error: unknown): Promise<void>;
+}
+/** Options for creating a durable stream from workflow code. */
+interface CreateStreamOptions {
+  readonly id?: StreamId;
+  readonly contentType?: string;
+  readonly metadata?: unknown;
+  readonly maximumChunks?: number;
+}
+/** Options for reading durable stream chunks by index or from the tail. */
+interface ReadStreamOptions {
+  readonly fromIndex?: number;
+  readonly fromTail?: number;
+  readonly maxChunks?: number;
+}
+/** Paginated stream read options combining stream offsets with cursor paging. */
+type ReadStreamPageOptions = ReadStreamOptions & PageOptions;
+/** Options for following stream updates until cancellation or a terminal stream event. */
+interface FollowStreamOptions extends ReadStreamOptions {
+  readonly pollInterval?: Temporal.Duration;
+  readonly signal?: AbortSignal;
+  readonly includeTerminal?: boolean;
+  readonly pageSize?: number;
+}
+/** Options for polling stream availability or terminal state. */
+interface WaitStreamOptions {
+  readonly pollInterval?: Temporal.Duration;
+  readonly signal?: AbortSignal;
+}
+/** Terminal-aware status of a durable workflow stream. */
+type StreamStatus = "open" | "closed" | "failed";
+/** Single ordered value written to a durable workflow stream. */
+interface StreamChunk<TChunk = unknown> {
+  readonly index: number;
+  readonly timestamp: Temporal.Instant;
+  readonly value: TChunk;
+}
+/** Current durable stream state including chunk history and optional terminal error. */
+interface StreamState<TChunk = unknown> {
+  readonly runId: RunId;
+  readonly id: StreamId;
+  readonly name: string;
+  readonly status: StreamStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly contentType?: string;
+  readonly metadata?: StorageValue;
+  readonly chunkCount: number;
+  readonly lastIndex?: number;
+  readonly chunks: readonly StreamChunk<TChunk>[];
+  readonly error?: WorkflowErrorRecord;
+}
+/** Durable stream metadata without chunk contents. */
+interface StreamInfo {
+  readonly runId: RunId;
+  readonly id: StreamId;
+  readonly name: string;
+  readonly status: StreamStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly contentType?: string;
+  readonly metadata?: StorageValue;
+  readonly chunkCount: number;
+  readonly lastIndex?: number;
+  readonly error?: WorkflowErrorRecord;
+}
+/** Paginated durable stream state where chunks are returned as a page. */
+interface StreamPage<TChunk = unknown> {
+  readonly runId: RunId;
+  readonly id: StreamId;
+  readonly name: string;
+  readonly status: StreamStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly contentType?: string;
+  readonly metadata?: StorageValue;
+  readonly chunkCount: number;
+  readonly lastIndex?: number;
+  readonly error?: WorkflowErrorRecord;
+  readonly chunks: WorkflowPage<StreamChunk<TChunk>>;
+}
+/** Incremental update emitted when a durable stream chunk is written. */
+type StreamUpdateKind = "chunk" | "closed" | "failed";
+/** Base contract for incremental durable stream updates. */
+interface StreamUpdateBase {
+  readonly kind: StreamUpdateKind;
+  readonly runId: RunId;
+  readonly streamId: StreamId;
+  readonly streamName: string;
+}
+/** Incremental update emitted when a durable stream chunk is written. */
+type StreamChunkUpdate<TChunk = unknown> = StreamUpdateBase & {
+  readonly kind: "chunk";
+  readonly chunk: StreamChunk<TChunk>;
+};
+/** Incremental update emitted when a durable stream closes or fails. */
+type StreamTerminalUpdate = StreamUpdateBase & {
+  readonly kind: "closed" | "failed";
+  readonly info: StreamInfo;
+};
+/** Incremental durable stream update yielded while following a stream. */
+type StreamUpdate<TChunk = unknown> = StreamChunkUpdate<TChunk> | StreamTerminalUpdate;
+//#endregion
+export { CreateStreamOptions, FollowStreamOptions, ReadStreamOptions, ReadStreamPageOptions, Stream, StreamChunk, StreamChunkUpdate, StreamInfo, StreamPage, StreamState, StreamStatus, StreamTerminalUpdate, StreamUpdate, StreamUpdateBase, StreamUpdateKind, WaitStreamOptions };

package/dist/types/stream.mjs

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