@warlock.js/cascade 4.0.174 → 4.1.2

package/esm/contracts/database-driver.contract.d.mts

@@ -0,0 +1,443 @@
+import { ModelDefaults } from "../types.mjs";
+import { DriverBlueprintContract } from "./driver-blueprint.contract.mjs";
+import { MigrationDriverContract } from "./migration-driver.contract.mjs";
+import { DatabaseDirtyTracker } from "../database-dirty-tracker.mjs";
+import { DatabaseDriver } from "../utils/connect-to-database.mjs";
+import { SQLSerializer } from "../migration/sql-serializer.mjs";
+import { QueryBuilderContract } from "./query-builder.contract.mjs";
+import { SyncAdapterContract } from "./sync-adapter.contract.mjs";
+
+//#region ../../@warlock.js/cascade/src/contracts/database-driver.contract.d.ts
+/** Supported driver lifecycle events. */
+type DriverEvent = "connected" | "disconnected" | string;
+/** Listener signature for driver lifecycle events. */
+type DriverEventListener = (...args: unknown[]) => void;
+/** Representation of an opened transaction (manual pattern). */
+interface DriverTransactionContract<TContext = unknown> {
+  /** Driver-specific transaction context (session, connection, ...). */
+  context: TContext;
+  /** Commit the transaction. */
+  commit(): Promise<void>;
+  /** Rollback the transaction. */
+  rollback(): Promise<void>;
+}
+/**
+ * Transaction context passed to callback-based transaction functions.
+ *
+ * Provides explicit rollback capability - calling rollback() will
+ * throw a TransactionRollbackError to exit the transaction scope.
+ */
+interface TransactionContext {
+  /**
+   * Explicitly rollback the transaction.
+   *
+   * Throws TransactionRollbackError to immediately exit the transaction callback.
+   * The transaction will be rolled back and the error will be re-thrown.
+   *
+   * @param reason - Optional reason for rollback (for logging/debugging)
+   * @throws {TransactionRollbackError}
+   *
+   * @example
+   * ```typescript
+   * await driver.transaction(async (ctx) => {
+   *   if (!isValid) {
+   *     ctx.rollback("Invalid data");
+   *   }
+   * });
+   * ```
+   */
+  rollback(reason?: string): never;
+}
+/** Result returned after insert operations. */
+type InsertResult<TDocument = unknown> = {
+  document: TDocument;
+};
+/** Result returned after update operations. */
+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 }
+ * }
+ * ```
+ */
+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.
+ */
+interface DriverContract {
+  /**
+   * The name of the driver.
+   *
+   * Used for identification, logging, and debugging.
+   *
+   * @example "mongodb", "postgres", "mysql"
+   */
+  readonly name: DatabaseDriver;
+  /**
+   * Database blueprint (Information Schema)
+   */
+  readonly blueprint: DriverBlueprintContract;
+  /**
+   * Driver-specific model defaults.
+   *
+   * These defaults are applied to all models using this driver,
+   * unless overridden by database config or model static properties.
+   *
+   * Examples:
+   * - MongoDB: camelCase naming (createdAt, updatedAt)
+   * - PostgreSQL: snake_case naming (created_at, updated_at)
+   *
+   * @example
+   * ```typescript
+   * // PostgreSQL driver
+   * readonly modelDefaults: Partial<ModelDefaults> = {
+   *   namingConvention: "snake_case",
+   *   createdAtColumn: "created_at",
+   *   updatedAtColumn: "updated_at",
+   *   timestamps: true,
+   * };
+   * ```
+   */
+  readonly modelDefaults?: Partial<ModelDefaults>;
+  /** 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>;
+  /** Get database native client */
+  getClient<Client = unknown>(): Client;
+  /**
+   * Serialize the given data
+   */
+  serialize(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Deserialize the given data
+   */
+  deserialize(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Get the dirty tracker for this driver.
+   *
+   * @param data The initial data snapshot to track
+   */
+  getDirtyTracker(data: Record<string, unknown>): DatabaseDirtyTracker;
+  /** 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>;
+  /** Find one and update a single document that matches the provided filter and return the updated document */
+  findOneAndUpdate<T = unknown>(table: string, filter: Record<string, unknown>, update: Record<string, unknown>, options?: Record<string, unknown>): Promise<T | null>;
+  /**
+   * Upsert (insert or update) a single document/row.
+   *
+   * If a document matching the filter exists, it will be updated.
+   * If no document matches, a new one will be inserted.
+   *
+   * @param table - Target table/collection name
+   * @param filter - Filter conditions to find existing document
+   * @param document - Document data to insert or update
+   * @param options - Driver-specific options (conflict columns for SQL, etc.)
+   * @returns The upserted document
+   *
+   * @example
+   * ```typescript
+   * // PostgreSQL: upsert on unique email
+   * await driver.upsert('users', { email: 'user@example.com' }, {
+   *   email: 'user@example.com',
+   *   name: 'John Doe',
+   *   updatedAt: new Date()
+   * }, { conflictColumns: ['email'] });
+   *
+   * // MongoDB: upsert by filter
+   * await driver.upsert('users', { email: 'user@example.com' }, {
+   *   email: 'user@example.com',
+   *   name: 'John Doe'
+   * });
+   * ```
+   */
+  upsert<T = unknown>(table: string, filter: Record<string, unknown>, document: Record<string, unknown>, options?: Record<string, unknown>): Promise<T>;
+  /**
+   * Find one and delete a single document that matches the provided filter and return the deleted document.
+   *
+   * @param table - Target table/collection name
+   * @param filter - Filter conditions
+   * @param options - Optional delete options
+   * @returns The deleted document or null if not found
+   *
+   * @example
+   * ```typescript
+   * const deleted = await driver.findOneAndDelete('users', { id: 1 });
+   * if (deleted) {
+   *   console.log('Deleted user:', deleted);
+   * }
+   * ```
+   */
+  findOneAndDelete<T = unknown>(table: string, filter: 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 (manual pattern).
+   *
+   * Returns a transaction object with commit/rollback methods.
+   * You are responsible for calling commit() or rollback() and handling cleanup.
+   *
+   * For most use cases, prefer the `transaction()` method which handles
+   * commit/rollback/cleanup automatically.
+   *
+   * @param options - Driver-specific transaction options
+   * @returns Transaction contract with commit/rollback methods
+   *
+   * @example
+   * ```typescript
+   * const tx = await driver.beginTransaction();
+   * try {
+   *   await driver.insert('users', { name: 'Alice' });
+   *   await tx.commit();
+   * } catch (error) {
+   *   await tx.rollback();
+   *   throw error;
+   * }
+   * ```
+   */
+  beginTransaction(options?: Record<string, unknown>): Promise<DriverTransactionContract>;
+  /**
+   * Execute a function within a transaction scope (recommended pattern).
+   *
+   * Automatically commits on success, rolls back on any error, and guarantees
+   * resource cleanup. This is the recommended way to use transactions.
+   *
+   * **Features:**
+   * - Auto-commit on successful callback completion
+   * - Auto-rollback on any thrown error
+   * - Explicit rollback via `ctx.rollback()`
+   * - Guaranteed resource cleanup (connection/session release)
+   * - Returns the callback's return value
+   *
+   * **Limitations:**
+   * - Nested `transaction()` calls are not supported (use `beginTransaction()` with savepoints)
+   * - MongoDB: Requires replica set configuration
+   *
+   * @param fn - Async function to execute within transaction
+   * @param options - Driver-specific transaction options (same as beginTransaction)
+   * @returns The return value of the callback function
+   * @throws {Error} If transaction fails or is explicitly rolled back
+   *
+   * @example
+   * ```typescript
+   * // Auto-commit on success
+   * const user = await driver.transaction(async (ctx) => {
+   *   const result = await driver.insert('users', { name: 'Alice' });
+   *   return result.document;
+   * });
+   *
+   * // Explicit rollback
+   * await driver.transaction(async (ctx) => {
+   *   if (!isValid) {
+   *     ctx.rollback('Validation failed');
+   *   }
+   * });
+   *
+   * // Auto-rollback on error
+   * await driver.transaction(async (ctx) => {
+   *   throw new Error('Oops'); // Automatically rolls back
+   * });
+   * ```
+   */
+  transaction<T>(fn: (ctx: TransactionContext) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  /** 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;
+  /**
+   * Return a SQL serializer for this driver's dialect.
+   * Used by Migration.toSQL() to convert pending operations to SQL strings.
+   */
+  getSQLSerializer(): SQLSerializer;
+  /**
+   * Execute a raw SQL query.
+   * Used by the runner to execute phase-ordered SQL.
+   *
+   * @param sql - SQL query string
+   * @param params - Optional query parameters
+   * @returns Query result
+   */
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<any>;
+  /**
+   * Create a new database.
+   *
+   * Used for multi-tenant scenarios where each tenant gets their own database.
+   *
+   * @param name - Database name to create
+   * @param options - Driver-specific options (encoding, template, etc.)
+   * @returns true if created, false if already exists
+   *
+   * @example
+   * ```typescript
+   * // Create a tenant database
+   * const created = await driver.createDatabase("tenant_xyz");
+   * if (created) {
+   *   console.log("Database created successfully");
+   * }
+   * ```
+   */
+  createDatabase(name: string, options?: CreateDatabaseOptions): Promise<boolean>;
+  /**
+   * Drop a database.
+   *
+   * Use with caution - this permanently deletes the database and all its data.
+   *
+   * @param name - Database name to drop
+   * @param options - Driver-specific options (force, etc.)
+   * @returns true if dropped, false if didn't exist
+   *
+   * @example
+   * ```typescript
+   * // Remove a tenant database
+   * await driver.dropDatabase("tenant_xyz");
+   * ```
+   */
+  dropDatabase(name: string, options?: DropDatabaseOptions): Promise<boolean>;
+  /**
+   * Check if a database exists.
+   *
+   * @param name - Database name to check
+   * @returns true if database exists
+   *
+   * @example
+   * ```typescript
+   * const exists = await driver.databaseExists("tenant_xyz");
+   * if (!exists) {
+   *   await driver.createDatabase("tenant_xyz");
+   * }
+   * ```
+   */
+  databaseExists(name: string): Promise<boolean>;
+  /**
+   * List all databases.
+   *
+   * @returns Array of database names
+   */
+  listDatabases(): Promise<string[]>;
+  /**
+   * Drop a table/collection.
+   *
+   * Throws an error if the table doesn't exist.
+   *
+   * @param name - Table/collection name to drop
+   *
+   * @example
+   * ```typescript
+   * await driver.dropTable("temp_data");
+   * ```
+   */
+  dropTable(name: string): Promise<void>;
+  /**
+   * Drop a table/collection if it exists.
+   *
+   * Does not throw an error if the table doesn't exist.
+   *
+   * @param name - Table/collection name to drop
+   *
+   * @example
+   * ```typescript
+   * await driver.dropTableIfExists("temp_data");
+   * ```
+   */
+  dropTableIfExists(name: string): Promise<void>;
+  /**
+   * Drop all tables/collections in the current database.
+   *
+   * Use with extreme caution - this permanently deletes all tables and data.
+   * Typically used for `migrate:fresh` command or test suite resets.
+   *
+   * @example
+   * ```typescript
+   * // Reset entire database schema
+   * await driver.dropAllTables();
+   * await runMigrations();
+   * ```
+   */
+  dropAllTables(): Promise<void>;
+}
+/**
+ * Options for creating a database.
+ */
+type CreateDatabaseOptions = {
+  /** Database encoding (PostgreSQL: UTF8, LATIN1, etc.) */encoding?: string; /** Template database (PostgreSQL) */
+  template?: string; /** Locale/collation settings */
+  locale?: string; /** Owner of the new database */
+  owner?: string;
+};
+/**
+ * Options for dropping a database.
+ */
+type DropDatabaseOptions = {
+  /** Force drop even if there are active connections */force?: boolean; /** Skip error if database doesn't exist */
+  ifExists?: boolean;
+};
+//#endregion
+export { CreateDatabaseOptions, DriverContract, DriverEvent, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult };
+//# sourceMappingURL=database-driver.contract.d.mts.map

package/esm/contracts/database-driver.contract.d.mts.map

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

package/esm/contracts/database-id-generator.contract.d.mts

@@ -0,0 +1,109 @@
+//#region ../../@warlock.js/cascade/src/contracts/database-id-generator.contract.d.ts
+/**
+ * Options for generating the next ID.
+ */
+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);
+ * ```
+ */
+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>;
+}
+//#endregion
+export { GenerateIdOptions, IdGeneratorContract };
+//# sourceMappingURL=database-id-generator.contract.d.mts.map

