@warlock.js/cascade 4.0.171 → 4.1.1

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

@@ -0,0 +1,145 @@
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/contracts/database-restorer.contract.d.ts
+/**
+ * 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
+ * ```
+ */
+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.
+ */
+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.
+ */
+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;
+  }>;
+};
+//#endregion
+export { RestorerContract, RestorerOptions, RestorerResult };
+//# sourceMappingURL=database-restorer.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-restorer.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/contracts/database-restorer.contract.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;;;;;;UAAiB,gBAAA;EAqDJ;;;;AAAkD;AAM/D;;;;;;;;AA2BY;AAMZ;;;;;;;;;;;;;;;EA9DE,OAAA,CACE,EAAA,mBACA,OAAA,GAAU,eAAA,GACT,OAAA,CAAQ,cAAA;EA8FC;;;;AAIJ;;;;;;;;;;;;;;EA9ER,UAAA,CAAW,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,cAAA;AAAA;;;;KAMrC,eAAA;;;;;;;;;EASV,QAAA;;;;;;;;;EAUA,YAAA;;;;;;;EAQA,UAAA;AAAA;;;;KAMU,cAAA;;;;EAIV,OAAA;;;;;;EAOA,aAAA;;;;;;EAOA,QAAA;;;;;EAMA,cAAA,GAAiB,KAAA;;;;EAKjB,eAAA,GAAkB,KAAA;;;;;EAMlB,SAAA,GAAY,KAAA;0CAEV,EAAA;IAEA,MAAA;EAAA;AAAA"}

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

@@ -0,0 +1,123 @@
+import { UpdateOperations } from "./database-driver.contract.mjs";
+
+//#region ../../@warlock.js/cascade/src/contracts/database-writer.contract.d.ts
+/**
+ * Writer service contract for persisting models to the database.
+ *
+ * The writer orchestrates the complete save pipeline:
+ * 1. Validation (via @warlock.js/seal)
+ * 2. ID generation (for new records in NoSQL)
+ * 3. Event emission (validating, saving, created/updated, saved)
+ * 4. Driver execution (insert or update)
+ * 5. Post-save cleanup (reset dirty tracker, update isNew flag)
+ *
+ * @example
+ * ```typescript
+ * const user = new User({ name: "Alice" });
+ * const writer = new DatabaseWriter(user);
+ * const result = await writer.save();
+ *
+ * console.log(result.success); // true
+ * console.log(result.isNew); // true (was an insert)
+ * console.log(result.document); // { _id: ..., id: 1, name: "Alice" }
+ * ```
+ */
+interface WriterContract {
+  /**
+   * Save the model instance to the database.
+   *
+   * Performs insert if `model.isNew === true`, otherwise performs update.
+   * Automatically validates, casts, generates IDs, and emits lifecycle events.
+   *
+   * @param options - Save options
+   * @returns Result containing success status, document, and metadata
+   *
+   * @throws {ValidationError} If validation fails
+   * @throws {Error} If database operation fails
+   *
+   * @example
+   * ```typescript
+   * // Insert
+   * const user = new User({ name: "Alice" });
+   * const writer = new DatabaseWriter(user);
+   * await writer.save();
+   *
+   * // Update
+   * user.set("name", "Bob");
+   * await writer.save();
+   *
+   * // Skip validation
+   * await writer.save({ skipValidation: true });
+   *
+   * // Skip events (silent save)
+   * await writer.save({ skipEvents: true });
+   * ```
+   */
+  save(options?: WriterOptions): Promise<WriterResult>;
+}
+/**
+ * Options for controlling the save operation.
+ */
+type WriterOptions = {
+  /**
+   * Skip validation and casting.
+   * Useful when data is already validated or for performance-critical operations.
+   *
+   * @default false
+   */
+  skipValidation?: boolean;
+  /**
+   * Skip lifecycle event emission.
+   * Equivalent to "silent save" in legacy Cascade.
+   *
+   * @default false
+   */
+  skipEvents?: boolean;
+  /**
+   * Skip sync operations after save.
+   * Useful when you want to save without triggering sync updates.
+   *
+   * @default false
+   */
+  skipSync?: boolean;
+  /**
+   * Replace entire document with the new data.
+   * By default, Model will only update or unset the dirty changes.
+   * @default false
+   */
+  replace?: boolean;
+};
+/**
+ * Result returned after a successful save operation.
+ */
+type WriterResult = {
+  /**
+   * Whether the save operation succeeded.
+   */
+  success: boolean;
+  /**
+   * The saved document with all database-generated fields.
+   * Includes _id, id, timestamps, etc.
+   */
+  document: Record<string, unknown>;
+  /**
+   * Whether this was an insert operation.
+   * - `true`: New record was created
+   * - `false`: Existing record was updated
+   */
+  isNew: boolean;
+  /**
+   * Number of records modified (for updates only).
+   * Undefined for insert operations.
+   */
+  modifiedCount?: number;
+};
+/**
+ * Internal type for building update operations from dirty tracker.
+ *
+ * @internal
+ */
+type BuildUpdateOperationsResult = UpdateOperations;
+//#endregion
+export { BuildUpdateOperationsResult, WriterContract, WriterOptions, WriterResult };
+//# sourceMappingURL=database-writer.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-writer.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/contracts/database-writer.contract.ts"],"mappings":";;;;;AAuBA;;;;;;;;;;;;;;AA+BqD;AAMrD;;;;UArCiB,cAAA;EAoDf;;;;AAeO;AAMT;;;;;;;;;;AAuBe;AAQf;;;;AAA0D;;;;;;;;;;EAzExD,IAAA,CAAK,OAAA,GAAU,aAAA,GAAgB,OAAA,CAAQ,YAAA;AAAA;;;;KAM7B,aAAA;;;;;;;EAOV,cAAA;;;;;;;EAQA,UAAA;;;;;;;EAQA,QAAA;;;;;;EAOA,OAAA;AAAA;;;;KAMU,YAAA;;;;EAIV,OAAA;;;;;EAMA,QAAA,EAAU,MAAM;;;;;;EAOhB,KAAA;;;;;EAMA,aAAA;AAAA;;;;;;KAQU,2BAAA,GAA8B,gBAAgB"}

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

