@temelj/workflow 0.0.0-alpha.1

package/dist/telemetry.d.mts

@@ -0,0 +1,132 @@
+import { ObservationEventMap } from "./types/observation.mjs";
+import { RunTelemetryContext, StepTelemetryContext, StorageTelemetryContext, Telemetry, TelemetryContext } from "./types/telemetry.mjs";
+//#region src/telemetry.d.ts
+/** Instrumentation scope used by workflow telemetry adapters. */
+declare const WORKFLOW_INSTRUMENTATION_NAME = "temelj.workflow";
+/** Version of the built-in workflow telemetry instrumentation. */
+declare const WORKFLOW_INSTRUMENTATION_VERSION = "0.1.0";
+/** Stable workflow system identifier used on spans, metrics, and logs. */
+declare const WORKFLOW_SYSTEM = "temelj";
+/** Stable OpenTelemetry span names emitted by `@temelj/workflow`. */
+declare const WORKFLOW_SPAN_NAMES: {
+  readonly childWorkflowOperation: "temelj.workflow.child_workflow.operation";
+  readonly cleanupOperation: "temelj.workflow.cleanup.operation";
+  readonly hookResume: "temelj.workflow.hook.resume";
+  readonly messageSend: "temelj.workflow.message.send";
+  readonly messageWait: "temelj.workflow.message.wait";
+  readonly runExecution: "temelj.workflow.execute";
+  readonly scheduleTick: "temelj.workflow.schedule.tick";
+  readonly scheduleRunCreate: "temelj.workflow.schedule.run.create";
+  readonly sleep: "temelj.workflow.sleep";
+  readonly stepExecution: "temelj.workflow.step";
+  readonly storageOperation: "temelj.workflow.storage.operation";
+  readonly streamOperation: "temelj.workflow.stream.operation";
+  readonly workerOperation: "temelj.workflow.worker.operation";
+};
+/** Stable metric names emitted by `@temelj/workflow` telemetry. */
+declare const WORKFLOW_METRIC_NAMES: {
+  readonly cleanupDeletedRuns: "temelj.workflow.cleanup.deleted_runs";
+  readonly eventsAppended: "temelj.workflow.events.appended";
+  readonly hooksResumed: "temelj.workflow.hooks.resumed";
+  readonly hookResumeLatency: "temelj.workflow.hooks.resume_latency";
+  readonly messageWaitLatency: "temelj.workflow.messages.wait_latency";
+  readonly messagesSent: "temelj.workflow.messages.sent";
+  readonly pendingToClaimedLatency: "temelj.workflow.run.pending_to_claimed_latency";
+  readonly runDuration: "temelj.workflow.run.duration";
+  readonly runTransitions: "temelj.workflow.run.transitions";
+  readonly runs: "temelj.workflow.runs";
+  readonly retryDelay: "temelj.workflow.retry.delay";
+  readonly retryExhausted: "temelj.workflow.retry.exhausted";
+  readonly retryScheduled: "temelj.workflow.retry.scheduled";
+  readonly runWaitingToResumedLatency: "temelj.workflow.run.waiting_to_resumed_latency";
+  readonly scheduleDueToRunCreatedLatency: "temelj.workflow.schedule.due_to_run_created_latency";
+  readonly stepAttempts: "temelj.workflow.step.attempts";
+  readonly stepDuration: "temelj.workflow.step.duration";
+  readonly storageOperationDuration: "temelj.workflow.storage.operation.duration";
+  readonly storageOperationErrors: "temelj.workflow.storage.operation.errors";
+  readonly streamUpdates: "temelj.workflow.stream.updates";
+  readonly workerActiveExecutions: "temelj.workflow.worker.active_executions";
+  readonly workerClaimFailures: "temelj.workflow.worker.claim_failures";
+  readonly workerClaims: "temelj.workflow.worker.claims";
+  readonly workerHeartbeatFailures: "temelj.workflow.worker.heartbeat_failures";
+  readonly workerLeaseExtensions: "temelj.workflow.worker.lease_extensions";
+  readonly workerLeaseReleases: "temelj.workflow.worker.lease_releases";
+};
+/** Stable workflow attribute names used by traces, metrics, and logs. */
+declare const WORKFLOW_ATTRIBUTES: {
+  readonly canceled: "workflow.canceled";
+  readonly childWorkflowDurationMs: "workflow.child_workflow.duration_ms";
+  readonly childWorkflowOperation: "workflow.child_workflow.operation";
+  readonly childWorkflowRunId: "workflow.child_workflow.run.id";
+  readonly childWorkflowStatus: "workflow.child_workflow.status";
+  readonly childWorkflowName: "workflow.child_workflow.name";
+  readonly childWorkflowVersion: "workflow.child_workflow.version";
+  readonly cleanupCreatedMarkers: "workflow.cleanup.created_markers";
+  readonly cleanupDeletedEvents: "workflow.cleanup.deleted_events";
+  readonly cleanupDeletedIdempotencyKeys: "workflow.cleanup.deleted_idempotency_keys";
+  readonly cleanupDeletedMarkers: "workflow.cleanup.deleted_markers";
+  readonly cleanupDeletedMessageIdempotencyKeys: "workflow.cleanup.deleted_message_idempotency_keys";
+  readonly cleanupDeletedRuns: "workflow.cleanup.deleted_runs";
+  readonly cleanupDeletedStepAttempts: "workflow.cleanup.deleted_step_attempts";
+  readonly cleanupDryRun: "workflow.cleanup.dry_run";
+  readonly cleanupMatchedRuns: "workflow.cleanup.matched_runs";
+  readonly cleanupSource: "workflow.cleanup.source";
+  readonly deadlineExceeded: "workflow.deadline.exceeded";
+  readonly errorKind: "workflow.error.kind";
+  readonly errorRetryable: "workflow.error.retryable";
+  readonly eventCategory: "workflow.event.category";
+  readonly eventKind: "workflow.event.kind";
+  readonly hookKind: "workflow.hook.kind";
+  readonly messageId: "workflow.message.id";
+  readonly messageSource: "workflow.message.source";
+  readonly namespace: "workflow.namespace";
+  readonly replay: "workflow.replay";
+  readonly retryExhausted: "workflow.retry.exhausted";
+  readonly retryReason: "workflow.retry.reason";
+  readonly runAttempt: "workflow.run.attempt";
+  readonly runId: "workflow.run.id";
+  readonly runStatus: "workflow.run.status";
+  readonly runTransition: "workflow.run.transition";
+  readonly scheduleFireAt: "workflow.schedule.fire_at";
+  readonly scheduleId: "workflow.schedule.id";
+  readonly scheduleNextAt: "workflow.schedule.next_at";
+  readonly scheduleTickedRuns: "workflow.schedule.ticked_runs";
+  readonly scheduleTickedSchedules: "workflow.schedule.ticked_schedules";
+  readonly sleepActualMs: "workflow.sleep.actual_ms";
+  readonly sleepDurationMs: "workflow.sleep.duration_ms";
+  readonly sleepUntil: "workflow.sleep.until";
+  readonly stepAttempt: "workflow.step.attempt";
+  readonly stepId: "workflow.step.id";
+  readonly stepKind: "workflow.step.kind";
+  readonly stepName: "workflow.step.name";
+  readonly stepStatus: "workflow.step.status";
+  readonly stepTimeoutAt: "workflow.step.timeout_at";
+  readonly storageBackend: "workflow.storage.backend";
+  readonly storageOperation: "workflow.storage.operation";
+  readonly storageOperationStatus: "workflow.storage.operation.status";
+  readonly streamEventKind: "workflow.stream.event.kind";
+  readonly streamId: "workflow.stream.id";
+  readonly streamIndex: "workflow.stream.index";
+  readonly streamStatus: "workflow.stream.status";
+  readonly system: "workflow.system";
+  readonly workerId: "workflow.worker.id";
+  readonly workerOperation: "workflow.worker.operation";
+  readonly workerOperationStatus: "workflow.worker.operation.status";
+  readonly workflowName: "workflow.name";
+  readonly workflowVersion: "workflow.version";
+};
+/** OpenTelemetry semantic convention attributes used when workflow operations act like messages. */
+declare const WORKFLOW_MESSAGING_ATTRIBUTES: {
+  readonly destinationName: "messaging.destination.name";
+  readonly messageId: "messaging.message.id";
+  readonly operationName: "messaging.operation.name";
+  readonly operationType: "messaging.operation.type";
+  readonly system: "messaging.system";
+};
+declare function captureTelemetryContext(telemetry: Telemetry | undefined): TelemetryContext | undefined;
+declare function withRunTelemetry<T>(telemetry: Telemetry | undefined, context: RunTelemetryContext, callback: () => Promise<T>): Promise<T>;
+declare function withStepTelemetry<T>(telemetry: Telemetry | undefined, context: StepTelemetryContext, callback: () => Promise<T>): Promise<T>;
+declare function withStorageTelemetry<T>(telemetry: Telemetry | undefined, context: StorageTelemetryContext, callback: () => Promise<T>): Promise<T>;
+declare function observeTelemetry<Key extends keyof ObservationEventMap>(telemetry: Telemetry | undefined, name: Key, payload: ObservationEventMap[Key]): void;
+//#endregion
+export { WORKFLOW_ATTRIBUTES, WORKFLOW_INSTRUMENTATION_NAME, WORKFLOW_INSTRUMENTATION_VERSION, WORKFLOW_MESSAGING_ATTRIBUTES, WORKFLOW_METRIC_NAMES, WORKFLOW_SPAN_NAMES, WORKFLOW_SYSTEM, captureTelemetryContext, observeTelemetry, withRunTelemetry, withStepTelemetry, withStorageTelemetry };

