@temelj/workflow 0.0.0-alpha.1

package/dist/store/run.mjs

@@ -0,0 +1,236 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import { WorkflowRunNotFoundError } from "../errors/run.mjs";
+import { isTerminalWorkflowLifecycleEventForRun, isTerminalWorkflowRunStatus, limitWorkflowItems, nextRunAttempt } from "../utility.mjs";
+import { omitUndefined } from "../collection.mjs";
+import "../errors/mod.mjs";
+import { supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { makeRunKey } from "../store-keys.mjs";
+import { isSameWorkflowStorageValue } from "./revision.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableWorkflowRunRecord, parseStoredWorkflowRunRecord, requireReadableStoreRun, requireValidRunTransition } from "./validation.mjs";
+import { rollbackAppendedEventIfCurrent } from "./event-history.mjs";
+import { makeWorkflowRunCursorKey, pageItems } from "../pagination.mjs";
+import { compactWorkflowStoreRecord } from "./compaction.mjs";
+import { matchesWorkflowRunListOptions, queryWorkflowRuns } from "./query.mjs";
+//#region src/store/run.ts
+async function updateRunIfCurrent(storage, namespace, store, current, next) {
+	const runId = current.id;
+	const nextRunId = next.id;
+	if (runId !== nextRunId) WorkflowStateError.runIdMismatch(runId, nextRunId);
+	requireReadableStoreRun(current, namespace);
+	if (next.namespace !== namespace) WorkflowStateError.runNamespaceMismatch(String(next.namespace), namespace);
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const latest = await store.getRun(runId);
+		if (latest === void 0 || !isSameWorkflowStorageValue(omitUndefined(latest), omitUndefined(current))) return;
+		requireValidRunTransition(current, next);
+		const compact = compactWorkflowStoreRecord(next);
+		await storage.set(makeRunKey(namespace, runId), toStorageValue(compact));
+		return compact;
+	}
+	requireValidRunTransition(current, next);
+	const compact = compactWorkflowStoreRecord(next);
+	return await storage.compareAndSet(makeRunKey(namespace, runId), toStorageValue(current), toStorageValue(compact)) ? compact : void 0;
+}
+async function getWorkflowRun(storage, namespace, runId) {
+	const run = await storage.get(makeRunKey(namespace, runId));
+	return isReadableWorkflowRunRecord(run, namespace) ? run : void 0;
+}
+async function listWorkflowRuns(storage, namespace, options) {
+	return limitWorkflowItems(await queryWorkflowRuns(storage, namespace, options, {
+		label: "Workflow run list options",
+		sort: true
+	}), options?.limit);
+}
+async function listWorkflowRunsPage(storage, namespace, options) {
+	return pageItems(await queryWorkflowRuns(storage, namespace, {
+		...options,
+		limit: void 0
+	}, {
+		label: "Workflow run page options",
+		sort: true
+	}), options, "Workflow run page", makeWorkflowRunCursorKey);
+}
+async function countWorkflowRuns(storage, namespace, options) {
+	return (await queryWorkflowRuns(storage, namespace, options, {
+		label: "Workflow run list options",
+		sort: false
+	})).length;
+}
+async function updateWorkflowRun(storage, namespace, store, run) {
+	const runId = run.id;
+	if (run.namespace !== namespace) WorkflowStateError.runNamespaceMismatch(String(run.namespace), namespace);
+	const current = await store.getRun(runId);
+	if (current !== void 0) requireValidRunTransition(current, run);
+	const compact = compactWorkflowStoreRecord(run);
+	await storage.set(makeRunKey(namespace, runId), toStorageValue(compact));
+	return compact;
+}
+async function claimWorkflowRun(storage, namespace, store, options) {
+	const listOptions = claimableWorkflowRunListOptions(options);
+	const run = options.runId === void 0 ? await firstClaimableRun(store, options, listOptions) : await store.getRun(options.runId);
+	if (run === void 0 || !canClaimRun(run, options, listOptions)) return;
+	return await updateRunIfCurrent(storage, namespace, store, run, claimedRunPatch(run, options.workerId, options.now, options.leaseDuration));
+}
+async function extendWorkflowRunLease(storage, namespace, store, options) {
+	const run = await store.getRun(options.runId);
+	if (!isWorkflowRunLeaseHeldByWorker(run, options)) return;
+	return await updateRunIfCurrent(storage, namespace, store, run, extendedRunLeasePatch(run, options.now, options.leaseDuration));
+}
+async function releaseWorkflowRunLease(storage, namespace, store, options) {
+	const run = await store.getRun(options.runId);
+	if (!isWorkflowRunLeaseHeldByWorker(run, options)) return;
+	return await updateRunIfCurrent(storage, namespace, store, run, releaseRunLeasePatch(run, options.now));
+}
+function isSameReadableWorkflowRunRevision(latest, current, namespace) {
+	return latest !== void 0 && isReadableWorkflowRunRecord(latest, namespace) && isSameWorkflowStorageValue(omitUndefined(latest), omitUndefined(current));
+}
+async function isStoredWorkflowRunRevisionCurrent(storage, namespace, currentRun) {
+	return isSameReadableWorkflowRunRevision(await getReadableStoredWorkflowRunValue(storage, namespace, currentRun.id), currentRun, namespace);
+}
+async function getReadableStoredWorkflowRun(storage, namespace, runId) {
+	const run = parseStoredWorkflowRunRecord(await storage.get(makeRunKey(namespace, runId)));
+	return isReadableWorkflowRunRecord(run, namespace) ? run : void 0;
+}
+async function getReadableStoredWorkflowRunValue(storage, namespace, runId) {
+	const run = await storage.get(makeRunKey(namespace, runId));
+	return isReadableWorkflowRunRecord(run, namespace) ? run : void 0;
+}
+async function requireReadableStoredWorkflowRun(storage, namespace, runId) {
+	const run = await getReadableStoredWorkflowRun(storage, namespace, runId);
+	if (run === void 0) WorkflowRunNotFoundError.notFound(runId);
+	return run;
+}
+function shouldRollbackAppendedEventForRun(namespace, run, event) {
+	if (run === void 0 || !isReadableWorkflowRunRecord(run, namespace)) return true;
+	return isTerminalWorkflowRunStatus(run.status) && !isTerminalWorkflowLifecycleEventForRun(run, event);
+}
+function isWorkflowRunStaleForAppend(currentRun, event) {
+	return isTerminalWorkflowRunStatus(currentRun.status) && !isTerminalWorkflowLifecycleEventForRun(currentRun, event);
+}
+async function rollbackAppendedEventIfRunStale(storage, namespace, runId, event, events) {
+	if (!shouldRollbackAppendedEventForRun(namespace, await getReadableStoredWorkflowRunValue(storage, namespace, runId), event)) return false;
+	await rollbackAppendedEventIfCurrent(storage, namespace, runId, events);
+	return true;
+}
+function claimedRunPatch(run, workerId, now, leaseDuration) {
+	const timestamp = now;
+	const lastTransitionReason = isStaleLeaseClaim(run, now) ? "reclaimed" : "claimed";
+	return {
+		...run,
+		status: "running",
+		attempts: nextRunAttempt(run.attempts),
+		idempotencyKey: run.idempotencyKey,
+		parentRunId: run.parentRunId,
+		parentStepId: run.parentStepId,
+		parentStepName: run.parentStepName,
+		parentStepAttempt: run.parentStepAttempt,
+		workerId,
+		createdAt: run.createdAt,
+		updatedAt: timestamp,
+		lastTransitionAt: timestamp,
+		lastTransitionReason,
+		startedAt: run.startedAt ?? timestamp,
+		leaseExpiresAt: now.add(leaseDuration),
+		deadlineAt: run.deadlineAt,
+		availableAt: void 0,
+		retryAt: void 0,
+		retryReason: void 0,
+		retryAttempt: void 0,
+		retryStepId: void 0,
+		retryStepName: void 0,
+		error: void 0,
+		output: void 0,
+		finishedAt: void 0
+	};
+}
+function extendedRunLeasePatch(run, now, leaseDuration) {
+	const timestamp = now;
+	return {
+		...run,
+		idempotencyKey: run.idempotencyKey,
+		parentRunId: run.parentRunId,
+		parentStepId: run.parentStepId,
+		parentStepName: run.parentStepName,
+		parentStepAttempt: run.parentStepAttempt,
+		createdAt: run.createdAt,
+		updatedAt: timestamp,
+		lastTransitionAt: run.lastTransitionAt ?? timestamp,
+		deadlineAt: run.deadlineAt,
+		startedAt: run.startedAt ?? timestamp,
+		leaseExpiresAt: now.add(leaseDuration),
+		retryAt: void 0,
+		retryReason: void 0,
+		retryAttempt: void 0,
+		retryStepId: void 0,
+		retryStepName: void 0,
+		error: void 0,
+		output: void 0,
+		finishedAt: void 0
+	};
+}
+function releaseRunLeasePatch(run, now) {
+	const timestamp = now;
+	return {
+		...run,
+		status: "waiting",
+		idempotencyKey: run.idempotencyKey,
+		parentRunId: run.parentRunId,
+		parentStepId: run.parentStepId,
+		parentStepName: run.parentStepName,
+		parentStepAttempt: run.parentStepAttempt,
+		availableAt: timestamp,
+		createdAt: run.createdAt,
+		updatedAt: timestamp,
+		lastTransitionAt: timestamp,
+		lastTransitionReason: "waiting",
+		deadlineAt: run.deadlineAt,
+		startedAt: run.startedAt ?? timestamp,
+		retryAt: void 0,
+		retryReason: void 0,
+		retryAttempt: void 0,
+		retryStepId: void 0,
+		retryStepName: void 0,
+		error: void 0,
+		output: void 0,
+		finishedAt: void 0,
+		workerId: void 0,
+		leaseExpiresAt: void 0
+	};
+}
+async function firstClaimableRun(store, options, listOptions) {
+	return (await store.listRuns(listOptions)).find((run) => canClaimRun(run, options, listOptions));
+}
+function claimableWorkflowRunListOptions(options) {
+	return {
+		...options,
+		workerId: void 0,
+		availableAtFrom: void 0,
+		availableAtTo: void 0,
+		retryAtFrom: void 0,
+		retryAtTo: void 0,
+		leaseExpiresAtFrom: void 0,
+		leaseExpiresAtTo: void 0
+	};
+}
+function canClaimRun(run, options, listOptions) {
+	if (!matchesClaimableWorkflowRunListOptions(run, listOptions)) return false;
+	if (run.status === "pending" || run.status === "waiting") return run.availableAt === void 0 || Temporal.Instant.compare(run.availableAt, options.now) <= 0;
+	if (run.status !== "running") return false;
+	if (run.workerId === void 0) return true;
+	if (run.leaseExpiresAt === void 0) return true;
+	return Temporal.Instant.compare(run.leaseExpiresAt, options.now) <= 0;
+}
+function isWorkflowRunLeaseHeldByWorker(run, options) {
+	return run !== void 0 && run.status === "running" && run.workerId === options.workerId && (options.attempts === void 0 || run.attempts === options.attempts) && run.leaseExpiresAt !== void 0 && Temporal.Instant.compare(run.leaseExpiresAt, options.now) > 0;
+}
+function matchesClaimableWorkflowRunListOptions(run, listOptions) {
+	return matchesWorkflowRunListOptions(run, listOptions) && (listOptions.retryReason !== void 0 || run.retryReason === void 0);
+}
+function isStaleLeaseClaim(run, now) {
+	if (run.status !== "running") return false;
+	if (run.workerId === void 0) return true;
+	if (run.leaseExpiresAt === void 0) return true;
+	return Temporal.Instant.compare(run.leaseExpiresAt, now) <= 0;
+}
+//#endregion
+export { canClaimRun, claimWorkflowRun, claimedRunPatch, countWorkflowRuns, extendWorkflowRunLease, extendedRunLeasePatch, firstClaimableRun, getReadableStoredWorkflowRun, getWorkflowRun, isSameReadableWorkflowRunRevision, isStaleLeaseClaim, isStoredWorkflowRunRevisionCurrent, isWorkflowRunStaleForAppend, listWorkflowRuns, listWorkflowRunsPage, releaseRunLeasePatch, releaseWorkflowRunLease, requireReadableStoredWorkflowRun, rollbackAppendedEventIfRunStale, shouldRollbackAppendedEventForRun, updateRunIfCurrent, updateWorkflowRun };

