@warlock.js/cascade 4.0.47 → 4.0.58

package/cjs/context/database-data-source-context.d.ts

@@ -0,0 +1,29 @@
+import { Context } from "@warlock.js/context";
+import type { DataSource } from "../data-source/data-source";
+type DataSourceContextValue = string | DataSource;
+type DataSourceContextStore = {
+    dataSource?: DataSourceContextValue;
+};
+/**
+ * Database DataSource Context
+ *
+ * Manages the active database connection/data source using AsyncLocalStorage.
+ * Extends the base Context class for consistent API.
+ */
+declare class DatabaseDataSourceContext extends Context<DataSourceContextStore> {
+    /**
+     * Get the current data source
+     */
+    getDataSource(): DataSourceContextValue | undefined;
+    /**
+     * Set the data source in context
+     */
+    setDataSource(dataSource: DataSourceContextValue): void;
+    /**
+     * Build the initial data source store with defaults
+     */
+    buildStore(): DataSourceContextStore;
+}
+export declare const databaseDataSourceContext: DatabaseDataSourceContext;
+export {};
+//# sourceMappingURL=database-data-source-context.d.ts.map

package/cjs/context/database-data-source-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-data-source-context.d.ts","sourceRoot":"","sources":["../../src/context/database-data-source-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,KAAK,sBAAsB,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD,KAAK,sBAAsB,GAAG;IAC5B,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,cAAM,yBAA0B,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACrE;;OAEG;IACI,aAAa,IAAI,sBAAsB,GAAG,SAAS;IAI1D;;OAEG;IACI,aAAa,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI;IAI9D;;OAEG;IACI,UAAU,IAAI,sBAAsB;CAG5C;AAED,eAAO,MAAM,yBAAyB,2BAAkC,CAAC"}

package/cjs/context/database-data-source-context.js

@@ -0,0 +1,28 @@
+'use strict';var context=require('@warlock.js/context');/**
+ * Database DataSource Context
+ *
+ * Manages the active database connection/data source using AsyncLocalStorage.
+ * Extends the base Context class for consistent API.
+ */
+class DatabaseDataSourceContext extends context.Context {
+    /**
+     * Get the current data source
+     */
+    getDataSource() {
+        return this.get("dataSource");
+    }
+    /**
+     * Set the data source in context
+     */
+    setDataSource(dataSource) {
+        this.set("dataSource", dataSource);
+    }
+    /**
+     * Build the initial data source store with defaults
+     */
+    buildStore() {
+        return { dataSource: undefined };
+    }
+}
+const databaseDataSourceContext = new DatabaseDataSourceContext();
+context.contextManager.register("db.datasource", databaseDataSourceContext);exports.databaseDataSourceContext=databaseDataSourceContext;//# sourceMappingURL=database-data-source-context.js.map

package/cjs/context/database-data-source-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-data-source-context.js","sources":["../../src/context/database-data-source-context.ts"],"sourcesContent":[null],"names":["Context","contextManager"],"mappings":"wDASA;;;;;AAKG;AACH,MAAM,yBAA0B,SAAQA,eAA+B,CAAA;AACrE;;AAEG;IACI,aAAa,GAAA;AAClB,QAAA,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;KAC/B;AAED;;AAEG;AACI,IAAA,aAAa,CAAC,UAAkC,EAAA;AACrD,QAAA,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;KACpC;AAED;;AAEG;IACI,UAAU,GAAA;AACf,QAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;KAClC;AACF,CAAA;AAEY,MAAA,yBAAyB,GAAG,IAAI,yBAAyB,GAAG;AAEzEC,sBAAc,CAAC,QAAQ,CAAC,eAAe,EAAE,yBAAyB,CAAC"}

package/cjs/context/database-transaction-context.d.ts

@@ -0,0 +1,31 @@
+import { Context } from "@warlock.js/context";
+interface TransactionContextStore {
+    session?: unknown;
+}
+/**
+ * Database Transaction Context
+ *
+ * Manages database transaction sessions using AsyncLocalStorage.
+ * Extends the base Context class for consistent API.
+ */
+declare class DatabaseTransactionContext extends Context<TransactionContextStore> {
+    /**
+     * Get the current transaction session
+     */
+    getSession<TSession = unknown>(): TSession | undefined;
+    /**
+     * Set the transaction session in context
+     */
+    setSession(session: unknown): void;
+    /**
+     * Exit the transaction context
+     */
+    exit(): void;
+    /**
+     * Build the initial transaction store with defaults
+     */
+    buildStore(): TransactionContextStore;
+}
+export declare const databaseTransactionContext: DatabaseTransactionContext;
+export {};
+//# sourceMappingURL=database-transaction-context.d.ts.map