package/dist/telemetry.mjs

@@ -0,0 +1,172 @@
+//#region src/telemetry.ts
+/** Instrumentation scope used by workflow telemetry adapters. */
+const WORKFLOW_INSTRUMENTATION_NAME = "temelj.workflow";
+/** Version of the built-in workflow telemetry instrumentation. */
+const WORKFLOW_INSTRUMENTATION_VERSION = "0.1.0";
+/** Stable workflow system identifier used on spans, metrics, and logs. */
+const WORKFLOW_SYSTEM = "temelj";
+/** Stable OpenTelemetry span names emitted by `@temelj/workflow`. */
+const WORKFLOW_SPAN_NAMES = {
+	childWorkflowOperation: "temelj.workflow.child_workflow.operation",
+	cleanupOperation: "temelj.workflow.cleanup.operation",
+	hookResume: "temelj.workflow.hook.resume",
+	messageSend: "temelj.workflow.message.send",
+	messageWait: "temelj.workflow.message.wait",
+	runExecution: "temelj.workflow.execute",
+	scheduleTick: "temelj.workflow.schedule.tick",
+	scheduleRunCreate: "temelj.workflow.schedule.run.create",
+	sleep: "temelj.workflow.sleep",
+	stepExecution: "temelj.workflow.step",
+	storageOperation: "temelj.workflow.storage.operation",
+	streamOperation: "temelj.workflow.stream.operation",
+	workerOperation: "temelj.workflow.worker.operation"
+};
+/** Stable metric names emitted by `@temelj/workflow` telemetry. */
+const WORKFLOW_METRIC_NAMES = {
+	cleanupDeletedRuns: "temelj.workflow.cleanup.deleted_runs",
+	eventsAppended: "temelj.workflow.events.appended",
+	hooksResumed: "temelj.workflow.hooks.resumed",
+	hookResumeLatency: "temelj.workflow.hooks.resume_latency",
+	messageWaitLatency: "temelj.workflow.messages.wait_latency",
+	messagesSent: "temelj.workflow.messages.sent",
+	pendingToClaimedLatency: "temelj.workflow.run.pending_to_claimed_latency",
+	runDuration: "temelj.workflow.run.duration",
+	runTransitions: "temelj.workflow.run.transitions",
+	runs: "temelj.workflow.runs",
+	retryDelay: "temelj.workflow.retry.delay",
+	retryExhausted: "temelj.workflow.retry.exhausted",
+	retryScheduled: "temelj.workflow.retry.scheduled",
+	runWaitingToResumedLatency: "temelj.workflow.run.waiting_to_resumed_latency",
+	scheduleDueToRunCreatedLatency: "temelj.workflow.schedule.due_to_run_created_latency",
+	stepAttempts: "temelj.workflow.step.attempts",
+	stepDuration: "temelj.workflow.step.duration",
+	storageOperationDuration: "temelj.workflow.storage.operation.duration",
+	storageOperationErrors: "temelj.workflow.storage.operation.errors",
+	streamUpdates: "temelj.workflow.stream.updates",
+	workerActiveExecutions: "temelj.workflow.worker.active_executions",
+	workerClaimFailures: "temelj.workflow.worker.claim_failures",
+	workerClaims: "temelj.workflow.worker.claims",
+	workerHeartbeatFailures: "temelj.workflow.worker.heartbeat_failures",
+	workerLeaseExtensions: "temelj.workflow.worker.lease_extensions",
+	workerLeaseReleases: "temelj.workflow.worker.lease_releases"
+};
+/** Stable workflow attribute names used by traces, metrics, and logs. */
+const WORKFLOW_ATTRIBUTES = {
+	canceled: "workflow.canceled",
+	childWorkflowDurationMs: "workflow.child_workflow.duration_ms",
+	childWorkflowOperation: "workflow.child_workflow.operation",
+	childWorkflowRunId: "workflow.child_workflow.run.id",
+	childWorkflowStatus: "workflow.child_workflow.status",
+	childWorkflowName: "workflow.child_workflow.name",
+	childWorkflowVersion: "workflow.child_workflow.version",
+	cleanupCreatedMarkers: "workflow.cleanup.created_markers",
+	cleanupDeletedEvents: "workflow.cleanup.deleted_events",
+	cleanupDeletedIdempotencyKeys: "workflow.cleanup.deleted_idempotency_keys",
+	cleanupDeletedMarkers: "workflow.cleanup.deleted_markers",
+	cleanupDeletedMessageIdempotencyKeys: "workflow.cleanup.deleted_message_idempotency_keys",
+	cleanupDeletedRuns: "workflow.cleanup.deleted_runs",
+	cleanupDeletedStepAttempts: "workflow.cleanup.deleted_step_attempts",
+	cleanupDryRun: "workflow.cleanup.dry_run",
+	cleanupMatchedRuns: "workflow.cleanup.matched_runs",
+	cleanupSource: "workflow.cleanup.source",
+	deadlineExceeded: "workflow.deadline.exceeded",
+	errorKind: "workflow.error.kind",
+	errorRetryable: "workflow.error.retryable",
+	eventCategory: "workflow.event.category",
+	eventKind: "workflow.event.kind",
+	hookKind: "workflow.hook.kind",
+	messageId: "workflow.message.id",
+	messageSource: "workflow.message.source",
+	namespace: "workflow.namespace",
+	replay: "workflow.replay",
+	retryExhausted: "workflow.retry.exhausted",
+	retryReason: "workflow.retry.reason",
+	runAttempt: "workflow.run.attempt",
+	runId: "workflow.run.id",
+	runStatus: "workflow.run.status",
+	runTransition: "workflow.run.transition",
+	scheduleFireAt: "workflow.schedule.fire_at",
+	scheduleId: "workflow.schedule.id",
+	scheduleNextAt: "workflow.schedule.next_at",
+	scheduleTickedRuns: "workflow.schedule.ticked_runs",
+	scheduleTickedSchedules: "workflow.schedule.ticked_schedules",
+	sleepActualMs: "workflow.sleep.actual_ms",
+	sleepDurationMs: "workflow.sleep.duration_ms",
+	sleepUntil: "workflow.sleep.until",
+	stepAttempt: "workflow.step.attempt",
+	stepId: "workflow.step.id",
+	stepKind: "workflow.step.kind",
+	stepName: "workflow.step.name",
+	stepStatus: "workflow.step.status",
+	stepTimeoutAt: "workflow.step.timeout_at",
+	storageBackend: "workflow.storage.backend",
+	storageOperation: "workflow.storage.operation",
+	storageOperationStatus: "workflow.storage.operation.status",
+	streamEventKind: "workflow.stream.event.kind",
+	streamId: "workflow.stream.id",
+	streamIndex: "workflow.stream.index",
+	streamStatus: "workflow.stream.status",
+	system: "workflow.system",
+	workerId: "workflow.worker.id",
+	workerOperation: "workflow.worker.operation",
+	workerOperationStatus: "workflow.worker.operation.status",
+	workflowName: "workflow.name",
+	workflowVersion: "workflow.version"
+};
+/** OpenTelemetry semantic convention attributes used when workflow operations act like messages. */
+const WORKFLOW_MESSAGING_ATTRIBUTES = {
+	destinationName: "messaging.destination.name",
+	messageId: "messaging.message.id",
+	operationName: "messaging.operation.name",
+	operationType: "messaging.operation.type",
+	system: "messaging.system"
+};
+function captureTelemetryContext(telemetry) {
+	try {
+		return telemetry?.captureContext?.();
+	} catch {
+		return;
+	}
+}
+async function withRunTelemetry(telemetry, context, callback) {
+	if (telemetry?.withRunExecution === void 0) return await callback();
+	return await withTelemetry((wrappedCallback) => telemetry.withRunExecution(context, wrappedCallback), callback);
+}
+async function withStepTelemetry(telemetry, context, callback) {
+	if (telemetry?.withStepExecution === void 0) return await callback();
+	return await withTelemetry((wrappedCallback) => telemetry.withStepExecution(context, wrappedCallback), callback);
+}
+async function withStorageTelemetry(telemetry, context, callback) {
+	if (telemetry?.withStorageOperation === void 0) return await callback();
+	return await withTelemetry((wrappedCallback) => telemetry.withStorageOperation(context, wrappedCallback), callback);
+}
+function observeTelemetry(telemetry, name, payload) {
+	try {
+		telemetry?.observe?.(name, payload);
+	} catch {
+		return;
+	}
+}
+const UNSET = Symbol("workflow telemetry unset");
+async function withTelemetry(runWithTelemetry, callback) {
+	let result = UNSET;
+	let callbackError = UNSET;
+	const wrappedCallback = async () => {
+		try {
+			result = await callback();
+			return result;
+		} catch (error) {
+			callbackError = error;
+			throw error;
+		}
+	};
+	try {
+		return await runWithTelemetry(wrappedCallback);
+	} catch {
+		if (callbackError !== UNSET) throw callbackError;
+		if (result !== UNSET) return result;
+		return await callback();
+	}
+}
+//#endregion
+export { WORKFLOW_ATTRIBUTES, WORKFLOW_INSTRUMENTATION_NAME, WORKFLOW_INSTRUMENTATION_VERSION, WORKFLOW_MESSAGING_ATTRIBUTES, WORKFLOW_METRIC_NAMES, WORKFLOW_SPAN_NAMES, WORKFLOW_SYSTEM, captureTelemetryContext, observeTelemetry, withRunTelemetry, withStepTelemetry, withStorageTelemetry };

