monsqlize 2.0.4 → 2.0.6

package/dist/types/runtime.d.mts

@@ -0,0 +1,387 @@
+import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection.mjs';
+import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base.mjs';
+import type { ModelDefinition, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model.mjs';
+import type { LockOptions, LockStats } from './lock.mjs';
+import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool.mjs';
+import type { SagaDefinition, SagaOrchestratorOptions, SagaResult, SagaStats, SagaStep } from './saga.mjs';
+import type { SlowQueryLogConfig, SlowQueryLogConfigInput, SlowQueryLogEntry, SlowQueryLogFilter, SlowQueryLogQueryOptions, SlowQueryLogRecord, SlowQueryLogStorageConfig } from './slow-query-log.mjs';
+import type { ResumeTokenConfig, SyncChangeEvent, SyncConfig, SyncStats, SyncTargetConfig, SyncTargetHealthCheckConfig } from './sync.mjs';
+import type { MongoSession, TransactionOptions, TransactionStats } from './transaction.mjs';
+import type {
+    CacheLike as HubCacheLike,
+    CacheRemainingTtl as HubCacheRemainingTtl,
+    CacheSetOptions as HubCacheSetOptions,
+    CacheStats as HubCacheStats,
+    LockManager as HubCacheLockLike,
+    MemoryCacheOptions as HubMemoryCacheOptions,
+} from 'cache-hub' with { "resolution-mode": "import" };
+import type {
+    RedisCacheAdapter as HubRedisCacheAdapter,
+    RedisCacheAdapterOptions as HubRedisCacheAdapterOptions,
+} from 'cache-hub/redis' with { "resolution-mode": "import" };
+import type {
+    DistributedInvalidatorOptions as HubDistributedInvalidatorOptions,
+    InvalidatorStats as HubInvalidatorStats,
+} from 'cache-hub/distributed' with { "resolution-mode": "import" };
+import type {
+    FunctionCacheOptions as HubFunctionCacheOptions,
+    FunctionCacheStats as HubFunctionCacheStats,
+    WithCacheOptions as HubWithCacheOptions,
+    WithCacheStats as HubWithCacheStats,
+    WrappedFunction as HubWrappedFunction,
+} from 'cache-hub/function-cache' with { "resolution-mode": "import" };
+
+export { Lock, LockAcquireError, LockTimeoutError, LockManager } from './lock.mjs';
+export { ConnectionPoolManager } from './pool.mjs';
+export { SagaOrchestrator } from './saga.mjs';
+export { BatchQueue, SlowQueryLogConfigManager, SlowQueryLogManager, SlowQueryLogMemoryStorage, MongoDBSlowQueryLogStorage } from './slow-query-log.mjs';
+export { ChangeStreamSyncManager, ResumeTokenStore } from './sync.mjs';
+export { CacheLockManager, Transaction, TransactionManager } from './transaction.mjs';
+
+export declare class Logger {
+    constructor(logger?: LoggerLike | null);
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    static create(logger?: LoggerLike | null): Logger;
+}
+
+export type CacheLockLike = HubCacheLockLike;
+export type CacheLike = HubCacheLike;
+export type CacheRemainingTtl = HubCacheRemainingTtl;
+export type CacheSetOptions = HubCacheSetOptions;
+export type MemoryCacheOptions = HubMemoryCacheOptions;
+
+/**
+ * Multi-level cache write policy.
+ * - `both`: write to both local and remote simultaneously (waits for remote to complete)
+ * - `local-first-async-remote`: return after local write; remote write is asynchronous (reduces tail latency)
+ * @since v1.1.0
+ */
+export type WritePolicy = 'both' | 'local-first-async-remote';
+
+/**
+ * Multi-level cache policy configuration.
+ * @since v1.1.0
+ */
+export interface MultiLevelCachePolicy {
+    /** Write policy; defaults to `both`. */
+    writePolicy?: WritePolicy;
+    /** Whether to backfill the local cache on a remote hit; defaults to true. */
+    backfillLocalOnRemoteHit?: boolean;
+}
+
+/**
+ * Multi-level cache configuration object (declarative two-tier cache setup).
+ *
+ * When passed to `MonSQLizeOptions.cache`, the framework automatically creates a MultiLevelCache:
+ * - `local`: always uses the built-in memory cache (accepts MemoryCacheOptions only)
+ * - `remote`: accepts a CacheLike instance (recommended for production) or a config object
+ *             that degrades to an in-memory placeholder
+ * - `policy`: write policy and backfill policy configuration
+ * @since v1.1.0
+ */
+export interface MultiLevelCacheOptions {
+    multiLevel: true;
+    local?: MemoryCacheOptions;
+    remote?: CacheLike | (MemoryCacheOptions & { timeoutMs?: number });
+    policy?: MultiLevelCachePolicy;
+    publish?: MultiLevelPublish;
+}
+
+export type MultiLevelInvalidationMessage = {
+    type: 'delPattern';
+    pattern: string;
+    ts: number;
+} | {
+    type: 'invalidateTag';
+    tag: string;
+    ts: number;
+};
+
+export type MultiLevelPublish = (msg: MultiLevelInvalidationMessage) => void;
+
+export declare class MemoryCache {
+    constructor(options?: MemoryCacheOptions);
+    setLockManager(lockManager: CacheLockLike): void;
+    getLockManager(): CacheLockLike | null;
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown, ttl?: number, options?: CacheSetOptions): void;
+    del(key: string): boolean;
+    exists(key: string): boolean;
+    has(key: string): boolean;
+    getMany(keys: string[]): Record<string, unknown>;
+    setMany(values: Record<string, unknown>, ttl?: number): boolean;
+    delMany(keys: string[]): number;
+    clear(): void;
+    keys(pattern?: string): string[];
+    delPattern(pattern: string): number;
+    getRemainingTtl(key: string): CacheRemainingTtl | undefined;
+    getRemainingTtlMany(keys: string[]): Record<string, CacheRemainingTtl>;
+    getStats(): CacheStats;
+    resetStats(): void;
+    invalidateByTag(tag: string): void;
+    destroy(): void;
+}
+
+export declare class MultiLevelCache {
+    constructor(options: {
+        local: CacheLike;
+        remote?: CacheLike;
+        writePolicy?: 'both' | 'local-first-async-remote';
+        backfillOnRemoteHit?: boolean;
+        remoteTimeoutMs?: number;
+        publish?: MultiLevelPublish;
+        remoteInvalidationErrors?: 'ignore' | 'throw';
+    });
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, ttl?: number, options?: CacheSetOptions): Promise<void>;
+    del(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    getMany(keys: string[]): Promise<Record<string, unknown>>;
+    setMany(values: Record<string, unknown>, ttl?: number): Promise<boolean>;
+    delMany(keys: string[]): Promise<number>;
+    delPattern(pattern: string): Promise<number>;
+    keys(pattern?: string): Promise<string[]>;
+    invalidateByTag(tag: string): void | Promise<void>;
+    setPublish(publish: MultiLevelPublish): void;
+    setLockManager(lockManager: CacheLockLike): void;
+    getStats(): CacheStats;
+    resetStats(): void;
+    destroy(): void;
+}
+
+export type RedisCacheAdapterOptions = HubRedisCacheAdapterOptions;
+export type RedisLike = object;
+
+/**
+ * Adapts a v1-style CacheLike object to the v2 CacheLike interface.
+ *
+ * v2 requires a `has()` method that was absent in v1. This helper adds it
+ * by delegating to the existing `exists()`. All other methods are forwarded as-is.
+ *
+ * @param v1Cache - A v1 custom cache implementation missing `has()`.
+ * @returns A fully v2-compatible `CacheLike` instance.
+ * @example
+ * ```ts
+ * const v2Cache = adaptLegacyCacheLike(myV1Cache);
+ * const msq = new MonSQLize({ cache: v2Cache });
+ * ```
+ */
+export declare function adaptLegacyCacheLike(v1Cache: Omit<CacheLike, 'has'>): CacheLike;
+
+/** Re-exported alias so consumers can type the return value of `createRedisCacheAdapter`. */
+export type RedisCacheAdapter = HubRedisCacheAdapter;
+
+export declare function createRedisCacheAdapter(
+    redisUrlOrInstance: string | object | undefined,
+    options?: RedisCacheAdapterOptions,
+): HubRedisCacheAdapter;
+
+export type { LockOptions, LockStats, MongoSession, TransactionOptions, TransactionStats };
+
+export type DistributedCacheInvalidatorOptions = HubDistributedInvalidatorOptions;
+export type DistributedCacheInvalidatorStats = HubInvalidatorStats;
+
+export declare class DistributedCacheInvalidator {
+    constructor(options: DistributedCacheInvalidatorOptions);
+    invalidate(pattern: string): Promise<void>;
+    getStats(): HubInvalidatorStats;
+    close(): Promise<void>;
+}
+
+export type {
+    ConnectionPoolManagerOptions,
+    FallbackStrategy,
+    PoolConfig,
+    PoolHealthStatus,
+    PoolRole,
+    PoolStats,
+    PoolStrategy,
+    ResumeTokenConfig,
+    SagaDefinition,
+    SagaOrchestratorOptions,
+    SagaResult,
+    SagaStats,
+    SagaStep,
+    SlowQueryLogConfig,
+    SlowQueryLogConfigInput,
+    SlowQueryLogEntry,
+    SlowQueryLogFilter,
+    SlowQueryLogQueryOptions,
+    SlowQueryLogRecord,
+    SlowQueryLogStorageConfig,
+    SyncChangeEvent,
+    SyncConfig,
+    SyncStats,
+    SyncTargetConfig,
+    SyncTargetHealthCheckConfig,
+};
+
+export declare function validateSyncConfig(config: SyncConfig): void;
+export declare function generateQueryHash(input: unknown): string;
+
+export type WithCacheOptions<
+    T extends (...args: any[]) => Promise<any> = (...args: unknown[]) => Promise<unknown>,
+> = HubWithCacheOptions<T>;
+
+export type CacheStats = HubCacheStats;
+
+export interface WithCacheStats extends HubWithCacheStats {
+    calls: number;
+    totalTime: number;
+    avgTime: number;
+}
+
+export interface FunctionCacheStats extends HubFunctionCacheStats {
+    calls: number;
+    totalTime: number;
+    avgTime: number;
+}
+
+export type CachedFunction<TArgs extends unknown[] = unknown[], TResult = unknown> = HubWrappedFunction<(...args: TArgs) => Promise<TResult>> & {
+    /** @deprecated Use `stats()`. v1 backward-compat alias. */
+    getCacheStats(): WithCacheStats;
+    stats(): WithCacheStats;
+};
+
+export interface FunctionCacheOptions extends HubFunctionCacheOptions {
+    /** @deprecated v1 alias for `ttl`. Use `ttl` instead. */
+    defaultTTL?: number;
+}
+
+export declare function withCache<TArgs extends unknown[], TResult>(
+    fn: (...args: TArgs) => Promise<TResult>,
+    options?: WithCacheOptions<(...args: TArgs) => Promise<TResult>>,
+): CachedFunction<TArgs, TResult>;
+
+export declare class FunctionCache {
+    constructor(cacheOrDb?: CacheLike | { getCache(): CacheLike; }, options?: FunctionCacheOptions);
+    register(name: string, fn: (...args: unknown[]) => Promise<unknown>, options?: {
+        ttl?: number;
+        keyBuilder?: (...args: unknown[]) => string;
+        namespace?: string;
+        condition?: (result: unknown) => boolean;
+    }): Promise<void>;
+    execute(name: string, ...args: unknown[]): Promise<unknown>;
+    invalidate(name: string, ...args: unknown[]): Promise<void>;
+    invalidatePattern(pattern: string): Promise<number>;
+    getStats(name?: string): FunctionCacheStats | Record<string, FunctionCacheStats> | null;
+    list(): string[];
+    resetStats(name?: string): void;
+    clear(): void;
+}
+
+export declare class Model {
+    static define<TDocument = any>(name: string, definition: ModelDefinition<TDocument>): void;
+    static get<TDocument = any>(name: string): RegisteredModel<TDocument> | undefined;
+    static has(name: string): boolean;
+    static list(): string[];
+    static undefine(name: string): boolean;
+    static redefine<TDocument = any>(name: string, definition: ModelDefinition<TDocument>): void;
+    static _clear(): void;
+}
+
+export declare class ModelInstance<TDocument = any> implements ModelInstanceContract<TDocument> {
+    private constructor(...args: unknown[]);
+    readonly collectionName: string;
+    readonly dbName: string;
+    readonly poolName?: string;
+    readonly definition: ModelDefinition<TDocument>;
+    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
+    getRelations(): Record<string, RelationConfig>;
+    getEnums(): Record<string, string>;
+    raw(): unknown;
+    find(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<Array<import('./model.mjs').ModelDocument<TDocument>>>;
+    findOne(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
+    findOneById(id: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
+    findById(id: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
+    findByIds(ids: unknown[], options?: unknown): import('./model.mjs').PopulateProxy<Array<import('./model.mjs').ModelDocument<TDocument>>>;
+    findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model.mjs').PopulateProxy<{
+        items: Array<import('./model.mjs').ModelDocument<TDocument>>;
+        pageInfo: import('./model.mjs').ModelInstance<TDocument> extends {
+            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
+        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
+        totals: import('./model.mjs').ModelInstance<TDocument> extends {
+            findPage(options: { totals: { mode: 'sync'; } & Record<string, unknown>; } & Record<string, unknown>): import('./model.mjs').PopulateProxy<infer TResult>;
+        } ? TResult extends { totals: infer TTotals } ? TTotals : never : never;
+        meta?: import('./collection.mjs').MetaInfo;
+    }>;
+    findPage(options?: unknown): import('./model.mjs').PopulateProxy<{
+        items: Array<import('./model.mjs').ModelDocument<TDocument>>;
+        pageInfo: import('./model.mjs').ModelInstance<TDocument> extends {
+            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
+        } ? TResult extends { pageInfo: infer TPageInfo } ? TPageInfo : never : never;
+        totals?: import('./model.mjs').ModelInstance<TDocument> extends {
+            findPage(options?: unknown): import('./model.mjs').PopulateProxy<infer TResult>;
+        } ? TResult extends { totals?: infer TTotals } ? TTotals : never : never;
+        meta?: import('./collection.mjs').MetaInfo;
+    }>;
+    findAndCount(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<{ data: Array<import('./model.mjs').ModelDocument<TDocument>>; total: number; }>;
+    count(query?: unknown, options?: unknown): Promise<number>;
+    insertOne(document?: unknown, options?: unknown): Promise<{ acknowledged: boolean; insertedId: any; }>;
+    insertMany(documents?: unknown[], options?: unknown): Promise<InsertManyResult>;
+    updateOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    updateMany(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    replaceOne(filter?: unknown, replacement?: unknown, options?: unknown): Promise<UpdateResult>;
+    findOneAndUpdate(filter?: unknown, update?: unknown, options?: unknown): Promise<TDocument | null>;
+    findOneAndDelete(filter?: unknown, options?: unknown): Promise<TDocument | null>;
+    upsertOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    deleteOne(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    deleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    createIndex(keys: unknown, options?: unknown): Promise<IndexCreateResult>;
+    createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
+    listIndexes(): Promise<Record<string, unknown>[]>;
+    ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
+    dropIndex(name: string): Promise<unknown>;
+    dropIndexes(): Promise<unknown>;
+    prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;
+    listBookmarks(keyDims?: unknown): Promise<BookmarkListResult>;
+    clearBookmarks(keyDims?: unknown): Promise<BookmarkClearResult>;
+    distinct(key: string, query?: unknown, options?: unknown): Promise<unknown[]>;
+    aggregate(pipeline?: unknown[], options?: unknown): Promise<unknown[]>;
+    stream(query?: unknown, options?: unknown): NodeJS.ReadableStream;
+    explain(query?: unknown, options?: unknown): Promise<unknown>;
+    invalidate(op?: 'find' | 'findOne' | 'count' | 'findPage' | 'aggregate' | 'distinct'): Promise<number>;
+    dropCollection(): Promise<boolean>;
+    createCollection(name?: string, options?: Record<string, unknown>): Promise<boolean>;
+    createView(name: string, source: string, pipeline?: unknown[]): Promise<boolean>;
+    indexStats(): Promise<unknown[]>;
+    setValidator(validator: unknown, options?: { validationLevel?: string; validationAction?: string }): Promise<{ ok: number; collection: string }>;
+    setValidationLevel(level: 'off' | 'moderate' | 'strict' | string): Promise<{ ok: number; validationLevel: string }>;
+    setValidationAction(action: 'error' | 'warn' | string): Promise<{ ok: number; validationAction: string }>;
+    getValidator(): Promise<{ validator: Record<string, unknown> | null; validationLevel: string; validationAction: string }>;
+    stats(options?: { scale?: number }): Promise<{ ns: string; count: number; size: number; storageSize: number; totalIndexSize: number; nindexes: number; avgObjSize?: number; scaleFactor?: number }>;
+    renameCollection(newName: string, options?: { dropTarget?: boolean }): Promise<{ renamed: boolean; from: string; to: string }>;
+    collMod(modifications: Record<string, unknown>): Promise<Record<string, unknown>>;
+    convertToCapped(size: number, options?: { max?: number }): Promise<{ ok: number; collection: string; capped: boolean; size: number }>;
+    watch(pipeline?: unknown[], options?: unknown): import('mongodb').ChangeStream;
+    validate(document?: unknown): import('./model.mjs').ValidationResult;
+    findOneAndReplace(filter?: unknown, replacement?: unknown, options?: unknown): Promise<TDocument | null>;
+    incrementOne(filter?: unknown, field?: string | Record<string, number>, increment?: number, options?: unknown): Promise<IncrementOneResult<TDocument>>;
+    findWithDeleted(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<Array<import('./model.mjs').ModelDocument<TDocument>>>;
+    findOnlyDeleted(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<Array<import('./model.mjs').ModelDocument<TDocument>>>;
+    findOneWithDeleted(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
+    restore(filter?: unknown, options?: unknown): Promise<import('./model.mjs').RestoreResult>;
+    restoreMany(filter?: unknown, options?: unknown): Promise<import('./model.mjs').RestoreResult>;
+    forceDelete(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    forceDeleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    findOneOnlyDeleted(query?: unknown, options?: unknown): import('./model.mjs').PopulateProxy<import('./model.mjs').ModelDocument<TDocument> | null>;
+    countWithDeleted(query?: unknown, options?: unknown): Promise<number>;
+    countOnlyDeleted(query?: unknown, options?: unknown): Promise<number>;
+    insertBatch(docs: unknown[], options?: unknown): Promise<InsertBatchResult>;
+    updateBatch(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateBatchResult>;
+    deleteBatch(filter?: unknown, options?: unknown): Promise<DeleteBatchResult>;
+}
+
+export declare const expr: ExpressionFunction;
+export declare const createExpression: ExpressionFunction;
+export declare function isExpressionObject(value: unknown): value is ExpressionObject;
+export declare function hasExpressionInObject(value: unknown): boolean;
+export declare function hasExpressionInPipeline(pipeline: unknown): boolean;
+/** Compile expression objects in a MongoDB pipeline into real operators. */
+export declare function compilePipelineExpressions<TPipeline>(pipeline: TPipeline): TPipeline;
+

package/dist/types/runtime.d.ts

@@ -14,22 +14,22 @@ import type {
     CacheStats as HubCacheStats,
     LockManager as HubCacheLockLike,
     MemoryCacheOptions as HubMemoryCacheOptions,
-} from 'cache-hub';
+} from 'cache-hub' with { "resolution-mode": "import" };
 import type {
     RedisCacheAdapter as HubRedisCacheAdapter,
     RedisCacheAdapterOptions as HubRedisCacheAdapterOptions,
-} from 'cache-hub/redis';
+} from 'cache-hub/redis' with { "resolution-mode": "import" };
 import type {
     DistributedInvalidatorOptions as HubDistributedInvalidatorOptions,
     InvalidatorStats as HubInvalidatorStats,
-} from 'cache-hub/distributed';
+} from 'cache-hub/distributed' with { "resolution-mode": "import" };
 import type {
     FunctionCacheOptions as HubFunctionCacheOptions,
     FunctionCacheStats as HubFunctionCacheStats,
     WithCacheOptions as HubWithCacheOptions,
     WithCacheStats as HubWithCacheStats,
     WrappedFunction as HubWrappedFunction,
-} from 'cache-hub/function-cache';
+} from 'cache-hub/function-cache' with { "resolution-mode": "import" };
 
 export { Lock, LockAcquireError, LockTimeoutError, LockManager } from './lock';
 export { ConnectionPoolManager } from './pool';

package/dist/types/saga.d.mts

@@ -0,0 +1,143 @@
+import type { LoggerLike } from './base.mjs';
+
+export interface SagaMetadataCache {
+    set(key: string, value: any, ttl?: number): void | Promise<void>;
+    keys?(pattern?: string): string[] | Promise<string[]>;
+    publish?(channel: string, message: string): void | Promise<unknown>;
+}
+
+/** Execution context passed to each Saga step; provides data sharing between steps. */
+export interface SagaContext {
+    /** Unique ID for this Saga execution run. */
+    readonly executionId: string;
+    /** @deprecated Use `executionId` — v1 compatibility alias. */
+    readonly sagaId?: string;
+    /** Initial data passed to `executeSaga`. */
+    readonly data: any;
+    /** Store a value in the shared step context. */
+    set(key: string, value: any): void;
+    /** Retrieve a previously stored value. v1 compat — default generic is `any` to match v1 callers that did not annotate. */
+    get<T = any>(key: string): T | undefined;
+    /** Return `true` if a value exists for `key`. */
+    has(key: string): boolean;
+    /** Return all stored key-value pairs. */
+    getAll(): Record<string, any>;
+    /**
+     * Ordered list of completed step names.
+     * @deprecated v1 compat — populated automatically by the orchestrator.
+     */
+    readonly completedSteps: string[];
+    /**
+     * Mark a step as completed and record its result.
+     * @deprecated v1 compat — called automatically by the orchestrator. Use `ctx.get(stepName)` to retrieve step results.
+     */
+    markStepCompleted(stepName: string, result: unknown): void;
+    /**
+     * Return the result of a previously completed step.
+     * @deprecated v1 compat — use `ctx.get(stepName)` instead.
+     */
+    getStepResult(stepName: string): unknown;
+    /**
+     * Return an ordered copy of completed step names.
+     * @deprecated v1 compat — use `ctx.getAll()` instead.
+     */
+    getCompletedSteps(): string[];
+}
+
+/** A single step within a Saga, consisting of a forward action and an optional compensation handler. */
+export interface SagaStep {
+    name: string;
+    execute: (context: SagaContext) => Promise<any>;
+    /** Compensation handler — receives the context and the step's own execute result. v1 compat — required so callers may invoke `step.compensate(ctx)` without optional-chaining. */
+    compensate: (context: SagaContext, result?: any) => Promise<void>;
+    /** Per-step timeout in milliseconds (overrides Saga-level timeout). */
+    timeout?: number;
+    /** Number of retry attempts on step failure. */
+    retries?: number;
+}
+
+/** Definition of a Saga, including its ordered steps and execution configuration. */
+export interface SagaDefinition {
+    name: string;
+    steps: SagaStep[];
+    /** Overall Saga timeout in milliseconds. */
+    timeout?: number;
+    /** Whether to emit detailed execution logs. */
+    logging?: boolean;
+}
+
+/** Result returned after a Saga execution (success or failure). */
+export interface SagaResult {
+    /** v2 field — present when emitted by v2 runtime; v1 fixtures may omit. */
+    sagaId?: string;
+    /** Primary v1 field — always present in both v1 and v2 runtime output. */
+    executionId: string;
+    /** v2 field — present when emitted by v2 runtime; v1 fixtures may omit. */
+    sagaName?: string;
+    success: boolean;
+    /** The return value of the last completed step (success path). */
+    result?: any;
+    /** v1-compatible Error object (set when success is false). */
+    error?: Error;
+    /** v2 compatibility alias for message-only consumers. */
+    errorMessage?: string;
+    /** Ordered list of completed step names. */
+    completedSteps: string[];
+    /** v2 compatibility alias for count-only consumers. */
+    completedStepCount?: number;
+    /** @deprecated Alias of `completedSteps` retained for v2 callers. */
+    completedStepNames?: string[];
+    /** Names of steps whose compensation handlers were invoked. v1 compat — runtime always populates an array (empty on success). */
+    compensatedSteps: string[];
+    /** Total execution duration in milliseconds. */
+    duration: number;
+    /** Original Error object (failure path only). v1 compat — `error` field is a string in v2. */
+    errorCause?: any;
+    /** Present on the failure path when at least one completed step has a compensate function. */
+    compensation?: {
+        success: boolean;
+        results: Array<{ stepName: string; success: boolean; reason?: string; error?: string; duration?: number; }>;
+    };
+}
+
+/** Options for constructing a `SagaOrchestrator`. */
+export interface SagaOrchestratorOptions {
+    logger?: LoggerLike | null;
+    cache?: SagaMetadataCache | null;
+}
+
+/** Aggregate statistics for a `SagaOrchestrator` instance. */
+export interface SagaStats {
+    totalExecutions: number;
+    /** @since v1.0.8 — v2 extension; v1 fixtures may omit. */
+    successfulExecutions?: number;
+    /** @since v1.0.8 — v2 extension; v1 fixtures may omit. */
+    failedExecutions?: number;
+    /** @since v1.0.8 — v2 extension; v1 fixtures may omit. */
+    compensatedExecutions?: number;
+    successRate?: string;
+    storageMode?: string;
+    /** Primary v1 field — always present in both v1 and v2 runtime output. */
+    successCount: number;
+    /** Primary v1 field — always present in both v1 and v2 runtime output. */
+    failureCount: number;
+    /** Primary v1 field — always present in both v1 and v2 runtime output. */
+    compensationCount: number;
+}
+
+/** Orchestrates the execution and compensation of multi-step Saga workflows. */
+export declare class SagaOrchestrator {
+    constructor(options?: SagaOrchestratorOptions);
+    /** Register a Saga definition (sync). */
+    define(definition: SagaDefinition): void;
+    /** Register a Saga definition (async; returns the registered definition). */
+    defineSaga(definition: SagaDefinition): Promise<SagaDefinition>;
+    /** Execute the named Saga with the given initial data. */
+    execute(name: string, data: any): Promise<SagaResult>;
+    /** Return the definition for a registered Saga by name. */
+    getSaga(name: string): SagaDefinition | undefined;
+    /** Return the names of all registered Sagas. */
+    listSagas(): string[];
+    /** Return aggregate execution statistics. */
+    getStats(): SagaStats;
+}