package/cjs/context/database-transaction-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-transaction-context.d.ts","sourceRoot":"","sources":["../../src/context/database-transaction-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,qBAAqB,CAAC;AAE9D,UAAU,uBAAuB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,cAAM,0BAA2B,SAAQ,OAAO,CAAC,uBAAuB,CAAC;IACvE;;OAEG;IACI,UAAU,CAAC,QAAQ,GAAG,OAAO,KAAK,QAAQ,GAAG,SAAS;IAI7D;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIzC;;OAEG;IACI,IAAI,IAAI,IAAI;IAInB;;OAEG;IACI,UAAU,IAAI,uBAAuB;CAG7C;AAED,eAAO,MAAM,0BAA0B,4BAAmC,CAAC"}

package/cjs/context/database-transaction-context.js

@@ -0,0 +1,34 @@
+'use strict';var context=require('@warlock.js/context');/**
+ * Database Transaction Context
+ *
+ * Manages database transaction sessions using AsyncLocalStorage.
+ * Extends the base Context class for consistent API.
+ */
+class DatabaseTransactionContext extends context.Context {
+    /**
+     * Get the current transaction session
+     */
+    getSession() {
+        return this.get("session");
+    }
+    /**
+     * Set the transaction session in context
+     */
+    setSession(session) {
+        this.set("session", session);
+    }
+    /**
+     * Exit the transaction context
+     */
+    exit() {
+        this.clear();
+    }
+    /**
+     * Build the initial transaction store with defaults
+     */
+    buildStore() {
+        return { session: undefined };
+    }
+}
+const databaseTransactionContext = new DatabaseTransactionContext();
+context.contextManager.register("db.transaction", databaseTransactionContext);exports.databaseTransactionContext=databaseTransactionContext;//# sourceMappingURL=database-transaction-context.js.map

package/cjs/context/database-transaction-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-transaction-context.js","sources":["../../src/context/database-transaction-context.ts"],"sourcesContent":[null],"names":["Context","contextManager"],"mappings":"wDAMA;;;;;AAKG;AACH,MAAM,0BAA2B,SAAQA,eAAgC,CAAA;AACvE;;AAEG;IACI,UAAU,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAyB,CAAC;KACpD;AAED;;AAEG;AACI,IAAA,UAAU,CAAC,OAAgB,EAAA;AAChC,QAAA,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;KAC9B;AAED;;AAEG;IACI,IAAI,GAAA;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;KACd;AAED;;AAEG;IACI,UAAU,GAAA;AACf,QAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;KAC/B;AACF,CAAA;AAEY,MAAA,0BAA0B,GAAG,IAAI,0BAA0B,GAAG;AAE3EC,sBAAc,CAAC,QAAQ,CAAC,gBAAgB,EAAE,0BAA0B,CAAC"}

package/cjs/contracts/database-driver.contract.d.ts