package/dist/temporal.d.mts

@@ -0,0 +1,23 @@
+//#region src/temporal.d.ts
+/** Returns a non-negative millisecond duration between two instants. */
+declare function durationBetweenMilliseconds(from: Temporal.Instant, to: Temporal.Instant): number;
+/** Returns a non-negative millisecond duration between optional instants. */
+declare function optionalDurationBetweenMilliseconds(from: Temporal.Instant | undefined, to: Temporal.Instant | undefined): number | undefined;
+/** Returns a non-negative Temporal duration between two instants. */
+declare function durationBetween(from: Temporal.Instant, to: Temporal.Instant): Temporal.Duration;
+/** Returns whether a timestamp falls inside an inclusive optional instant range. */
+declare function matchesTimestampRange(timestamp: Temporal.Instant, from: Temporal.Instant | undefined, to: Temporal.Instant | undefined): boolean;
+/** Returns whether an optional timestamp falls inside an inclusive optional instant range. */
+declare function matchesOptionalTimestampRange(timestamp: Temporal.Instant | undefined, from: Temporal.Instant | undefined, to: Temporal.Instant | undefined): boolean;
+/** Returns whether an optional duration falls inside an inclusive optional duration range. */
+declare function matchesOptionalDurationRange(value: Temporal.Duration | undefined, from: Temporal.Duration | undefined, to: Temporal.Duration | undefined): boolean;
+/** Compares optional timestamps, sorting present timestamps before undefined values. */
+declare function compareOptionalTimestamps(left: Temporal.Instant | undefined, right: Temporal.Instant | undefined): number;
+/** Returns the earlier of two optional timestamps. */
+declare function earliestOptionalTimestamp(current: Temporal.Instant | undefined, next: Temporal.Instant | undefined): Temporal.Instant | undefined;
+/** Returns the later of two optional timestamps. */
+declare function latestOptionalTimestamp(current: Temporal.Instant | undefined, next: Temporal.Instant | undefined): Temporal.Instant | undefined;
+/** Returns whether `next` should replace `current` as the earliest defined instant. */
+declare function shouldReplaceWorkflowEarliestDefinedInstant(current: Temporal.Instant | undefined, next: Temporal.Instant | undefined): boolean;
+//#endregion
+export { compareOptionalTimestamps, durationBetween, durationBetweenMilliseconds, earliestOptionalTimestamp, latestOptionalTimestamp, matchesOptionalDurationRange, matchesOptionalTimestampRange, matchesTimestampRange, optionalDurationBetweenMilliseconds, shouldReplaceWorkflowEarliestDefinedInstant };

