awaitly 2.0.0 → 3.0.0

package/dist/persistence.d.cts

@@ -0,0 +1,254 @@
+import { R as ResumeState, j as ResumeStateEntry } from './types-C9Y71dua.cjs';
+export { J as JSONValue, M as MemoryCacheOptions, m as SerializedCause, n as SnapshotDecodeError, o as SnapshotFormatError, p as SnapshotMismatchError, S as SnapshotStore, q as SnapshotWarning, h as StepResult, b as WorkflowSnapshot, u as assertValidSnapshot, z as createMemoryCache, B as deserializeCauseNew, v as isWorkflowSnapshot, w as looksLikeWorkflowSnapshot, x as mergeSnapshots, D as serializeError, F as serializeThrown, y as validateSnapshot } from './types-C9Y71dua.cjs';
+export { c as isResumeState } from './guards-DhhOJZda.cjs';
+export { P as PersistedWorkflowState, S as SerializedResumeState, a as StoreLoadResult, b as StoreSaveInput, d as deserializeResumeState, i as isSerializedResumeState, s as serializeResumeState, t as toResumeState } from './store-contract-C2HyR_o6.cjs';
+export { W as WorkflowLock } from './index-Bwt-iz50.cjs';
+import { R as Result } from './index-ICmfQi08.cjs';
+import './types-d8q8iQlk.cjs';
+import '@standard-schema/spec';
+import './errors-sDSeaZBO.cjs';
+
+/**
+ * Workflow Versioning and Migration
+ *
+ * Handle schema changes when resuming workflows that were persisted
+ * with older step shapes.
+ *
+ * @example
+ * ```typescript
+ * import { createVersionedWorkflow } from 'awaitly';
+ *
+ * const workflow = createVersionedWorkflow(
+ *   { fetchUser, chargeCard },
+ *   {
+ *     version: 2,
+ *     migrations: {
+ *       1: (state) => migrateV1ToV2(state),
+ *     },
+ *     resumeState: loadState(runId),
+ *   }
+ * );
+ * ```
+ */
+
+/**
+ * Version number type.
+ */
+type Version = number;
+/**
+ * Migration function that transforms state from one version to the next.
+ */
+type MigrationFn = (state: ResumeState) => ResumeState | Promise<ResumeState>;
+/**
+ * Map of migrations keyed by the source version.
+ * Migration at key N transforms state from version N to version N+1.
+ */
+type Migrations = Record<Version, MigrationFn>;
+/**
+ * Versioned state includes the version number.
+ */
+interface VersionedState {
+    version: Version;
+    state: ResumeState;
+}
+/**
+ * Configuration for versioned workflow.
+ */
+interface VersionedWorkflowConfig {
+    /**
+     * Current workflow version.
+     */
+    version: Version;
+    /**
+     * Migrations for upgrading old states.
+     * Key is the source version, value transforms to next version.
+     */
+    migrations?: Migrations;
+    /**
+     * Strict mode - fail if state version is higher than current.
+     * @default true
+     */
+    strictVersioning?: boolean;
+}
+/**
+ * Error when version migration fails.
+ */
+interface MigrationError {
+    type: "MIGRATION_ERROR";
+    fromVersion: Version;
+    toVersion: Version;
+    cause: unknown;
+}
+/**
+ * Error when state version is incompatible.
+ */
+interface VersionIncompatibleError {
+    type: "VERSION_INCOMPATIBLE";
+    stateVersion: Version;
+    currentVersion: Version;
+    reason: string;
+}
+/**
+ * Type guard for MigrationError.
+ */
+declare function isMigrationError(error: unknown): error is MigrationError;
+/**
+ * Type guard for VersionIncompatibleError.
+ */
+declare function isVersionIncompatibleError(error: unknown): error is VersionIncompatibleError;
+/**
+ * Create a versioned resume state loader.
+ *
+ * This wraps a state loader to automatically apply migrations
+ * when loading older state versions.
+ *
+ * @param config - Versioning configuration
+ * @returns A function that loads and migrates state
+ *
+ * @example
+ * ```typescript
+ * const loadVersionedState = createVersionedStateLoader({
+ *   version: 3,
+ *   migrations: {
+ *     1: migrateV1ToV2,
+ *     2: migrateV2ToV3,
+ *   },
+ * });
+ *
+ * // In workflow
+ * const workflow = createWorkflow(deps, {
+ *   resumeState: () => loadVersionedState(savedState),
+ * });
+ * ```
+ */
+declare function createVersionedStateLoader(config: VersionedWorkflowConfig): (versionedState: VersionedState | null | undefined) => Promise<Result<ResumeState | undefined, MigrationError | VersionIncompatibleError>>;
+/**
+ * Create versioned state from current resume state.
+ *
+ * Use this when saving state to storage.
+ *
+ * @param state - The current resume state
+ * @param version - The current workflow version
+ * @returns A versioned state object
+ *
+ * @example
+ * ```typescript
+ * const collector = createResumeStateCollector();
+ * // ... run workflow ...
+ *
+ * const versionedState = createVersionedState(collector.getResumeState(), 2);
+ * await db.saveWorkflowState(workflowId, versionedState);
+ * ```
+ */
+declare function createVersionedState(state: ResumeState, version: Version): VersionedState;
+/**
+ * Parse versioned state from JSON.
+ *
+ * Handles the serialization/deserialization of ResumeState with Map.
+ *
+ * @param json - The JSON string or parsed object
+ * @returns The versioned state or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const json = await db.loadWorkflowState(workflowId);
+ * const versionedState = parseVersionedState(json);
+ * if (versionedState) {
+ *   const loader = createVersionedStateLoader(config);
+ *   const state = await loader(versionedState);
+ * }
+ * ```
+ */
+interface SerializedVersionedState {
+    version: number;
+    state: {
+        steps: Array<[string, ResumeStateEntry]>;
+    };
+}
+declare function parseVersionedState(json: string | SerializedVersionedState | null | undefined): VersionedState | null;
+/**
+ * Serialize versioned state to JSON.
+ *
+ * Converts the Map to an array for JSON serialization.
+ *
+ * @param state - The versioned state
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const json = stringifyVersionedState(versionedState);
+ * await db.saveWorkflowState(workflowId, json);
+ * ```
+ */
+declare function stringifyVersionedState(state: VersionedState): string;
+/**
+ * Create a migration that renames step keys.
+ *
+ * @param renames - Map of old key to new key
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRenameMigration({
+ *     'user:fetch': 'user:load',
+ *     'order:create': 'order:submit',
+ *   }),
+ * };
+ * ```
+ */
+declare function createKeyRenameMigration(renames: Record<string, string>): MigrationFn;
+/**
+ * Create a migration that removes specific step keys.
+ *
+ * @param keysToRemove - Array of keys to remove
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRemoveMigration(['deprecated:step', 'old:cache']),
+ * };
+ * ```
+ */
+declare function createKeyRemoveMigration(keysToRemove: string[]): MigrationFn;
+/**
+ * Create a migration that transforms step values.
+ *
+ * @param transforms - Map of key to transform function
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createValueTransformMigration({
+ *     'user:fetch': (entry) => ({
+ *       ...entry,
+ *       result: entry.result.ok
+ *         ? ok({ ...entry.result.value, newField: 'default' })
+ *         : entry.result,
+ *     }),
+ *   }),
+ * };
+ * ```
+ */
+declare function createValueTransformMigration(transforms: Record<string, (entry: ResumeStateEntry) => ResumeStateEntry>): MigrationFn;
+/**
+ * Compose multiple migrations into a single migration.
+ *
+ * @param migrations - Array of migration functions
+ * @returns A single migration function that applies all migrations in order
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: composeMigrations([
+ *     createKeyRenameMigration({ 'old': 'new' }),
+ *     createKeyRemoveMigration(['deprecated']),
+ *   ]),
+ * };
+ * ```
+ */
+declare function composeMigrations(migrations: MigrationFn[]): MigrationFn;
+
+export { type MigrationError, type MigrationFn, type Migrations, ResumeState, type Version, type VersionIncompatibleError, type VersionedState, type VersionedWorkflowConfig, composeMigrations, createKeyRemoveMigration, createKeyRenameMigration, createValueTransformMigration, createVersionedState, createVersionedStateLoader, isMigrationError, isVersionIncompatibleError, parseVersionedState, stringifyVersionedState };