@@ -0,0 +1,143 @@
+import { DriverBlueprintContract } from "./driver-blueprint.contract";
+import type { MigrationDriverContract } from "./migration-driver.contract";
+import type { QueryBuilderContract } from "./query-builder.contract";
+import type { SyncAdapterContract } from "./sync-adapter.contract";
+/** Supported driver lifecycle events. */
+export type DriverEvent = "connected" | "disconnected" | string;
+/** Listener signature for driver lifecycle events. */
+export type DriverEventListener = (...args: unknown[]) => void;
+/** Representation of an opened transaction. */
+export interface DriverTransactionContract<TContext = unknown> {
+    /** Driver-specific transaction context (session, connection, ...). */
+    context: TContext;
+    /** Commit the transaction. */
+    commit(): Promise<void>;
+    /** Rollback the transaction. */
+    rollback(): Promise<void>;
+}
+/** Result returned after insert operations. */
+export type InsertResult<TDocument = unknown> = {
+    document: TDocument;
+};
+/** Result returned after update operations. */
+export type UpdateResult = {
+    modifiedCount: number;
+};
+/**
+ * Database-agnostic update operations.
+ *
+ * Drivers translate these to their native syntax:
+ * - MongoDB: Used as-is (e.g., `{ $set: { age: 31 } }`)
+ * - SQL: Translated to SET/NULL statements (e.g., `SET age = 31`)
+ *
+ * @example
+ * ```typescript
+ * // Set fields
+ * { $set: { age: 31, name: "Alice" } }
+ *
+ * // Remove fields (MongoDB: delete, SQL: SET NULL)
+ * { $unset: { tempField: 1 } }
+ *
+ * // Increment numeric fields
+ * { $inc: { views: 1, likes: 5 } }
+ *
+ * // Combined operations
+ * {
+ *   $set: { status: "active" },
+ *   $unset: { tempData: 1 },
+ *   $inc: { loginCount: 1 }
+ * }
+ * ```
+ */
+export type UpdateOperations = {
+    /** Set field values */
+    $set?: Record<string, unknown>;
+    /** Remove/unset fields (MongoDB: delete field, SQL: SET NULL) */
+    $unset?: Record<string, 1 | true>;
+    /** Increment numeric fields */
+    $inc?: Record<string, number>;
+    /** Decrement numeric fields */
+    $dec?: Record<string, number>;
+    /** Push to arrays (NoSQL only, SQL drivers may ignore) */
+    $push?: Record<string, unknown>;
+    /** Pull from arrays (NoSQL only, SQL drivers may ignore) */
+    $pull?: Record<string, unknown>;
+};
+/**
+ * Unified driver contract used by the model layer.
+ */
+export interface DriverContract {
+    /**
+     * The name of the driver.
+     *
+     * Used for identification, logging, and debugging.
+     *
+     * @example "mongodb", "postgres", "mysql"
+     */
+    readonly name: string;
+    /**
+     * Database blueprint (Information Schema)
+     */
+    readonly blueprint: DriverBlueprintContract;
+    /** Whether the underlying connection is currently established. */
+    readonly isConnected: boolean;
+    /** Establish the underlying database connection/pool. */
+    connect(): Promise<void>;
+    /** Close the underlying database connection/pool. */
+    disconnect(): Promise<void>;
+    /**
+     * Serialize the given data
+     */
+    serialize(data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Deserialize the given data
+     */
+    deserialize(data: Record<string, unknown>): Record<string, unknown>;
+    /** Register event listeners (connected/disconnected/custom). */
+    on(event: DriverEvent, listener: DriverEventListener): void;
+    /** Insert a single document/row into the given table. */
+    insert(table: string, document: Record<string, unknown>, options?: Record<string, unknown>): Promise<InsertResult>;
+    /** Insert multiple documents/rows into the given table. */
+    insertMany(table: string, documents: Record<string, unknown>[], options?: Record<string, unknown>): Promise<InsertResult[]>;
+    /** Update documents/rows matching the filter. */
+    update(table: string, filter: Record<string, unknown>, update: UpdateOperations, options?: Record<string, unknown>): Promise<UpdateResult>;
+    /** Update many documents/rows matching the filter. */
+    updateMany(table: string, filter: Record<string, unknown>, update: UpdateOperations, options?: Record<string, unknown>): Promise<UpdateResult>;
+    /** Replace a single document that matches the provided filter. */
+    replace<T = unknown>(table: string, filter: Record<string, unknown>, document: Record<string, unknown>, options?: Record<string, unknown>): Promise<T | null>;
+    /** Delete a single document that matches the provided filter. */
+    delete(table: string, filter?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    /** Delete documents/rows matching the filter. */
+    deleteMany(table: string, filter?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Remove all records from a table/collection.
+     *
+     * This is a destructive operation that deletes all documents/rows.
+     * Use with caution, especially in production environments.
+     *
+     * @param table - Table/collection name to truncate
+     * @param options - Driver-specific options
+     * @returns Number of records deleted
+     *
+     * @example
+     * ```typescript
+     * // Clear all users
+     * await driver.truncateTable("users");
+     *
+     * // Use in seeders for test data cleanup
+     * await driver.truncateTable("test_data");
+     * ```
+     */
+    truncateTable(table: string, options?: Record<string, unknown>): Promise<number>;
+    /** Obtain a query builder for custom querying. */
+    queryBuilder<T = unknown>(table: string): QueryBuilderContract<T>;
+    /** Start a new transaction scope. */
+    beginTransaction(): Promise<DriverTransactionContract>;
+    /** Perform atomic updates matching the filter. */
+    atomic(table: string, filter: Record<string, unknown>, operations: UpdateOperations, options?: Record<string, unknown>): Promise<UpdateResult>;
+    /** Access the sync adapter used for bulk denormalized updates. */
+    syncAdapter(): SyncAdapterContract;
+    /** Access the migration driver for schema operations. */
+    migrationDriver(): MigrationDriverContract;
+}
+//# sourceMappingURL=database-driver.contract.d.ts.map

package/cjs/contracts/database-driver.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-driver.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/database-driver.contract.ts"],"names":[],"mappings":"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"}

package/cjs/contracts/database-id-generator.contract.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Options for generating the next ID.
+ */
+export type GenerateIdOptions = {
+    /** The table/collection name */
+    table: string;
+    /** Initial ID value for the first record (default: 1) */
+    initialId?: number;
+    /** Amount to increment by for each new record (default: 1) */
+    incrementIdBy?: number;
+};
+/**
+ * ID generator contract for auto-incrementing IDs in NoSQL databases.
+ *
+ * This service generates sequential integer IDs for NoSQL databases (like MongoDB)
+ * that don't have native auto-increment support. It maintains a separate collection
+ * that tracks the last generated ID for each table.
+ *
+ * **Note:** SQL databases (PostgreSQL, MySQL) use native AUTO_INCREMENT/SERIAL
+ * and don't need this service.
+ *
+ * @example
+ * ```typescript
+ * // For MongoDB
+ * const mongoDriver = new MongoDbDriver({ ...config, autoGenerateId: true });
+ * const idGenerator = mongoDriver.getIdGenerator();
+ *
+ * // Generate next ID
+ * const id = await idGenerator.generateNextId({
+ *   table: "users",
+ *   initialId: 1000,
+ *   incrementIdBy: 1
+ * });
+ * console.log(id); // 1000 (first time), 1001 (second time), etc.
+ *
+ * // Get last ID for a table
+ * const lastId = await idGenerator.getLastId("users"); // Returns 1001
+ *
+ * // Manually set last ID (useful for migrations)
+ * await idGenerator.setLastId("users", 5000);
+ * ```
+ */
+export interface IdGeneratorContract {
+    /**
+     * Generate the next ID for a table.
+     *
+     * This method:
+     * 1. Atomically increments the counter in the tracking collection
+     * 2. Returns the new ID
+     * 3. Creates the counter document if it doesn't exist (using initialId)
+     *
+     * The operation is atomic to ensure uniqueness even in concurrent scenarios.
+     *
+     * @param options - Configuration for ID generation
+     * @returns The generated ID
+     *
+     * @example
+     * ```typescript
+     * const id = await idGenerator.generateNextId({
+     *   table: "users",
+     *   initialId: 1000,
+     *   incrementIdBy: 5
+     * });
+     * console.log(id); // 1000, 1005, 1010, etc.
+     * ```
+     */
+    generateNextId(options: GenerateIdOptions): Promise<number>;
+    /**
+     * Get the last generated ID for a table.
+     *
+     * Returns 0 if no IDs have been generated yet for this table.
+     *
+     * @param table - The table/collection name
+     * @returns The last generated ID, or 0 if none exists
+     *
+     * @example
+     * ```typescript
+     * const lastId = await idGenerator.getLastId("users");
+     * console.log(lastId); // 42
+     * ```
+     */
+    getLastId(table: string): Promise<number>;
+    /**
+     * Set the last ID for a table.
+     *
+     * Useful for:
+     * - Migrations: Setting a starting point for IDs
+     * - Manual ID management: Adjusting counters after bulk operations
+     * - Testing: Resetting ID sequences
+     *
+     * @param table - The table/collection name
+     * @param id - The ID to set as the last generated ID
+     *
+     * @example
+     * ```typescript
+     * // Start IDs from 1000
+     * await idGenerator.setLastId("users", 1000);
+     *
+     * // Next generated ID will be 1001
+     * const nextId = await idGenerator.generateNextId({
+     *   table: "users",
+     *   incrementIdBy: 1
+     * });
+     * console.log(nextId); // 1001
+     * ```
+     */
+    setLastId(table: string, id: number): Promise<void>;
+}
+//# sourceMappingURL=database-id-generator.contract.d.ts.map

package/cjs/contracts/database-id-generator.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-id-generator.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/database-id-generator.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD"}

package/cjs/contracts/database-remover.contract.d.ts

@@ -0,0 +1,104 @@
+import type { DeleteStrategy } from "../types";
+/**
+ * Remover service contract for deleting models from the database.
+ *
+ * The remover orchestrates the complete deletion pipeline:
+ * 1. Strategy resolution (options → model static → data source default)
+ * 2. Validation (check if model is new, has primary key)
+ * 3. Event emission (deleting, deleted)
+ * 4. Driver execution (based on strategy: trash, permanent, or soft)
+ * 5. Post-deletion cleanup (mark as new, reset state)
+ *
+ * @example
+ * ```typescript
+ * const user = await User.find(1);
+ * const remover = new DatabaseRemover(user);
+ * const result = await remover.destroy();
+ *
+ * console.log(result.success); // true
+ * console.log(result.strategy); // "trash" | "permanent" | "soft"
+ * console.log(result.deletedCount); // 1
+ * ```
+ */
+export interface RemoverContract {
+    /**
+     * Destroy (delete) the model instance from the database.
+     *
+     * Performs deletion based on the resolved strategy:
+     * - `trash`: Moves to trash collection, then deletes
+     * - `permanent`: Direct deletion
+     * - `soft`: Sets deletedAt timestamp
+     *
+     * Automatically emits lifecycle events and handles cleanup.
+     *
+     * @param options - Remover options
+     * @returns Result containing success status, strategy used, and metadata
+     *
+     * @throws {Error} If model is new (not saved) or if deletion fails
+     *
+     * @example
+     * ```typescript
+     * // Use default strategy
+     * const result = await remover.destroy();
+     *
+     * // Override strategy
+     * await remover.destroy({ strategy: "permanent" });
+     *
+     * // Skip events (silent delete)
+     * await remover.destroy({ skipEvents: true });
+     * ```
+     */
+    destroy(options?: RemoverOptions): Promise<RemoverResult>;
+}
+/**
+ * Options for controlling the destroy operation.
+ */
+export type RemoverOptions = {
+    /**
+     * Override the delete strategy for this operation.
+     * Takes precedence over model static property and data source default.
+     *
+     * @default undefined (uses model static or data source default)
+     */
+    strategy?: DeleteStrategy;
+    /**
+     * Skip lifecycle event emission.
+     * Equivalent to "silent delete" in legacy Cascade.
+     *
+     * @default false
+     */
+    skipEvents?: boolean;
+    /**
+     * Skip sync operations after delete.
+     * Useful when you want to delete without triggering sync updates.
+     *
+     * @default false
+     */
+    skipSync?: boolean;
+};
+/**
+ * Result returned after a successful destroy operation.
+ */
+export type RemoverResult = {
+    /**
+     * Whether the destroy operation succeeded.
+     */
+    success: boolean;
+    /**
+     * Number of records deleted.
+     * - `1` for permanent and trash strategies
+     * - `1` for soft delete (one record updated)
+     * - `0` if deletion failed
+     */
+    deletedCount: number;
+    /**
+     * The delete strategy that was used.
+     */
+    strategy: DeleteStrategy;
+    /**
+     * The trash record (if strategy was "trash").
+     * Contains the original record data that was moved to trash.
+     */
+    trashRecord?: Record<string, unknown>;
+};
+//# sourceMappingURL=database-remover.contract.d.ts.map

package/cjs/contracts/database-remover.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-remover.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/database-remover.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,EAAE,cAAc,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC,CAAC"}

package/cjs/contracts/database-restorer.contract.d.ts

@@ -0,0 +1,143 @@
+import type { Model } from "../model/model";
+/**
+ * Restorer service contract for restoring deleted models from the database.
+ *
+ * The restorer orchestrates the complete restoration pipeline:
+ * 1. Strategy detection (trash vs soft delete)
+ * 2. Record retrieval from trash table or soft-deleted records
+ * 3. ID conflict resolution
+ * 4. Event emission (restoring, restored)
+ * 5. Driver execution (insert back to original table, remove from trash/clear deletedAt)
+ *
+ * @example
+ * ```typescript
+ * const restorer = new DatabaseRestorer(User);
+ * const result = await restorer.restore(123);
+ *
+ * console.log(result.success); // true
+ * console.log(result.strategy); // "trash" | "soft"
+ * console.log(result.restoredCount); // 1
+ * ```
+ */
+export interface RestorerContract {
+    /**
+     * Restore a single deleted record by its ID.
+     *
+     * Resolves the delete strategy from options → model static → data source default.
+     * Handles ID conflicts based on options.
+     *
+     * @param id - The primary key value of the record to restore
+     * @param options - Restorer options
+     * @returns Result containing success status, strategy used, and restored record
+     *
+     * @throws {Error} If strategy is "permanent" (cannot restore permanently deleted records)
+     * @throws {Error} If record not found in trash or soft-deleted records
+     * @throws {Error} If ID conflict and onIdConflict is "fail"
+     *
+     * @example
+     * ```typescript
+     * // Restore with default options (assign new ID if conflict)
+     * const result = await restorer.restore(123);
+     *
+     * // Restore with explicit strategy
+     * await restorer.restore(123, { strategy: "trash" });
+     *
+     * // Restore and fail if ID conflict
+     * await restorer.restore(123, { onIdConflict: "fail" });
+     *
+     * // Silent restore (skip events)
+     * await restorer.restore(123, { skipEvents: true });
+     * ```
+     */
+    restore(id: string | number, options?: RestorerOptions): Promise<RestorerResult>;
+    /**
+     * Restore all deleted records for the model's table.
+     *
+     * Restores all records from the trash table (if using trash strategy)
+     * or all soft-deleted records (if using soft strategy).
+     *
+     * @param options - Restorer options
+     * @returns Result containing success status, strategy used, and aggregate counts
+     *
+     * @example
+     * ```typescript
+     * // Restore all with default options
+     * const result = await restorer.restoreAll();
+     *
+     * // Restore all and fail on any ID conflict
+     * await restorer.restoreAll({ onIdConflict: "fail" });
+     * ```
+     */
+    restoreAll(options?: RestorerOptions): Promise<RestorerResult>;
+}
+/**
+ * Options for controlling the restore operation.
+ */
+export type RestorerOptions = {
+    /**
+     * Override the delete strategy for this operation.
+     * Takes precedence over model static property and data source default.
+     *
+     * Must be "trash" or "soft" (cannot restore permanently deleted records).
+     *
+     * @default undefined (uses model static or data source default)
+     */
+    strategy?: "trash" | "soft";
+    /**
+     * Behavior when the original ID already exists in the target table.
+     *
+     * - `"assignNew"`: Automatically assign a new ID (default)
+     * - `"fail"`: Throw an error if ID conflict occurs
+     *
+     * @default "assignNew"
+     */
+    onIdConflict?: "fail" | "assignNew";
+    /**
+     * Skip lifecycle event emission.
+     * Equivalent to "silent restore".
+     *
+     * @default false
+     */
+    skipEvents?: boolean;
+};
+/**
+ * Result returned after a successful restore operation.
+ */
+export type RestorerResult = {
+    /**
+     * Whether the restore operation succeeded.
+     */
+    success: boolean;
+    /**
+     * Number of records restored.
+     * - `1` for single restore
+     * - `N` for restoreAll (number of records restored)
+     */
+    restoredCount: number;
+    /**
+     * The delete strategy that was used for restoration.
+     * - `"trash"`: Record was restored from trash table
+     * - `"soft"`: Record was restored by clearing deletedAt timestamp
+     */
+    strategy: "trash" | "soft";
+    /**
+     * The restored record data (for single restore only).
+     * Contains the record that was restored, with potentially new ID if conflict occurred.
+     */
+    restoredRecord?: Model;
+    /**
+     * The restored records list
+     */
+    restoredRecords?: Model[];
+    /**
+     * List of ID conflicts that occurred during restoreAll.
+     * Only populated if onIdConflict is "assignNew" and conflicts occurred.
+     */
+    conflicts?: Array<{
+        /** The original ID that conflicted */
+        id: string | number;
+        /** Reason for the conflict */
+        reason: string;
+    }>;
+};
+//# sourceMappingURL=database-restorer.contract.d.ts.map

package/cjs/contracts/database-restorer.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-restorer.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/database-restorer.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,OAAO,CACL,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAE5B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAEpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;IAEvB;;OAEG;IACH,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,sCAAsC;QACtC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QACpB,8BAA8B;QAC9B,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ,CAAC"}