package/dist/temporal.mjs

@@ -0,0 +1,59 @@
+//#region src/temporal.ts
+/** Returns a non-negative millisecond duration between two instants. */
+function durationBetweenMilliseconds(from, to) {
+	return Math.max(0, to.epochMilliseconds - from.epochMilliseconds);
+}
+/** Returns a non-negative millisecond duration between optional instants. */
+function optionalDurationBetweenMilliseconds(from, to) {
+	if (from === void 0 || to === void 0) return;
+	return durationBetweenMilliseconds(from, to);
+}
+/** Returns a non-negative Temporal duration between two instants. */
+function durationBetween(from, to) {
+	return Temporal.Duration.from({ milliseconds: durationBetweenMilliseconds(from, to) });
+}
+/** Returns whether a timestamp falls inside an inclusive optional instant range. */
+function matchesTimestampRange(timestamp, from, to) {
+	if (from === void 0 && to === void 0) return true;
+	return (from === void 0 || Temporal.Instant.compare(timestamp, from) >= 0) && (to === void 0 || Temporal.Instant.compare(timestamp, to) <= 0);
+}
+/** Returns whether an optional timestamp falls inside an inclusive optional instant range. */
+function matchesOptionalTimestampRange(timestamp, from, to) {
+	if (from === void 0 && to === void 0) return true;
+	if (timestamp === void 0) return false;
+	return matchesTimestampRange(timestamp, from, to);
+}
+/** Returns whether an optional duration falls inside an inclusive optional duration range. */
+function matchesOptionalDurationRange(value, from, to) {
+	if (from === void 0 && to === void 0) return true;
+	if (value === void 0) return false;
+	const current = value.total({ unit: "millisecond" });
+	const lower = from === void 0 ? void 0 : from.total({ unit: "millisecond" });
+	const upper = to === void 0 ? void 0 : to.total({ unit: "millisecond" });
+	return (lower === void 0 || current >= lower) && (upper === void 0 || current <= upper);
+}
+/** Compares optional timestamps, sorting present timestamps before undefined values. */
+function compareOptionalTimestamps(left, right) {
+	if (left !== void 0 && right !== void 0) return Temporal.Instant.compare(left, right);
+	if (left !== void 0) return -1;
+	if (right !== void 0) return 1;
+	return 0;
+}
+/** Returns the earlier of two optional timestamps. */
+function earliestOptionalTimestamp(current, next) {
+	if (next === void 0) return current;
+	if (current === void 0) return next;
+	return Temporal.Instant.compare(next, current) < 0 ? next : current;
+}
+/** Returns the later of two optional timestamps. */
+function latestOptionalTimestamp(current, next) {
+	if (next === void 0) return current;
+	if (current === void 0) return next;
+	return Temporal.Instant.compare(next, current) > 0 ? next : current;
+}
+/** Returns whether `next` should replace `current` as the earliest defined instant. */
+function shouldReplaceWorkflowEarliestDefinedInstant(current, next) {
+	return next !== void 0 && (current === void 0 || Temporal.Instant.compare(next, current) < 0);
+}
+//#endregion
+export { compareOptionalTimestamps, durationBetween, durationBetweenMilliseconds, earliestOptionalTimestamp, latestOptionalTimestamp, matchesOptionalDurationRange, matchesOptionalTimestampRange, matchesTimestampRange, optionalDurationBetweenMilliseconds, shouldReplaceWorkflowEarliestDefinedInstant };