package/dist/persistence.d.ts

@@ -0,0 +1,254 @@
+import { R as ResumeState, j as ResumeStateEntry } from './types-BDTxgKKc.js';
+export { J as JSONValue, M as MemoryCacheOptions, m as SerializedCause, n as SnapshotDecodeError, o as SnapshotFormatError, p as SnapshotMismatchError, S as SnapshotStore, q as SnapshotWarning, h as StepResult, b as WorkflowSnapshot, u as assertValidSnapshot, z as createMemoryCache, B as deserializeCauseNew, v as isWorkflowSnapshot, w as looksLikeWorkflowSnapshot, x as mergeSnapshots, D as serializeError, F as serializeThrown, y as validateSnapshot } from './types-BDTxgKKc.js';
+export { c as isResumeState } from './guards-CwQZro1F.js';
+export { P as PersistedWorkflowState, S as SerializedResumeState, a as StoreLoadResult, b as StoreSaveInput, d as deserializeResumeState, i as isSerializedResumeState, s as serializeResumeState, t as toResumeState } from './store-contract-BI98VYmX.js';
+export { W as WorkflowLock } from './index-Bew12SZ8.js';
+import { R as Result } from './index-Cv4K_3sZ.js';
+import './types-sObbY4mX.js';
+import '@standard-schema/spec';
+import './errors-sDSeaZBO.js';
+
+/**
+ * Workflow Versioning and Migration
+ *
+ * Handle schema changes when resuming workflows that were persisted
+ * with older step shapes.
+ *
+ * @example
+ * ```typescript
+ * import { createVersionedWorkflow } from 'awaitly';
+ *
+ * const workflow = createVersionedWorkflow(
+ *   { fetchUser, chargeCard },
+ *   {
+ *     version: 2,
+ *     migrations: {
+ *       1: (state) => migrateV1ToV2(state),
+ *     },
+ *     resumeState: loadState(runId),
+ *   }
+ * );
+ * ```
+ */
+
+/**
+ * Version number type.
+ */
+type Version = number;
+/**
+ * Migration function that transforms state from one version to the next.
+ */
+type MigrationFn = (state: ResumeState) => ResumeState | Promise<ResumeState>;
+/**
+ * Map of migrations keyed by the source version.
+ * Migration at key N transforms state from version N to version N+1.
+ */
+type Migrations = Record<Version, MigrationFn>;
+/**
+ * Versioned state includes the version number.
+ */
+interface VersionedState {
+    version: Version;
+    state: ResumeState;
+}
+/**
+ * Configuration for versioned workflow.
+ */
+interface VersionedWorkflowConfig {
+    /**
+     * Current workflow version.
+     */
+    version: Version;
+    /**
+     * Migrations for upgrading old states.
+     * Key is the source version, value transforms to next version.
+     */
+    migrations?: Migrations;
+    /**
+     * Strict mode - fail if state version is higher than current.
+     * @default true
+     */
+    strictVersioning?: boolean;
+}
+/**
+ * Error when version migration fails.
+ */
+interface MigrationError {
+    type: "MIGRATION_ERROR";
+    fromVersion: Version;
+    toVersion: Version;
+    cause: unknown;
+}
+/**
+ * Error when state version is incompatible.
+ */
+interface VersionIncompatibleError {
+    type: "VERSION_INCOMPATIBLE";
+    stateVersion: Version;
+    currentVersion: Version;
+    reason: string;
+}
+/**
+ * Type guard for MigrationError.
+ */
+declare function isMigrationError(error: unknown): error is MigrationError;
+/**
+ * Type guard for VersionIncompatibleError.
+ */
+declare function isVersionIncompatibleError(error: unknown): error is VersionIncompatibleError;
+/**
+ * Create a versioned resume state loader.
+ *
+ * This wraps a state loader to automatically apply migrations
+ * when loading older state versions.
+ *
+ * @param config - Versioning configuration
+ * @returns A function that loads and migrates state
+ *
+ * @example
+ * ```typescript
+ * const loadVersionedState = createVersionedStateLoader({
+ *   version: 3,
+ *   migrations: {
+ *     1: migrateV1ToV2,
+ *     2: migrateV2ToV3,
+ *   },
+ * });
+ *
+ * // In workflow
+ * const workflow = createWorkflow(deps, {
+ *   resumeState: () => loadVersionedState(savedState),
+ * });
+ * ```
+ */
+declare function createVersionedStateLoader(config: VersionedWorkflowConfig): (versionedState: VersionedState | null | undefined) => Promise<Result<ResumeState | undefined, MigrationError | VersionIncompatibleError>>;
+/**
+ * Create versioned state from current resume state.
+ *
+ * Use this when saving state to storage.
+ *
+ * @param state - The current resume state
+ * @param version - The current workflow version
+ * @returns A versioned state object
+ *
+ * @example
+ * ```typescript
+ * const collector = createResumeStateCollector();
+ * // ... run workflow ...
+ *
+ * const versionedState = createVersionedState(collector.getResumeState(), 2);
+ * await db.saveWorkflowState(workflowId, versionedState);
+ * ```
+ */
+declare function createVersionedState(state: ResumeState, version: Version): VersionedState;
+/**
+ * Parse versioned state from JSON.
+ *
+ * Handles the serialization/deserialization of ResumeState with Map.
+ *
+ * @param json - The JSON string or parsed object
+ * @returns The versioned state or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const json = await db.loadWorkflowState(workflowId);
+ * const versionedState = parseVersionedState(json);
+ * if (versionedState) {
+ *   const loader = createVersionedStateLoader(config);
+ *   const state = await loader(versionedState);
+ * }
+ * ```
+ */
+interface SerializedVersionedState {
+    version: number;
+    state: {
+        steps: Array<[string, ResumeStateEntry]>;
+    };
+}
+declare function parseVersionedState(json: string | SerializedVersionedState | null | undefined): VersionedState | null;
+/**
+ * Serialize versioned state to JSON.
+ *
+ * Converts the Map to an array for JSON serialization.
+ *
+ * @param state - The versioned state
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const json = stringifyVersionedState(versionedState);
+ * await db.saveWorkflowState(workflowId, json);
+ * ```
+ */
+declare function stringifyVersionedState(state: VersionedState): string;
+/**
+ * Create a migration that renames step keys.
+ *
+ * @param renames - Map of old key to new key
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRenameMigration({
+ *     'user:fetch': 'user:load',
+ *     'order:create': 'order:submit',
+ *   }),
+ * };
+ * ```
+ */
+declare function createKeyRenameMigration(renames: Record<string, string>): MigrationFn;
+/**
+ * Create a migration that removes specific step keys.
+ *
+ * @param keysToRemove - Array of keys to remove
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRemoveMigration(['deprecated:step', 'old:cache']),
+ * };
+ * ```
+ */
+declare function createKeyRemoveMigration(keysToRemove: string[]): MigrationFn;
+/**
+ * Create a migration that transforms step values.
+ *
+ * @param transforms - Map of key to transform function
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createValueTransformMigration({
+ *     'user:fetch': (entry) => ({
+ *       ...entry,
+ *       result: entry.result.ok
+ *         ? ok({ ...entry.result.value, newField: 'default' })
+ *         : entry.result,
+ *     }),
+ *   }),
+ * };
+ * ```
+ */
+declare function createValueTransformMigration(transforms: Record<string, (entry: ResumeStateEntry) => ResumeStateEntry>): MigrationFn;
+/**
+ * Compose multiple migrations into a single migration.
+ *
+ * @param migrations - Array of migration functions
+ * @returns A single migration function that applies all migrations in order
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: composeMigrations([
+ *     createKeyRenameMigration({ 'old': 'new' }),
+ *     createKeyRemoveMigration(['deprecated']),
+ *   ]),
+ * };
+ * ```
+ */
+declare function composeMigrations(migrations: MigrationFn[]): MigrationFn;
+
+export { type MigrationError, type MigrationFn, type Migrations, ResumeState, type Version, type VersionIncompatibleError, type VersionedState, type VersionedWorkflowConfig, composeMigrations, createKeyRemoveMigration, createKeyRenameMigration, createValueTransformMigration, createVersionedState, createVersionedStateLoader, isMigrationError, isVersionIncompatibleError, parseVersionedState, stringifyVersionedState };