package/dist/store/schedule.d.mts

@@ -0,0 +1,12 @@
+import { WorkflowPage } from "../types/pagination.mjs";
+import { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleId, ScheduleRecord } from "../types/schedule.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/store/schedule.d.ts
+declare function createSchedule<TInput>(storage: WorkflowStorage, namespace: string, schedule: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput>>;
+declare function getReadableSchedule<TInput = StorageValue>(storage: WorkflowStorage, namespace: string, scheduleId: ScheduleId): Promise<ScheduleRecord<TInput> | undefined>;
+declare function updateScheduleIfCurrent<TInput>(storage: WorkflowStorage, namespace: string, current: ScheduleRecord, next: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput> | undefined>;
+declare function listSchedules(storage: WorkflowStorage, namespace: string, options?: ListSchedulesOptions): Promise<readonly ScheduleRecord[]>;
+declare function listSchedulesPage(storage: WorkflowStorage, namespace: string, options?: ListSchedulesPageOptions): Promise<WorkflowPage<ScheduleRecord>>;
+//#endregion
+export { createSchedule, getReadableSchedule, listSchedules, listSchedulesPage, updateScheduleIfCurrent };

package/dist/store/schedule.mjs

@@ -0,0 +1,41 @@
+import { limitWorkflowItems } from "../utility.mjs";
+import { WorkflowScheduleAlreadyExistsError, WorkflowScheduleError } from "../errors/schedule.mjs";
+import "../errors/mod.mjs";
+import { makeScheduleKey } from "../store-keys.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableScheduleRecord } from "./validation.mjs";
+import { makeScheduleCursorKey, pageItems } from "../pagination.mjs";
+import { compactWorkflowStoreRecord } from "./compaction.mjs";
+import { querySchedules } from "./query.mjs";
+//#region src/store/schedule.ts
+async function createSchedule(storage, namespace, schedule) {
+	if (schedule.namespace !== namespace) WorkflowScheduleError.namespaceMismatch(schedule.namespace, namespace);
+	if (!isReadableScheduleRecord(schedule, namespace)) WorkflowScheduleError.recordInvalid();
+	const compact = compactWorkflowStoreRecord(schedule);
+	if (!await storage.compareAndSet(makeScheduleKey(namespace, schedule.id), void 0, toStorageValue(compact))) WorkflowScheduleAlreadyExistsError.alreadyExists(schedule.id);
+	return compact;
+}
+async function getReadableSchedule(storage, namespace, scheduleId) {
+	const schedule = await storage.get(makeScheduleKey(namespace, scheduleId));
+	return isReadableScheduleRecord(schedule, namespace) ? schedule : void 0;
+}
+async function updateScheduleIfCurrent(storage, namespace, current, next) {
+	if (current.namespace !== namespace) WorkflowScheduleError.namespaceMismatch(current.namespace, namespace);
+	if (next.namespace !== namespace) WorkflowScheduleError.namespaceMismatch(next.namespace, namespace);
+	if (current.id !== next.id) WorkflowScheduleError.idChangeRejected();
+	if (!isReadableScheduleRecord(current, namespace)) WorkflowScheduleError.currentRecordInvalid();
+	if (!isReadableScheduleRecord(next, namespace)) WorkflowScheduleError.nextRecordInvalid();
+	const compact = compactWorkflowStoreRecord(next);
+	return await storage.compareAndSet(makeScheduleKey(namespace, current.id), toStorageValue(current), toStorageValue(compact)) ? compact : void 0;
+}
+async function listSchedules(storage, namespace, options) {
+	return limitWorkflowItems(await querySchedules(storage, namespace, options, { label: "Workflow schedule list options" }), options?.limit);
+}
+async function listSchedulesPage(storage, namespace, options) {
+	return pageItems(await querySchedules(storage, namespace, {
+		...options,
+		limit: void 0
+	}, { label: "Workflow schedule page options" }), options, "Workflow schedule page", makeScheduleCursorKey);
+}
+//#endregion
+export { createSchedule, getReadableSchedule, listSchedules, listSchedulesPage, updateScheduleIfCurrent };

package/dist/store/schema.d.mts

@@ -0,0 +1,14 @@
+import { StorageValue } from "@temelj/storage";
+import { z } from "zod";
+//#region src/store/schema.d.ts
+declare const workflowCleanupIndexKeySchema: z.ZodObject<{
+  key: z.ZodString;
+  value: z.ZodCustom<StorageValue, StorageValue>;
+}, z.core.$strip>;
+declare const workflowMessageIdempotencyIndexSchema: z.ZodObject<{
+  runId: z.ZodString;
+  messageId: z.ZodString;
+  timestamp: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+}, z.core.$strip>;
+//#endregion
+export { workflowCleanupIndexKeySchema, workflowMessageIdempotencyIndexSchema };

package/dist/store/schema.mjs

@@ -0,0 +1,17 @@
+import { nonBlankStringSchema, temporalInstantSchema } from "../types/common.mjs";
+import { runIdSchema } from "../types/run-id.mjs";
+import { persistedValueIssue } from "../types/run.mjs";
+import { messageIdSchema } from "../types/message-id.mjs";
+import { z } from "zod";
+//#region src/store/schema.ts
+const workflowCleanupIndexKeySchema = z.object({
+	key: nonBlankStringSchema,
+	value: z.custom((value) => value !== void 0 && persistedValueIssue(value, "value", /* @__PURE__ */ new WeakSet(), true) === void 0)
+});
+const workflowMessageIdempotencyIndexSchema = z.object({
+	runId: runIdSchema,
+	messageId: messageIdSchema,
+	timestamp: temporalInstantSchema
+});
+//#endregion
+export { workflowCleanupIndexKeySchema, workflowMessageIdempotencyIndexSchema };

package/dist/store/step-attempt.d.mts

@@ -0,0 +1,14 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowPage } from "../types/pagination.mjs";
+import { WorkflowListStepAttemptsPageOptions } from "../types/run-list.mjs";
+import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord } from "../types/step-attempts.mjs";
+import "../types/run.mjs";
+import { WorkflowEventReader, WorkflowRunReaderRepository, WorkflowStorage } from "../types/store.mjs";
+//#region src/store/step-attempt.d.ts
+type WorkflowStepAttemptReadStore = WorkflowRunReaderRepository & WorkflowEventReader;
+declare function listWorkflowStepAttempts(storage: WorkflowStorage, namespace: string, store: WorkflowStepAttemptReadStore, runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<readonly WorkflowStepAttemptRecord[]>;
+declare function listWorkflowStepAttemptsPage(storage: WorkflowStorage, namespace: string, store: WorkflowStepAttemptReadStore, runId: RunId, options?: WorkflowListStepAttemptsPageOptions): Promise<WorkflowPage<WorkflowStepAttemptRecord>>;
+declare function countWorkflowStepAttempts(storage: WorkflowStorage, namespace: string, store: WorkflowStepAttemptReadStore, runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<number>;
+declare function repairWorkflowStepAttempts(storage: WorkflowStorage, namespace: string, store: WorkflowStepAttemptReadStore, runId: RunId): Promise<readonly WorkflowStepAttemptRecord[]>;
+//#endregion
+export { countWorkflowStepAttempts, listWorkflowStepAttempts, listWorkflowStepAttemptsPage, repairWorkflowStepAttempts };

package/dist/store/step-attempt.mjs

@@ -0,0 +1,23 @@
+import { limitWorkflowItems } from "../utility.mjs";
+import { makeWorkflowStepAttemptCursorKey, pageItems } from "../pagination.mjs";
+import { reconcileStepAttempts } from "./materialization.mjs";
+import { getRequiredStoreRun, queryWorkflowStepAttempts } from "./query.mjs";
+//#region src/store/step-attempt.ts
+async function listWorkflowStepAttempts(storage, namespace, store, runId, options) {
+	return limitWorkflowItems(await queryWorkflowStepAttempts(storage, namespace, store, runId, options, { label: "Workflow step attempt list options" }), options?.limit);
+}
+async function listWorkflowStepAttemptsPage(storage, namespace, store, runId, options) {
+	return pageItems(await queryWorkflowStepAttempts(storage, namespace, store, runId, {
+		...options,
+		limit: void 0
+	}, { label: "Workflow step attempt page options" }), options, "Workflow step attempt page", makeWorkflowStepAttemptCursorKey);
+}
+async function countWorkflowStepAttempts(storage, namespace, store, runId, options) {
+	return (await queryWorkflowStepAttempts(storage, namespace, store, runId, options, { label: "Workflow step attempt list options" })).length;
+}
+async function repairWorkflowStepAttempts(storage, namespace, store, runId) {
+	await getRequiredStoreRun(store, runId);
+	return await reconcileStepAttempts(storage, namespace, runId, await store.getEvents(runId));
+}
+//#endregion
+export { countWorkflowStepAttempts, listWorkflowStepAttempts, listWorkflowStepAttemptsPage, repairWorkflowStepAttempts };

package/dist/store/storage-value.d.mts

@@ -0,0 +1,5 @@
+import { StorageValue } from "@temelj/storage";
+//#region src/store/storage-value.d.ts
+declare function toStorageValue(value: unknown): StorageValue;
+//#endregion
+export { toStorageValue };

package/dist/store/storage-value.mjs

@@ -0,0 +1,6 @@
+//#region src/store/storage-value.ts
+function toStorageValue(value) {
+	return value;
+}
+//#endregion
+export { toStorageValue };

package/dist/store/validation.d.mts

@@ -0,0 +1,35 @@
+import { CleanupMarkerRecord } from "../types/cleanup.mjs";
+import { ScheduleRecord } from "../types/schedule.mjs";
+import { LockRecord } from "../types/lock.mjs";
+import { WorkflowStepAttemptRecord } from "../types/step-attempts.mjs";
+import { WorkflowRunRecord, WorkflowRunTransitionReason } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowMessageIdempotencyIndex } from "../types/store.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/store/validation.d.ts
+/** Returns whether an unknown value is a readable run record in the expected namespace. */
+declare function isReadableWorkflowRunRecord(run: unknown, expectedNamespace: string): run is WorkflowRunRecord;
+/** Returns whether an unknown value is a run record that can participate in indexed list queries. */
+declare function isListableWorkflowRunRecord(run: unknown, expectedNamespace: string): run is WorkflowRunRecord & {
+  readonly lastTransitionReason: WorkflowRunTransitionReason;
+};
+/** Parses a stored workflow run record, if one exists. */
+declare function parseStoredWorkflowRunRecord(value: StorageValue | undefined): WorkflowRunRecord | undefined;
+/** Returns whether an unknown value is a readable schedule record in the expected namespace. */
+declare function isReadableScheduleRecord<TInput = StorageValue>(schedule: unknown, expectedNamespace: string): schedule is ScheduleRecord<TInput>;
+/** Returns whether an unknown value is a readable lock record in the expected namespace. */
+declare function isReadableLockRecord(lock: unknown, expectedNamespace: string): lock is LockRecord;
+/** Returns whether an unknown value is a readable durable workflow event record. */
+declare function isReadableEventRecord(event: unknown): event is EventRecord;
+/** Parses a readable cleanup marker record, if the value has the expected shape. */
+declare function readableCleanupMarkerRecord(marker: unknown): CleanupMarkerRecord | undefined;
+/** Parses a stored materialized step-attempt record, if one exists. */
+declare function parseStoredWorkflowStepAttemptRecord(value: StorageValue | undefined): WorkflowStepAttemptRecord | undefined;
+/** Returns whether an unknown value is a readable message idempotency index record. */
+declare function isReadableMessageIdempotencyIndex(value: unknown): value is WorkflowMessageIdempotencyIndex;
+/** Returns whether the stored message idempotency index matches the expected logical index. */
+declare function isSameMessageIdempotencyIndex(current: unknown, value: WorkflowMessageIdempotencyIndex): boolean;
+declare function requireReadableStoreRun(run: WorkflowRunRecord, namespace: string): void;
+declare function requireValidRunTransition(current: WorkflowRunRecord, next: WorkflowRunRecord): void;
+//#endregion
+export { isListableWorkflowRunRecord, isReadableEventRecord, isReadableLockRecord, isReadableMessageIdempotencyIndex, isReadableScheduleRecord, isReadableWorkflowRunRecord, isSameMessageIdempotencyIndex, parseStoredWorkflowRunRecord, parseStoredWorkflowStepAttemptRecord, readableCleanupMarkerRecord, requireReadableStoreRun, requireValidRunTransition };

package/dist/store/validation.mjs

@@ -0,0 +1,77 @@
+import { WorkflowRunNotFoundError, WorkflowRunTransitionError } from "../errors/run.mjs";
+import { workflowRunRecordSchema } from "../types/run.mjs";
+import "../errors/mod.mjs";
+import { workflowEventRecordSchema } from "../types/events.mjs";
+import { workflowCleanupMarkerRecordSchema } from "../types/cleanup.mjs";
+import { workflowLockRecordSchema } from "../types/lock.mjs";
+import { workflowScheduleRecordSchema } from "../types/schedule.mjs";
+import { workflowStepAttemptRecordSchema } from "../types/step-attempts.mjs";
+import { workflowMessageIdempotencyIndexSchema } from "./schema.mjs";
+//#region src/store/validation.ts
+/** Returns whether an unknown value is a readable run record in the expected namespace. */
+function isReadableWorkflowRunRecord(run, expectedNamespace) {
+	const parsed = workflowRunRecordSchema.safeParse(run);
+	return parsed.success && parsed.data.namespace === expectedNamespace;
+}
+/** Returns whether an unknown value is a run record that can participate in indexed list queries. */
+function isListableWorkflowRunRecord(run, expectedNamespace) {
+	return isReadableWorkflowRunRecord(run, expectedNamespace);
+}
+/** Parses a stored workflow run record, if one exists. */
+function parseStoredWorkflowRunRecord(value) {
+	return value === void 0 ? void 0 : workflowRunRecordSchema.parse(value);
+}
+/** Returns whether an unknown value is a readable schedule record in the expected namespace. */
+function isReadableScheduleRecord(schedule, expectedNamespace) {
+	const parsed = workflowScheduleRecordSchema.safeParse(schedule);
+	return parsed.success && parsed.data.namespace === expectedNamespace;
+}
+/** Returns whether an unknown value is a readable lock record in the expected namespace. */
+function isReadableLockRecord(lock, expectedNamespace) {
+	const parsed = workflowLockRecordSchema.safeParse(lock);
+	return parsed.success && parsed.data.namespace === expectedNamespace;
+}
+/** Returns whether an unknown value is a readable durable workflow event record. */
+function isReadableEventRecord(event) {
+	return workflowEventRecordSchema.safeParse(event).success;
+}
+/** Parses a readable cleanup marker record, if the value has the expected shape. */
+function readableCleanupMarkerRecord(marker) {
+	const parsed = workflowCleanupMarkerRecordSchema.safeParse(marker);
+	return parsed.success ? parsed.data : void 0;
+}
+/** Parses a stored materialized step-attempt record, if one exists. */
+function parseStoredWorkflowStepAttemptRecord(value) {
+	return value === void 0 ? void 0 : workflowStepAttemptRecordSchema.parse(value);
+}
+/** Returns whether an unknown value is a readable message idempotency index record. */
+function isReadableMessageIdempotencyIndex(value) {
+	return workflowMessageIdempotencyIndexSchema.safeParse(value).success;
+}
+/** Returns whether the stored message idempotency index matches the expected logical index. */
+function isSameMessageIdempotencyIndex(current, value) {
+	const parsedCurrent = workflowMessageIdempotencyIndexSchema.safeParse(current);
+	return parsedCurrent.success && parsedCurrent.data.runId === value.runId && parsedCurrent.data.messageId === value.messageId && Temporal.Instant.compare(parsedCurrent.data.timestamp, value.timestamp) === 0;
+}
+function requireReadableStoreRun(run, namespace) {
+	const runId = run.id;
+	if (!isReadableWorkflowRunRecord(run, namespace)) WorkflowRunNotFoundError.notFound(runId);
+}
+function requireValidRunTransition(current, next) {
+	if (current.status === next.status) return;
+	if (canTransitionWorkflowRunStatus(current.status, next.status)) return;
+	WorkflowRunTransitionError.invalidTransition(current.id, current.status, next.status);
+}
+/** Returns whether a run status transition is allowed by the workflow state machine. */
+function canTransitionWorkflowRunStatus(from, to) {
+	switch (from) {
+		case "pending": return to === "running" || to === "waiting" || to === "failed" || to === "canceled";
+		case "running": return to === "waiting" || to === "completed" || to === "failed" || to === "canceled";
+		case "waiting": return to === "running" || to === "failed" || to === "canceled";
+		case "failed": return to === "pending";
+		case "completed":
+		case "canceled": return false;
+	}
+}
+//#endregion
+export { isListableWorkflowRunRecord, isReadableEventRecord, isReadableLockRecord, isReadableMessageIdempotencyIndex, isReadableScheduleRecord, isReadableWorkflowRunRecord, isSameMessageIdempotencyIndex, parseStoredWorkflowRunRecord, parseStoredWorkflowStepAttemptRecord, readableCleanupMarkerRecord, requireReadableStoreRun, requireValidRunTransition };

package/dist/store-keys.d.mts

@@ -0,0 +1,49 @@
+import { RunId } from "./types/run-id.mjs";
+import { ScheduleId } from "./types/schedule.mjs";
+import "./types/run.mjs";
+import { WorkflowIdempotencyKeyOptions } from "./types/store.mjs";
+//#region src/store-keys.d.ts
+type WorkflowIdempotencyKey = `workflow:${string}:idempotency:${string}:${string}`;
+type MessageIdempotencyKey = `workflow:${string}:message-idempotency:${string}:${string}`;
+type WorkflowRunKey = `workflow:${string}:run:${string}`;
+type WorkflowEventsKey = `workflow:${string}:events:${string}`;
+type WorkflowStepAttemptKey = `workflow:${string}:step-attempt:${string}:${string}`;
+type WorkflowScheduleKey = `workflow:${string}:schedule:${string}`;
+type WorkflowLockKey = `workflow:${string}:lock:${string}`;
+type WorkflowCleanupMarkerKey = `workflow:${string}:cleanup:${string}`;
+type WorkflowNamespacePrefix = `workflow:${string}:`;
+type WorkflowRunKeyPrefix = `workflow:${string}:run:`;
+type WorkflowStepAttemptKeyPrefix = `workflow:${string}:step-attempt:${string}:`;
+type WorkflowScheduleKeyPrefix = `workflow:${string}:schedule:`;
+type WorkflowLockKeyPrefix = `workflow:${string}:lock:`;
+type WorkflowCleanupMarkerKeyPrefix = `workflow:${string}:cleanup:`;
+/** Builds a validated workflow idempotency storage key. */
+declare function makeWorkflowIdempotencyKey(namespace: string, options: WorkflowIdempotencyKeyOptions): WorkflowIdempotencyKey;
+/** Builds a workflow run storage key. */
+declare function makeRunKey(namespace: string, runId: RunId): WorkflowRunKey;
+/** Builds a workflow event-history storage key. */
+declare function makeEventsKey(namespace: string, runId: RunId): WorkflowEventsKey;
+/** Builds a workflow step-attempt storage key. */
+declare function makeStepAttemptKey(namespace: string, runId: RunId, attemptKey: string): WorkflowStepAttemptKey;
+/** Builds a workflow step-attempt storage key prefix. */
+declare function makeStepAttemptKeyPrefix(namespace: string, runId: RunId): WorkflowStepAttemptKeyPrefix;
+/** Builds a workflow message idempotency storage key. */
+declare function makeMessageIdempotencyKey(namespace: string, runId: RunId, idempotencyKey: string): MessageIdempotencyKey;
+/** Builds a workflow schedule storage key. */
+declare function makeScheduleKey(namespace: string, scheduleId: ScheduleId): WorkflowScheduleKey;
+/** Builds a workflow schedule storage key prefix. */
+declare function makeScheduleKeyPrefix(namespace: string): WorkflowScheduleKeyPrefix;
+/** Builds a workflow lock storage key. */
+declare function makeLockKey(namespace: string, key: string): WorkflowLockKey;
+/** Builds a workflow cleanup marker storage key. */
+declare function makeCleanupMarkerKey(namespace: string, runId: RunId): WorkflowCleanupMarkerKey;
+/** Builds a workflow cleanup marker storage key prefix. */
+declare function makeCleanupMarkerKeyPrefix(namespace: string): WorkflowCleanupMarkerKeyPrefix;
+/** Builds a workflow lock storage key prefix. */
+declare function makeLockKeyPrefix(namespace: string): WorkflowLockKeyPrefix;
+/** Builds a workflow idempotency storage key. */
+declare function makeIdempotencyKey(namespace: string, options: WorkflowIdempotencyKeyOptions): WorkflowIdempotencyKey;
+/** Builds a workflow run storage key prefix. */
+declare function makeRunKeyPrefix(namespace: string): WorkflowRunKeyPrefix;
+//#endregion
+export { MessageIdempotencyKey, WorkflowCleanupMarkerKey, WorkflowCleanupMarkerKeyPrefix, WorkflowEventsKey, WorkflowIdempotencyKey, WorkflowLockKey, WorkflowLockKeyPrefix, WorkflowNamespacePrefix, WorkflowRunKey, WorkflowRunKeyPrefix, WorkflowScheduleKey, WorkflowScheduleKeyPrefix, WorkflowStepAttemptKey, WorkflowStepAttemptKeyPrefix, makeCleanupMarkerKey, makeCleanupMarkerKeyPrefix, makeEventsKey, makeIdempotencyKey, makeLockKey, makeLockKeyPrefix, makeMessageIdempotencyKey, makeRunKey, makeRunKeyPrefix, makeScheduleKey, makeScheduleKeyPrefix, makeStepAttemptKey, makeStepAttemptKeyPrefix, makeWorkflowIdempotencyKey };

package/dist/store-keys.mjs

@@ -0,0 +1,63 @@
+//#region src/store-keys.ts
+/** Builds a validated workflow idempotency storage key. */
+function makeWorkflowIdempotencyKey(namespace, options) {
+	return makeIdempotencyKey(namespace, options);
+}
+/** Builds a workflow run storage key. */
+function makeRunKey(namespace, runId) {
+	return `${namespacePrefix(namespace)}run:${runId}`;
+}
+/** Builds a workflow event-history storage key. */
+function makeEventsKey(namespace, runId) {
+	return `${namespacePrefix(namespace)}events:${runId}`;
+}
+/** Builds a workflow step-attempt storage key. */
+function makeStepAttemptKey(namespace, runId, attemptKey) {
+	return `${makeStepAttemptKeyPrefix(namespace, runId)}${encodeURIComponent(attemptKey)}`;
+}
+/** Builds a workflow step-attempt storage key prefix. */
+function makeStepAttemptKeyPrefix(namespace, runId) {
+	return `${namespacePrefix(namespace)}step-attempt:${runId}:`;
+}
+/** Builds a workflow message idempotency storage key. */
+function makeMessageIdempotencyKey(namespace, runId, idempotencyKey) {
+	return `${namespacePrefix(namespace)}message-idempotency:${encodeURIComponent(runId)}:${encodeURIComponent(idempotencyKey)}`;
+}
+/** Builds a workflow schedule storage key. */
+function makeScheduleKey(namespace, scheduleId) {
+	return `${namespacePrefix(namespace)}schedule:${encodeURIComponent(scheduleId)}`;
+}
+/** Builds a workflow schedule storage key prefix. */
+function makeScheduleKeyPrefix(namespace) {
+	return `${namespacePrefix(namespace)}schedule:`;
+}
+/** Builds a workflow lock storage key. */
+function makeLockKey(namespace, key) {
+	return `${namespacePrefix(namespace)}lock:${encodeURIComponent(key)}`;
+}
+/** Builds a workflow cleanup marker storage key. */
+function makeCleanupMarkerKey(namespace, runId) {
+	return `${namespacePrefix(namespace)}cleanup:${encodeURIComponent(runId)}`;
+}
+/** Builds a workflow cleanup marker storage key prefix. */
+function makeCleanupMarkerKeyPrefix(namespace) {
+	return `${namespacePrefix(namespace)}cleanup:`;
+}
+/** Builds a workflow lock storage key prefix. */
+function makeLockKeyPrefix(namespace) {
+	return `${namespacePrefix(namespace)}lock:`;
+}
+/** Builds a workflow idempotency storage key. */
+function makeIdempotencyKey(namespace, options) {
+	const versionedName = options.workflowVersion === void 0 ? options.workflowName : `${options.workflowName}@${options.workflowVersion}`;
+	return `${namespacePrefix(namespace)}idempotency:${encodeURIComponent(versionedName)}:${encodeURIComponent(options.idempotencyKey)}`;
+}
+/** Builds a workflow run storage key prefix. */
+function makeRunKeyPrefix(namespace) {
+	return `${namespacePrefix(namespace)}run:`;
+}
+function namespacePrefix(namespace) {
+	return `workflow:${encodeURIComponent(namespace)}:`;
+}
+//#endregion
+export { makeCleanupMarkerKey, makeCleanupMarkerKeyPrefix, makeEventsKey, makeIdempotencyKey, makeLockKey, makeLockKeyPrefix, makeMessageIdempotencyKey, makeRunKey, makeRunKeyPrefix, makeScheduleKey, makeScheduleKeyPrefix, makeStepAttemptKey, makeStepAttemptKeyPrefix, makeWorkflowIdempotencyKey };