package/dist/timer.d.mts

@@ -0,0 +1,12 @@
+import { TimerDelay } from "./types/common.mjs";
+//#region src/timer.d.ts
+declare const MAX_TIMER_DELAY: number;
+/** Runtime timer handle returned by setTimeout. */
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+/** Runtime interval handle returned by setInterval. */
+type IntervalHandle = ReturnType<typeof setInterval>;
+declare function nonNegativeTimerDelay(duration: Temporal.Duration, label: string, maximumDelay?: number): TimerDelay;
+declare function positiveTimerDelay(duration: Temporal.Duration, label: string, maximumDelay?: number): TimerDelay;
+declare function sleep(duration: number): Promise<void>;
+//#endregion
+export { IntervalHandle, MAX_TIMER_DELAY, TimeoutHandle, nonNegativeTimerDelay, positiveTimerDelay, sleep };

package/dist/timer.mjs

@@ -0,0 +1,28 @@
+import { WorkflowOptionsError } from "./errors/base.mjs";
+import { durationTotal, isNonNegativeSafeInteger, isPositiveSafeInteger } from "./utility.mjs";
+import "./errors/mod.mjs";
+//#region src/timer.ts
+const MAX_TIMER_DELAY = 2 ** 31 - 1;
+function nonNegativeTimerDelay(duration, label, maximumDelay = MAX_TIMER_DELAY) {
+	const delay = durationTotal(duration);
+	if (!isNonNegativeSafeInteger(delay)) WorkflowOptionsError.nonNegativeDuration(label);
+	return {
+		duration,
+		clampedDelay: Math.min(delay, maximumDelay)
+	};
+}
+function positiveTimerDelay(duration, label, maximumDelay = MAX_TIMER_DELAY) {
+	const delay = durationTotal(duration);
+	if (!isPositiveSafeInteger(delay)) WorkflowOptionsError.positiveDuration(label);
+	return {
+		duration,
+		clampedDelay: Math.min(delay, maximumDelay)
+	};
+}
+async function sleep(duration) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, Math.min(duration, MAX_TIMER_DELAY));
+	});
+}
+//#endregion
+export { MAX_TIMER_DELAY, nonNegativeTimerDelay, positiveTimerDelay, sleep };