package/esm/contracts/database-id-generator.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-id-generator.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/contracts/database-id-generator.contract.ts"],"mappings":";;AAGA;;KAAY,iBAAA;EAAiB,gCAE3B,KAAA,UAEA;EAAA,SAAA,WAEa;EAAb,aAAA;AAAA;;;;;;;;;;;;;;;;;;;;;AAoG6C;;;;;;;;;;;UAlE9B,mBAAA;;;;;;;;;;;;;;;;;;;;;;;;EAwBf,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA;;;;;;;;;;;;;;;EAgB5C,SAAA,CAAU,KAAA,WAAgB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;EA0B1B,SAAA,CAAU,KAAA,UAAe,EAAA,WAAa,OAAA;AAAA"}

package/esm/contracts/database-remover.contract.d.mts

@@ -0,0 +1,108 @@
+import { DeleteStrategy } from "../types.mjs";
+
+//#region ../../@warlock.js/cascade/src/contracts/database-remover.contract.d.ts
+/**
+ * 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
+ * ```
+ */
+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.
+ */
+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.
+ */
+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>;
+};
+//#endregion
+export { RemoverContract, RemoverOptions, RemoverResult };
+//# sourceMappingURL=database-remover.contract.d.mts.map

package/esm/contracts/database-remover.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-remover.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/contracts/database-remover.contract.ts"],"mappings":";;;;;AAuBA;;;;;;;;;;;;;;AA4B0D;AAM1D;;;;UAlCiB,eAAA;EAyCJ;;;;AAgBH;AAMV;;;;;;;;;;;AAuBsB;;;;;;;;;;;EA1DpB,OAAA,CAAQ,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;AAAA;;;;KAMjC,cAAA;;;;;;;EAOV,QAAA,GAAW,cAAc;;;;;;;EAQzB,UAAA;;;;;;;EAQA,QAAA;AAAA;;;;KAMU,aAAA;;;;EAIV,OAAA;;;;;;;EAQA,YAAA;;;;EAKA,QAAA,EAAU,cAAA;;;;;EAMV,WAAA,GAAc,MAAM;AAAA"}