@@ -0,0 +1,52 @@
+//#region ../../@warlock.js/cascade/src/contracts/driver-blueprint.contract.d.ts
+interface DriverBlueprintContract {
+  /**
+   * Get tables list
+   */
+  listTables(): Promise<string[]>;
+  /**
+   * Get all indexes of the given table
+   */
+  listIndexes(table: string): Promise<TableIndexInformation[]>;
+  /**
+   * Get all tables of the database
+   */
+  listTables(): Promise<string[]>;
+  /**
+   * Get all columns of the given table
+   */
+  listColumns(table: string): Promise<string[]>;
+  /**
+   * Check if the given table exists
+   */
+  tableExists(table: string): Promise<boolean>;
+}
+type TableIndexInformation = {
+  /**
+   * Index name
+   */
+  name: string;
+  /**
+   * Index columns
+   */
+  columns?: string[];
+  /**
+   * Index type
+   */
+  type?: string;
+  /**
+   * Index unique
+   */
+  unique: boolean;
+  /**
+   * Index partial
+   */
+  partial: boolean;
+  /**
+   * Index options
+   */
+  options: Record<string, any>;
+};
+//#endregion
+export { DriverBlueprintContract, TableIndexInformation };
+//# sourceMappingURL=driver-blueprint.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"driver-blueprint.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/contracts/driver-blueprint.contract.ts"],"mappings":";UAAiB,uBAAA;EAAA;;;EAIf,UAAA,IAAc,OAAA;EAIsB;;;EAApC,WAAA,CAAY,KAAA,WAAgB,OAAA,CAAQ,qBAAA;EAeR;;;EAV5B,UAAA,IAAc,OAAA;EATA;;;EAcd,WAAA,CAAY,KAAA,WAAgB,OAAA;EAVQ;;;EAepC,WAAA,CAAY,KAAA,WAAgB,OAAA;AAAA;AAAA,KAGlB,qBAAA;EAHV;;;EAOA,IAAA;EAPmC;AAGrC;;EASE,OAAA;EAoBe;;;EAff,IAAA;EAKA;;;EAAA,MAAA;EAUe;AAAA;;EALf,OAAA;;;;EAKA,OAAA,EAAS,MAAM;AAAA"}

package/esm/contracts/index.d.mts

@@ -0,0 +1,9 @@
+import { DriverBlueprintContract, TableIndexInformation } from "./driver-blueprint.contract.mjs";
+import { ColumnDefinition, ColumnType, ForeignKeyDefinition, FullTextIndexOptions, GeoIndexOptions, IndexDefinition, MigrationDriverContract, MigrationDriverFactory, VectorIndexOptions } from "./migration-driver.contract.mjs";
+import { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, DriverQuery, GroupByInput, HavingInput, JoinOptions, OrderDirection, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression, WhereCallback, WhereObject, WhereOperator } from "./query-builder.contract.mjs";
+import { SyncAdapterContract, SyncInstruction } from "./sync-adapter.contract.mjs";
+import { CreateDatabaseOptions, DriverContract, DriverEvent, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult } from "./database-driver.contract.mjs";
+import { GenerateIdOptions, IdGeneratorContract } from "./database-id-generator.contract.mjs";
+import { RemoverContract, RemoverOptions, RemoverResult } from "./database-remover.contract.mjs";
+import { RestorerContract, RestorerOptions, RestorerResult } from "./database-restorer.contract.mjs";
+import { BuildUpdateOperationsResult, WriterContract, WriterOptions, WriterResult } from "./database-writer.contract.mjs";