package/dist/types/cleanup.d.mts

@@ -0,0 +1,112 @@
+import { RunId } from "./run-id.mjs";
+import { StepId } from "./step-id.mjs";
+import { WorkflowTerminalRunStatus } from "./run.mjs";
+import { z } from "zod";
+//#region src/types/cleanup.d.ts
+declare const workflowCleanupModeSchema: z.ZodLiteral<"best_effort">;
+declare const workflowCleanupMarkerRecordSchema: z.ZodObject<{
+  mode: z.ZodLiteral<"best_effort">;
+  runId: z.ZodString;
+  workflowName: z.ZodString;
+  workflowVersion: z.ZodOptional<z.ZodString>;
+  status: z.ZodEnum<{
+    canceled: "canceled";
+    completed: "completed";
+    failed: "failed";
+  }>;
+  createdAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  finishedAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  cleanupStartedAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  events: z.ZodNumber;
+  stepAttempts: z.ZodNumber;
+  idempotencyKeys: z.ZodNumber;
+  messageIdempotencyKeys: z.ZodNumber;
+}, z.core.$strip>;
+/** Cleanup strategy used when deleting terminal run data from the store. */
+type CleanupMode = "best_effort";
+/** Options for workflow cleanup runs. */
+interface CleanupRunsOptions extends WorkflowCleanupRunFilterOptions {
+  readonly finishedAtBefore: Temporal.Instant;
+}
+/** Status filter accepted by workflow cleanup operations. */
+type CleanupStatusFilter = WorkflowTerminalRunStatus | readonly WorkflowTerminalRunStatus[];
+/** Options for workflow retention policy. */
+interface RetentionPolicyOptions extends WorkflowCleanupRunFilterOptions {
+  readonly olderThan: Temporal.Duration;
+  readonly now?: Temporal.Instant;
+}
+interface WorkflowCleanupRunFilterOptions {
+  readonly status?: CleanupStatusFilter;
+  readonly workflowName?: string;
+  readonly workflowVersion?: string;
+  readonly idempotencyKey?: string;
+  readonly parentRunId?: RunId;
+  readonly parentStepId?: StepId;
+  readonly parentStepName?: string;
+  readonly parentStepAttempt?: number;
+  readonly dryRun?: boolean;
+  readonly limit?: number;
+}
+/** Stored record for workflow cleanup marker. */
+interface CleanupMarkerRecord {
+  readonly mode: CleanupMode;
+  readonly runId: RunId;
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly status: WorkflowTerminalRunStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly finishedAt: Temporal.Instant;
+  readonly cleanupStartedAt: Temporal.Instant;
+  readonly events: number;
+  readonly stepAttempts: number;
+  readonly idempotencyKeys: number;
+  readonly messageIdempotencyKeys: number;
+}
+/** Result returned by workflow cleanup runs. */
+interface CleanupRunsResult {
+  readonly mode: CleanupMode;
+  readonly runIds: readonly RunId[];
+  readonly runs: readonly CleanupRunResult[];
+  readonly dryRun?: boolean;
+  readonly matchedRuns?: number;
+  readonly matchedEvents?: number;
+  readonly matchedStepAttempts?: number;
+  readonly matchedIdempotencyKeys?: number;
+  readonly matchedMessageIdempotencyKeys?: number;
+  readonly deletedRuns: number;
+  readonly createdCleanupMarkers: number;
+  readonly deletedCleanupMarkers: number;
+  readonly deletedEvents: number;
+  readonly deletedStepAttempts: number;
+  readonly deletedIdempotencyKeys: number;
+  readonly deletedMessageIdempotencyKeys: number;
+}
+/** Result returned by workflow cleanup run. */
+interface CleanupRunResult {
+  readonly mode: CleanupMode;
+  readonly runId: RunId;
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly status: WorkflowTerminalRunStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly finishedAt: Temporal.Instant;
+  readonly idempotencyKey?: string;
+  readonly parentRunId?: RunId;
+  readonly parentStepId?: StepId;
+  readonly parentStepName?: string;
+  readonly parentStepAttempt?: number;
+  readonly events: number;
+  readonly stepAttempts: number;
+  readonly idempotencyKeys: number;
+  readonly messageIdempotencyKeys: number;
+  readonly cleanupMarkerCreated: boolean;
+  readonly cleanupMarkerDeleted: boolean;
+  readonly runDeleted: boolean;
+  readonly deletedEvents: number;
+  readonly deletedStepAttempts: number;
+  readonly deletedIdempotencyKeys: number;
+  readonly deletedMessageIdempotencyKeys: number;
+}
+//#endregion
+export { CleanupMarkerRecord, CleanupMode, CleanupRunResult, CleanupRunsOptions, CleanupRunsResult, CleanupStatusFilter, RetentionPolicyOptions, workflowCleanupMarkerRecordSchema, workflowCleanupModeSchema };

package/dist/types/cleanup.mjs

@@ -0,0 +1,22 @@
+import { nonBlankStringSchema, nonNegativeSafeIntegerSchema, temporalInstantSchema } from "./common.mjs";
+import { runIdSchema } from "./run-id.mjs";
+import { workflowTerminalRunStatusSchema } from "./run.mjs";
+import { z } from "zod";
+//#region src/types/cleanup.ts
+const workflowCleanupModeSchema = z.literal("best_effort");
+const workflowCleanupMarkerRecordSchema = z.object({
+	mode: workflowCleanupModeSchema,
+	runId: runIdSchema,
+	workflowName: nonBlankStringSchema,
+	workflowVersion: nonBlankStringSchema.optional(),
+	status: workflowTerminalRunStatusSchema,
+	createdAt: temporalInstantSchema,
+	finishedAt: temporalInstantSchema,
+	cleanupStartedAt: temporalInstantSchema,
+	events: nonNegativeSafeIntegerSchema,
+	stepAttempts: nonNegativeSafeIntegerSchema,
+	idempotencyKeys: nonNegativeSafeIntegerSchema,
+	messageIdempotencyKeys: nonNegativeSafeIntegerSchema
+});
+//#endregion
+export { workflowCleanupMarkerRecordSchema, workflowCleanupModeSchema };