@warlock.js/cascade 4.0.174 → 4.1.1

package/esm/utils/connect-to-database.d.mts

@@ -0,0 +1,328 @@
+import { DeleteStrategy, MigrationDefaults, ModelDefaults, RelationDefaults } from "../types.mjs";
+import { DriverContract, TransactionContext } from "../contracts/database-driver.contract.mjs";
+import { DataSource } from "../data-source/data-source.mjs";
+
+//#region ../../@warlock.js/cascade/src/utils/connect-to-database.d.ts
+/**
+ * Supported database driver types.
+ */
+type DatabaseDriver = "mongodb" | "postgres" | "mysql";
+/**
+ * Default model configuration options.
+ *
+ * These settings will be applied to all models using this data source,
+ * unless overridden by individual model static properties.
+ *
+ * This is a re-export of Partial<ModelDefaults> for backward compatibility
+ * and to provide clearer naming in the connection config context.
+ *
+ * The full hierarchy is:
+ * 1. Model static property (highest priority)
+ * 2. Database config modelDefaults (this type)
+ * 3. Driver defaults (e.g., snake_case for PostgreSQL, camelCase for MongoDB)
+ * 4. Framework defaults (fallback values)
+ *
+ * @see ModelDefaults for complete type definition and documentation
+ */
+type ModelDefaultConfig = Partial<ModelDefaults>;
+/**
+ * Connection options for establishing a database connection.
+ *
+ * Generic type that separates concerns:
+ * - Shared config (driver, name, database, connection details)
+ * - Driver options (cascade-next driver-specific settings)
+ * - Client options (native database client settings)
+ * - Model options (default model behaviors)
+ *
+ * @template TDriverOptions - Driver-specific options (e.g., MongoDriverOptions)
+ * @template TClientOptions - Native client options (e.g., MongoClientOptions from mongodb package)
+ *
+ * @example
+ * ```typescript
+ * // MongoDB
+ * import type { MongoClientOptions } from "mongodb";
+ * import type { MongoDriverOptions } from "@warlock.js/cascade";
+ *
+ * const config: ConnectionOptions<MongoDriverOptions, MongoClientOptions> = {
+ *   driver: "mongodb",
+ *   database: "myapp",
+ *   host: "localhost",
+ *   port: 27017,
+ *   driverOptions: {
+ *     autoGenerateId: true,
+ *     counterCollection: "counters",
+ *   },
+ *   clientOptions: {
+ *     minPoolSize: 5,
+ *     maxPoolSize: 10,
+ *   },
+ *   modelOptions: {
+ *     randomIncrement: true,
+ *     initialId: 1000,
+ *   },
+ * };
+ * ```
+ */
+type ConnectionOptions<TDriverOptions = any, TClientOptions = any> = {
+  /**
+   * Database driver to use.
+   * @default "mongodb"
+   */
+  driver?: DatabaseDriver;
+  /**
+   * Unique name for this data source.
+   * Used for registration in DataSourceRegistry.
+   * @default "default"
+   */
+  name?: string;
+  /**
+   * Whether this should be the default data source.
+   * @default true
+   */
+  isDefault?: boolean;
+  /**
+   * Database name (required).
+   */
+  database: string;
+  /**
+   * Enable database operation logging (queries, execution time, parameters).
+   * Highly recommended to keep this disabled in production to prevent sensitive data leakage.
+   *
+   * @default false
+   */
+  logging?: boolean;
+  /**
+   * Database connection URI.
+   * Alternative to specifying host/port separately.
+   *
+   * @example "mongodb://localhost:27017/mydb"
+   * @example "postgresql://user:pass@localhost:5432/mydb"
+   */
+  uri?: string;
+  /**
+   * Database host.
+   * @default "localhost"
+   */
+  host?: string;
+  /**
+   * Database port.
+   * @default 27017 (MongoDB), 5432 (PostgreSQL)
+   */
+  port?: number;
+  /**
+   * Database username for authentication.
+   */
+  username?: string;
+  /**
+   * Database password for authentication.
+   */
+  password?: string;
+  /**
+   * Authentication source database.
+   * Typically "admin" for MongoDB.
+   */
+  authSource?: string;
+  /**
+   * Driver-specific options.
+   *
+   * For MongoDB: { autoGenerateId, counterCollection, transactionOptions }
+   * For PostgreSQL: { schema, ... }
+   */
+  driverOptions?: TDriverOptions;
+  /**
+   * Native database client options.
+   *
+   * For MongoDB: MongoClientOptions from 'mongodb' package
+   * For PostgreSQL: PoolConfig from 'pg' package
+   */
+  clientOptions?: TClientOptions;
+  /**
+   * Default model configuration for all models using this data source.
+   *
+   * These settings override driver defaults but are overridden by
+   * individual model static properties.
+   *
+   * **Configuration Hierarchy (highest to lowest):**
+   * 1. Model static property - `User.createdAtColumn = "creation_date"`
+   * 2. **modelOptions (this)** - Database-wide overrides
+   * 3. Driver defaults - PostgreSQL: snake_case, MongoDB: camelCase
+   * 4. Framework defaults - Fallback values
+   *
+   * @example
+   * ```typescript
+   * // PostgreSQL database with custom settings
+   * {
+   *   driver: "postgres",
+   *   modelOptions: {
+   *     // Override PostgreSQL default (snake_case) to use camelCase
+   *     namingConvention: "camelCase",
+   *     createdAtColumn: "createdAt",
+   *     updatedAtColumn: "updatedAt",
+   *
+   *     // ID generation settings (for MongoDB)
+   *     randomIncrement: true,
+   *     initialId: 1000,
+   *
+   *     // Deletion settings
+   *     deleteStrategy: "soft",
+   *     trashTable: "archive", // All models use same trash table
+   *   }
+   * }
+   *
+   * // MongoDB database with defaults
+   * {
+   *   driver: "mongodb",
+   *   modelOptions: {
+   *     // MongoDB already uses camelCase by default
+   *     randomIncrement: true,
+   *     initialId: 10000,
+   *     deleteStrategy: "trash", // Use RecycleBin
+   *   }
+   * }
+   * ```
+   */
+  modelOptions?: ModelDefaultConfig;
+  /**
+   * Migration-level defaults (UUID strategy, etc.).
+   *
+   * These defaults override driver migration defaults but can be
+   * overridden by individual migration calls.
+   *
+   * @default undefined (uses driver defaults)
+   *
+   * @example
+   * ```typescript
+   * migrationDefaults: {
+   *   uuidStrategy: "v7", // Use UUID v7 for all migrations
+   * }
+   * ```
+   */
+  migrationOptions?: MigrationDefaults;
+  /**
+   * Defaults for relation conventions — foreign-key suffix and pivot-table
+   * naming order. Controls how `@BelongsTo` / `@HasOne` / `@HasMany` /
+   * `@BelongsToMany` infer column / table names when none are explicitly
+   * configured on the decorator.
+   *
+   * @default undefined (uses framework defaults: `"_id"` suffix + alphabetical pivot)
+   *
+   * @example
+   * ```typescript
+   * relationOptions: {
+   *   foreignKeySuffix: "_id",
+   *   pivotTableNamingOrder: "alphabetical",
+   * }
+   * ```
+   */
+  relationOptions?: RelationDefaults;
+  /**
+   * Default delete strategy for models using this data source.
+   *
+   * - MongoDB: Typically `"trash"` (uses RecycleBin collection)
+   * - PostgreSQL: Typically `"permanent"` or `"soft"`
+   *
+   * Can be overridden by model static property or destroy() options.
+   *
+   * @default undefined (falls back to "permanent")
+   */
+  defaultDeleteStrategy?: DeleteStrategy;
+  /**
+   * Default trash table/collection name for "trash" delete strategy.
+   *
+   * - MongoDB: Typically `"RecycleBin"`
+   * - If not set, defaults to `{table}Trash` pattern
+   *
+   * Can be overridden by Model.trashTable static property.
+   *
+   * @default undefined (uses {table}Trash pattern)
+   */
+  defaultTrashTable?: string;
+  /**
+   * Migration configuration options.
+   */
+  migrations?: {
+    /**
+     * Whether to wrap migrations in database transactions.
+     *
+     * Overrides driver defaults:
+     * - PostgreSQL default: `true` (DDL is transactional)
+     * - MongoDB default: `false` (DDL cannot be transactional)
+     *
+     * Individual migrations can override this with their own `transactional` property.
+     *
+     * @default undefined (uses driver default)
+     */
+    transactional?: boolean;
+    /**
+     * Name of the migrations tracking table/collection.
+     *
+     * @default "_migrations"
+     */
+    table?: string;
+  };
+};
+/**
+ * Connect to a database and register the data source.
+ *
+ * This is a high-level utility function that simplifies database connection
+ * for small to medium projects. It handles driver instantiation, connection,
+ * data source creation, and automatic registration.
+ *
+ * **Supported Drivers:**
+ * - `mongodb` (default) - MongoDB driver with optional auto ID generation
+ * - `postgres` - PostgreSQL driver (not yet implemented)
+ * - `mysql` - MySQL driver (not yet implemented)
+ *
+ * **Features:**
+ * - Automatic driver instantiation based on driver name
+ * - Connection establishment and error handling
+ * - DataSource creation and registration
+ * - Support for MongoDB-specific features (ID generation, transactions)
+ *
+ * @param options - Connection configuration options
+ * @returns A connected and registered DataSource instance
+ * @throws {Error} If connection fails or driver is not implemented
+ *
+ * @example
+ * ```typescript
+ * // MongoDB with new structure
+ * const dataSource = await connectToDatabase({
+ *   driver: "mongodb",
+ *   database: "myapp",
+ *   host: "localhost",
+ *   port: 27017,
+ *   driverOptions: {
+ *     autoGenerateId: true,
+ *   },
+ *   clientOptions: {
+ *     minPoolSize: 5,
+ *     maxPoolSize: 10,
+ *   },
+ *   modelOptions: {
+ *     randomIncrement: true,
+ *     initialId: 1000,
+ *   },
+ * });
+ * ```
+ */
+declare function connectToDatabase<TDriverOptions = any, TClientOptions = any>(options: ConnectionOptions<TDriverOptions, TClientOptions>): Promise<DataSource>;
+/**
+ * Get current driver instance.
+ *
+ * @example
+ * ```typescript
+ * const driver = getDatabaseDriver();
+ *
+ * // Pass type to return Postgres driver type
+ * const pgDriver = getDatabaseDriver<PostgresDriver>();
+ * ```
+ */
+declare function getDatabaseDriver<T extends DriverContract = any>(): T;
+/**
+ * Perform database transaction(s)
+ * Shorthand to `dataSourceRegister.get().driver.transaction
+ */
+declare function transaction<T = any>(fn: (ctx: TransactionContext) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+//#endregion
+export { ConnectionOptions, DatabaseDriver, ModelDefaultConfig, connectToDatabase, getDatabaseDriver, transaction };
+//# sourceMappingURL=connect-to-database.d.mts.map

package/esm/utils/connect-to-database.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-database.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/connect-to-database.ts"],"mappings":";;;;;;;;KAUY,cAAA;;;;AAAc;AAmB1B;;;;AAAsD;AAwCtD;;;;;;;;KAxCY,kBAAA,GAAqB,OAAO,CAAC,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0RhC;AAgDT;;;KAlSY,iBAAA;EAmSiC;;;;EA1R3C,MAAA,GAAS,cAAA;EA2RD;;;;;EApRR,IAAA;EAmRA;;;;EA7QA,SAAA;EA2Wc;;;EAtWd,QAAA;EAsWgC;;;;AAAoC;AAUtE;EAxWE,OAAA;EAwW+B;;;;;;;EA3V/B,GAAA;EA8VQ;;;;EAxVR,IAAA;EAsVyC;;;;EAhVzC,IAAA;EAkVS;;AAAC;EA7UV,QAAA;;;;EAKA,QAAA;;;;;EAMA,UAAA;;;;;;;EAYA,aAAA,GAAgB,cAAA;;;;;;;EAYhB,aAAA,GAAgB,cAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmDhB,YAAA,GAAe,kBAAA;;;;;;;;;;;;;;;;EAiBf,gBAAA,GAAmB,iBAAA;;;;;;;;;;;;;;;;;EAkBnB,eAAA,GAAkB,gBAAA;;;;;;;;;;;EAgBlB,qBAAA,GAAwB,cAAA;;;;;;;;;;;EAYxB,iBAAA;;;;EASA,UAAA;;;;;;;;;;;;IAYE,aAAA;;;;;;IAOA,KAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgDkB,iBAAA,4CAAA,CACpB,OAAA,EAAS,iBAAA,CAAkB,cAAA,EAAgB,cAAA,IAC1C,OAAA,CAAQ,UAAA;;;;;;;;;;;;iBA6FK,iBAAA,WAA4B,cAAA,OAAA,CAAA,GAAyB,CAAC;;;;;iBAUhD,WAAA,SAAA,CACpB,EAAA,GAAK,GAAA,EAAK,kBAAA,KAAuB,OAAA,CAAQ,CAAA,GACzC,OAAA,GAAU,MAAA,oBACT,OAAA,CAAQ,CAAA"}

package/esm/utils/connect-to-database.mjs

@@ -0,0 +1,130 @@
+import { DataSource } from "../data-source/data-source.mjs";
+import { dataSourceRegistry } from "../data-source/data-source-registry.mjs";
+import { MongoDbDriver } from "../drivers/mongodb/mongodb-driver.mjs";
+import { PostgresDriver } from "../drivers/postgres/postgres-driver.mjs";
+import "../drivers/postgres/index.mjs";
+
+//#region ../../@warlock.js/cascade/src/utils/connect-to-database.ts
+/**
+* Connect to a database and register the data source.
+*
+* This is a high-level utility function that simplifies database connection
+* for small to medium projects. It handles driver instantiation, connection,
+* data source creation, and automatic registration.
+*
+* **Supported Drivers:**
+* - `mongodb` (default) - MongoDB driver with optional auto ID generation
+* - `postgres` - PostgreSQL driver (not yet implemented)
+* - `mysql` - MySQL driver (not yet implemented)
+*
+* **Features:**
+* - Automatic driver instantiation based on driver name
+* - Connection establishment and error handling
+* - DataSource creation and registration
+* - Support for MongoDB-specific features (ID generation, transactions)
+*
+* @param options - Connection configuration options
+* @returns A connected and registered DataSource instance
+* @throws {Error} If connection fails or driver is not implemented
+*
+* @example
+* ```typescript
+* // MongoDB with new structure
+* const dataSource = await connectToDatabase({
+*   driver: "mongodb",
+*   database: "myapp",
+*   host: "localhost",
+*   port: 27017,
+*   driverOptions: {
+*     autoGenerateId: true,
+*   },
+*   clientOptions: {
+*     minPoolSize: 5,
+*     maxPoolSize: 10,
+*   },
+*   modelOptions: {
+*     randomIncrement: true,
+*     initialId: 1000,
+*   },
+* });
+* ```
+*/
+async function connectToDatabase(options) {
+	const driverType = options.driver ?? "mongodb";
+	const dataSourceName = options.name ?? "default";
+	const isDefault = options.isDefault ?? true;
+	let driver;
+	switch (driverType) {
+		case "mongodb":
+			driver = new MongoDbDriver({
+				database: options.database,
+				uri: options.uri,
+				host: options.host,
+				port: options.port,
+				username: options.username,
+				password: options.password,
+				authSource: options.authSource,
+				logging: options.logging,
+				clientOptions: options.clientOptions
+			}, options.driverOptions);
+			break;
+		case "postgres":
+			driver = new PostgresDriver({
+				database: options.database,
+				connectionString: options.uri,
+				host: options.host,
+				port: options.port ?? 5432,
+				user: options.username,
+				password: options.password,
+				logging: options.logging,
+				...options.clientOptions
+			});
+			break;
+		case "mysql": throw new Error("MySQL driver is not yet implemented. Coming soon!");
+		default: throw new Error(`Unknown driver: "${driverType}". Supported drivers: mongodb, postgres, mysql`);
+	}
+	const dataSource = new DataSource({
+		name: dataSourceName,
+		driver,
+		isDefault,
+		defaultDeleteStrategy: options.defaultDeleteStrategy,
+		defaultTrashTable: options.defaultTrashTable,
+		modelDefaults: options.modelOptions,
+		migrationDefaults: options.migrationOptions,
+		relationDefaults: options.relationOptions,
+		migrations: options.migrations
+	});
+	dataSourceRegistry.register(dataSource);
+	try {
+		await driver.connect();
+	} catch (error) {
+		console.log(error);
+		throw new Error(`Failed to connect to ${driverType} database: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return dataSource;
+}
+/**
+* Get current driver instance.
+*
+* @example
+* ```typescript
+* const driver = getDatabaseDriver();
+*
+* // Pass type to return Postgres driver type
+* const pgDriver = getDatabaseDriver<PostgresDriver>();
+* ```
+*/
+function getDatabaseDriver() {
+	return dataSourceRegistry.get().driver;
+}
+/**
+* Perform database transaction(s)
+* Shorthand to `dataSourceRegister.get().driver.transaction
+*/
+async function transaction(fn, options) {
+	return getDatabaseDriver().transaction(fn, options);
+}
+
+//#endregion
+export { connectToDatabase, getDatabaseDriver, transaction };
+//# sourceMappingURL=connect-to-database.mjs.map

package/esm/utils/connect-to-database.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-database.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/connect-to-database.ts"],"sourcesContent":["import { DriverContract, TransactionContext } from \"../contracts\";\nimport { DataSource } from \"../data-source/data-source\";\nimport { dataSourceRegistry } from \"../data-source/data-source-registry\";\nimport { MongoDbDriver } from \"../drivers/mongodb/mongodb-driver\";\nimport { PostgresDriver } from \"../drivers/postgres\";\nimport type { DeleteStrategy, MigrationDefaults, ModelDefaults, RelationDefaults } from \"../types\";\n\n/**\n * Supported database driver types.\n */\nexport type DatabaseDriver = \"mongodb\" | \"postgres\" | \"mysql\";\n\n/**\n * Default model configuration options.\n *\n * These settings will be applied to all models using this data source,\n * unless overridden by individual model static properties.\n *\n * This is a re-export of Partial<ModelDefaults> for backward compatibility\n * and to provide clearer naming in the connection config context.\n *\n * The full hierarchy is:\n * 1. Model static property (highest priority)\n * 2. Database config modelDefaults (this type)\n * 3. Driver defaults (e.g., snake_case for PostgreSQL, camelCase for MongoDB)\n * 4. Framework defaults (fallback values)\n *\n * @see ModelDefaults for complete type definition and documentation\n */\nexport type ModelDefaultConfig = Partial<ModelDefaults>;\n\n/**\n * Connection options for establishing a database connection.\n *\n * Generic type that separates concerns:\n * - Shared config (driver, name, database, connection details)\n * - Driver options (cascade-next driver-specific settings)\n * - Client options (native database client settings)\n * - Model options (default model behaviors)\n *\n * @template TDriverOptions - Driver-specific options (e.g., MongoDriverOptions)\n * @template TClientOptions - Native client options (e.g., MongoClientOptions from mongodb package)\n *\n * @example\n * ```typescript\n * // MongoDB\n * import type { MongoClientOptions } from \"mongodb\";\n * import type { MongoDriverOptions } from \"@warlock.js/cascade\";\n *\n * const config: ConnectionOptions<MongoDriverOptions, MongoClientOptions> = {\n *   driver: \"mongodb\",\n *   database: \"myapp\",\n *   host: \"localhost\",\n *   port: 27017,\n *   driverOptions: {\n *     autoGenerateId: true,\n *     counterCollection: \"counters\",\n *   },\n *   clientOptions: {\n *     minPoolSize: 5,\n *     maxPoolSize: 10,\n *   },\n *   modelOptions: {\n *     randomIncrement: true,\n *     initialId: 1000,\n *   },\n * };\n * ```\n */\nexport type ConnectionOptions<TDriverOptions = any, TClientOptions = any> = {\n  // ============================================================================\n  // SHARED CONFIGURATION (Framework-level)\n  // ============================================================================\n\n  /**\n   * Database driver to use.\n   * @default \"mongodb\"\n   */\n  driver?: DatabaseDriver;\n\n  /**\n   * Unique name for this data source.\n   * Used for registration in DataSourceRegistry.\n   * @default \"default\"\n   */\n  name?: string;\n\n  /**\n   * Whether this should be the default data source.\n   * @default true\n   */\n  isDefault?: boolean;\n\n  /**\n   * Database name (required).\n   */\n  database: string;\n\n  /**\n   * Enable database operation logging (queries, execution time, parameters).\n   * Highly recommended to keep this disabled in production to prevent sensitive data leakage.\n   *\n   * @default false\n   */\n  logging?: boolean;\n\n  // ============================================================================\n  // CONNECTION DETAILS (Shared across drivers)\n  // ============================================================================\n\n  /**\n   * Database connection URI.\n   * Alternative to specifying host/port separately.\n   *\n   * @example \"mongodb://localhost:27017/mydb\"\n   * @example \"postgresql://user:pass@localhost:5432/mydb\"\n   */\n  uri?: string;\n\n  /**\n   * Database host.\n   * @default \"localhost\"\n   */\n  host?: string;\n\n  /**\n   * Database port.\n   * @default 27017 (MongoDB), 5432 (PostgreSQL)\n   */\n  port?: number;\n\n  /**\n   * Database username for authentication.\n   */\n  username?: string;\n\n  /**\n   * Database password for authentication.\n   */\n  password?: string;\n\n  /**\n   * Authentication source database.\n   * Typically \"admin\" for MongoDB.\n   */\n  authSource?: string;\n\n  // ============================================================================\n  // DRIVER OPTIONS (Package-level, driver-specific)\n  // ============================================================================\n\n  /**\n   * Driver-specific options.\n   *\n   * For MongoDB: { autoGenerateId, counterCollection, transactionOptions }\n   * For PostgreSQL: { schema, ... }\n   */\n  driverOptions?: TDriverOptions;\n\n  // ============================================================================\n  // CLIENT OPTIONS (Native database client library)\n  // ============================================================================\n\n  /**\n   * Native database client options.\n   *\n   * For MongoDB: MongoClientOptions from 'mongodb' package\n   * For PostgreSQL: PoolConfig from 'pg' package\n   */\n  clientOptions?: TClientOptions;\n\n  // ============================================================================\n  // MODEL OPTIONS (Model defaults)\n  // ============================================================================\n\n  /**\n   * Default model configuration for all models using this data source.\n   *\n   * These settings override driver defaults but are overridden by\n   * individual model static properties.\n   *\n   * **Configuration Hierarchy (highest to lowest):**\n   * 1. Model static property - `User.createdAtColumn = \"creation_date\"`\n   * 2. **modelOptions (this)** - Database-wide overrides\n   * 3. Driver defaults - PostgreSQL: snake_case, MongoDB: camelCase\n   * 4. Framework defaults - Fallback values\n   *\n   * @example\n   * ```typescript\n   * // PostgreSQL database with custom settings\n   * {\n   *   driver: \"postgres\",\n   *   modelOptions: {\n   *     // Override PostgreSQL default (snake_case) to use camelCase\n   *     namingConvention: \"camelCase\",\n   *     createdAtColumn: \"createdAt\",\n   *     updatedAtColumn: \"updatedAt\",\n   *\n   *     // ID generation settings (for MongoDB)\n   *     randomIncrement: true,\n   *     initialId: 1000,\n   *\n   *     // Deletion settings\n   *     deleteStrategy: \"soft\",\n   *     trashTable: \"archive\", // All models use same trash table\n   *   }\n   * }\n   *\n   * // MongoDB database with defaults\n   * {\n   *   driver: \"mongodb\",\n   *   modelOptions: {\n   *     // MongoDB already uses camelCase by default\n   *     randomIncrement: true,\n   *     initialId: 10000,\n   *     deleteStrategy: \"trash\", // Use RecycleBin\n   *   }\n   * }\n   * ```\n   */\n  modelOptions?: ModelDefaultConfig;\n\n  /**\n   * Migration-level defaults (UUID strategy, etc.).\n   *\n   * These defaults override driver migration defaults but can be\n   * overridden by individual migration calls.\n   *\n   * @default undefined (uses driver defaults)\n   *\n   * @example\n   * ```typescript\n   * migrationDefaults: {\n   *   uuidStrategy: \"v7\", // Use UUID v7 for all migrations\n   * }\n   * ```\n   */\n  migrationOptions?: MigrationDefaults;\n\n  /**\n   * Defaults for relation conventions — foreign-key suffix and pivot-table\n   * naming order. Controls how `@BelongsTo` / `@HasOne` / `@HasMany` /\n   * `@BelongsToMany` infer column / table names when none are explicitly\n   * configured on the decorator.\n   *\n   * @default undefined (uses framework defaults: `\"_id\"` suffix + alphabetical pivot)\n   *\n   * @example\n   * ```typescript\n   * relationOptions: {\n   *   foreignKeySuffix: \"_id\",\n   *   pivotTableNamingOrder: \"alphabetical\",\n   * }\n   * ```\n   */\n  relationOptions?: RelationDefaults;\n\n  // ============================================================================\n  // DATA SOURCE DEFAULTS\n  // ============================================================================\n\n  /**\n   * Default delete strategy for models using this data source.\n   *\n   * - MongoDB: Typically `\"trash\"` (uses RecycleBin collection)\n   * - PostgreSQL: Typically `\"permanent\"` or `\"soft\"`\n   *\n   * Can be overridden by model static property or destroy() options.\n   *\n   * @default undefined (falls back to \"permanent\")\n   */\n  defaultDeleteStrategy?: DeleteStrategy;\n\n  /**\n   * Default trash table/collection name for \"trash\" delete strategy.\n   *\n   * - MongoDB: Typically `\"RecycleBin\"`\n   * - If not set, defaults to `{table}Trash` pattern\n   *\n   * Can be overridden by Model.trashTable static property.\n   *\n   * @default undefined (uses {table}Trash pattern)\n   */\n  defaultTrashTable?: string;\n\n  // ============================================================================\n  // MIGRATION OPTIONS\n  // ============================================================================\n\n  /**\n   * Migration configuration options.\n   */\n  migrations?: {\n    /**\n     * Whether to wrap migrations in database transactions.\n     *\n     * Overrides driver defaults:\n     * - PostgreSQL default: `true` (DDL is transactional)\n     * - MongoDB default: `false` (DDL cannot be transactional)\n     *\n     * Individual migrations can override this with their own `transactional` property.\n     *\n     * @default undefined (uses driver default)\n     */\n    transactional?: boolean;\n\n    /**\n     * Name of the migrations tracking table/collection.\n     *\n     * @default \"_migrations\"\n     */\n    table?: string;\n  };\n};\n\n/**\n * Connect to a database and register the data source.\n *\n * This is a high-level utility function that simplifies database connection\n * for small to medium projects. It handles driver instantiation, connection,\n * data source creation, and automatic registration.\n *\n * **Supported Drivers:**\n * - `mongodb` (default) - MongoDB driver with optional auto ID generation\n * - `postgres` - PostgreSQL driver (not yet implemented)\n * - `mysql` - MySQL driver (not yet implemented)\n *\n * **Features:**\n * - Automatic driver instantiation based on driver name\n * - Connection establishment and error handling\n * - DataSource creation and registration\n * - Support for MongoDB-specific features (ID generation, transactions)\n *\n * @param options - Connection configuration options\n * @returns A connected and registered DataSource instance\n * @throws {Error} If connection fails or driver is not implemented\n *\n * @example\n * ```typescript\n * // MongoDB with new structure\n * const dataSource = await connectToDatabase({\n *   driver: \"mongodb\",\n *   database: \"myapp\",\n *   host: \"localhost\",\n *   port: 27017,\n *   driverOptions: {\n *     autoGenerateId: true,\n *   },\n *   clientOptions: {\n *     minPoolSize: 5,\n *     maxPoolSize: 10,\n *   },\n *   modelOptions: {\n *     randomIncrement: true,\n *     initialId: 1000,\n *   },\n * });\n * ```\n */\nexport async function connectToDatabase<TDriverOptions = any, TClientOptions = any>(\n  options: ConnectionOptions<TDriverOptions, TClientOptions>,\n): Promise<DataSource> {\n  // Default values\n  const driverType = options.driver ?? \"mongodb\";\n  const dataSourceName = options.name ?? \"default\";\n  const isDefault = options.isDefault ?? true;\n\n  // Create driver based on type\n  let driver: DriverContract;\n\n  switch (driverType) {\n    case \"mongodb\": {\n      driver = new MongoDbDriver(\n        {\n          database: options.database,\n          uri: options.uri,\n          host: options.host,\n          port: options.port,\n          username: options.username,\n          password: options.password,\n          authSource: options.authSource,\n          logging: options.logging,\n          clientOptions: options.clientOptions as any,\n        },\n        options.driverOptions as any,\n      );\n      break;\n    }\n\n    case \"postgres\": {\n      driver = new PostgresDriver({\n        database: options.database,\n        connectionString: options.uri,\n        host: options.host,\n        port: options.port ?? 5432,\n        user: options.username,\n        password: options.password,\n        logging: options.logging,\n        // Spread any additional client options (pool settings, SSL, etc.)\n        ...(options.clientOptions as object),\n      });\n      break;\n    }\n\n    case \"mysql\":\n      throw new Error(\"MySQL driver is not yet implemented. Coming soon!\");\n\n    default:\n      throw new Error(\n        `Unknown driver: \"${driverType}\". Supported drivers: mongodb, postgres, mysql`,\n      );\n  }\n\n  // Create data source\n  const dataSource = new DataSource({\n    name: dataSourceName,\n    driver,\n    isDefault,\n    defaultDeleteStrategy: options.defaultDeleteStrategy,\n    defaultTrashTable: options.defaultTrashTable,\n    modelDefaults: options.modelOptions,\n    migrationDefaults: options.migrationOptions,\n    relationDefaults: options.relationOptions,\n    migrations: options.migrations,\n  });\n\n  // Register data source\n  dataSourceRegistry.register(dataSource);\n\n  // Connect to the database\n  try {\n    await driver.connect();\n  } catch (error) {\n    console.log(error);\n\n    throw new Error(\n      `Failed to connect to ${driverType} database: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n\n  return dataSource;\n}\n\n/**\n * Get current driver instance.\n *\n * @example\n * ```typescript\n * const driver = getDatabaseDriver();\n *\n * // Pass type to return Postgres driver type\n * const pgDriver = getDatabaseDriver<PostgresDriver>();\n * ```\n */\nexport function getDatabaseDriver<T extends DriverContract = any>(): T {\n  const driver = dataSourceRegistry.get().driver;\n\n  return driver as unknown as T;\n}\n\n/**\n * Perform database transaction(s)\n * Shorthand to `dataSourceRegister.get().driver.transaction\n */\nexport async function transaction<T = any>(\n  fn: (ctx: TransactionContext) => Promise<T>,\n  options?: Record<string, unknown>,\n): Promise<T> {\n  return getDatabaseDriver().transaction(fn, options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuWA,eAAsB,kBACpB,SACqB;CAErB,MAAM,aAAa,QAAQ,UAAU;CACrC,MAAM,iBAAiB,QAAQ,QAAQ;CACvC,MAAM,YAAY,QAAQ,aAAa;CAGvC,IAAI;CAEJ,QAAQ,YAAR;EACE,KAAK;GACH,SAAS,IAAI,cACX;IACE,UAAU,QAAQ;IAClB,KAAK,QAAQ;IACb,MAAM,QAAQ;IACd,MAAM,QAAQ;IACd,UAAU,QAAQ;IAClB,UAAU,QAAQ;IAClB,YAAY,QAAQ;IACpB,SAAS,QAAQ;IACjB,eAAe,QAAQ;GACzB,GACA,QAAQ,aACV;GACA;EAGF,KAAK;GACH,SAAS,IAAI,eAAe;IAC1B,UAAU,QAAQ;IAClB,kBAAkB,QAAQ;IAC1B,MAAM,QAAQ;IACd,MAAM,QAAQ,QAAQ;IACtB,MAAM,QAAQ;IACd,UAAU,QAAQ;IAClB,SAAS,QAAQ;IAEjB,GAAI,QAAQ;GACd,CAAC;GACD;EAGF,KAAK,SACH,MAAM,IAAI,MAAM,mDAAmD;EAErE,SACE,MAAM,IAAI,MACR,oBAAoB,WAAW,+CACjC;CACJ;CAGA,MAAM,aAAa,IAAI,WAAW;EAChC,MAAM;EACN;EACA;EACA,uBAAuB,QAAQ;EAC/B,mBAAmB,QAAQ;EAC3B,eAAe,QAAQ;EACvB,mBAAmB,QAAQ;EAC3B,kBAAkB,QAAQ;EAC1B,YAAY,QAAQ;CACtB,CAAC;CAGD,mBAAmB,SAAS,UAAU;CAGtC,IAAI;EACF,MAAM,OAAO,QAAQ;CACvB,SAAS,OAAO;EACd,QAAQ,IAAI,KAAK;EAEjB,MAAM,IAAI,MACR,wBAAwB,WAAW,aAAa,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACvG;CACF;CAEA,OAAO;AACT;;;;;;;;;;;;AAaA,SAAgB,oBAAuD;CAGrE,OAFe,mBAAmB,IAAI,EAAE;AAG1C;;;;;AAMA,eAAsB,YACpB,IACA,SACY;CACZ,OAAO,kBAAkB,EAAE,YAAY,IAAI,OAAO;AACpD"}

package/esm/utils/database-writer.utils.d.mts

@@ -0,0 +1,18 @@
+import { Model } from "../model/model.mjs";
+
+//#region ../../@warlock.js/cascade/src/utils/database-writer.utils.d.ts
+type transformCallbackOptions = {
+  model: Model;
+  column: string;
+  value: any;
+  isChanged: boolean;
+  isNew: boolean;
+};
+type ModelTransformCallback = (options: transformCallbackOptions) => string;
+/**
+ * Transfer value before saving it into the database
+ */
+declare function useModelTransformer(callback: ModelTransformCallback): TransformerCallback;
+//#endregion
+export { ModelTransformCallback, useModelTransformer };
+//# sourceMappingURL=database-writer.utils.d.mts.map

package/esm/utils/database-writer.utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-writer.utils.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/database-writer.utils.ts"],"mappings":";;;KAGK,wBAAA;EACH,KAAA,EAAO,KAAK;EACZ,MAAA;EACA,KAAA;EACA,SAAA;EACA,KAAA;AAAA;AAAA,KAGU,sBAAA,IAA0B,OAAiC,EAAxB,wBAAwB;;;;iBAKvD,mBAAA,CAAoB,QAAA,EAAU,sBAAA,GAAsB,mBAAA"}

package/esm/utils/database-writer.utils.mjs

@@ -0,0 +1,25 @@
+//#region ../../@warlock.js/cascade/src/utils/database-writer.utils.ts
+/**
+* Transfer value before saving it into the database
+*/
+function useModelTransformer(callback) {
+	const transformCallback = (data, { context }) => {
+		const model = context.rootContext?.model;
+		const column = context.key;
+		const value = data;
+		const isChanged = model.isDirty(column);
+		const isNew = model.isNew;
+		return callback({
+			model,
+			column,
+			value,
+			isChanged,
+			isNew
+		});
+	};
+	return transformCallback;
+}
+
+//#endregion
+export { useModelTransformer };
+//# sourceMappingURL=database-writer.utils.mjs.map

package/esm/utils/database-writer.utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-writer.utils.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/utils/database-writer.utils.ts"],"sourcesContent":["import { type TransformerCallback } from \"@warlock.js/seal\";\nimport { type Model } from \"../model/model\";\n\ntype transformCallbackOptions = {\n  model: Model;\n  column: string;\n  value: any;\n  isChanged: boolean;\n  isNew: boolean;\n};\n\nexport type ModelTransformCallback = (options: transformCallbackOptions) => string;\n\n/**\n * Transfer value before saving it into the database\n */\nexport function useModelTransformer(callback: ModelTransformCallback) {\n  const transformCallback: TransformerCallback = (data, { context }) => {\n    const model = context.rootContext?.model as Model;\n    const column = context.key;\n    const value = data;\n    const isChanged = model.isDirty(column);\n    const isNew = model.isNew;\n    return callback({ model, column, value, isChanged, isNew });\n  };\n\n  return transformCallback;\n}\n"],"mappings":";;;;AAgBA,SAAgB,oBAAoB,UAAkC;CACpE,MAAM,qBAA0C,MAAM,EAAE,cAAc;EACpE,MAAM,QAAQ,QAAQ,aAAa;EACnC,MAAM,SAAS,QAAQ;EACvB,MAAM,QAAQ;EACd,MAAM,YAAY,MAAM,QAAQ,MAAM;EACtC,MAAM,QAAQ,MAAM;EACpB,OAAO,SAAS;GAAE;GAAO;GAAQ;GAAO;GAAW;EAAM,CAAC;CAC5D;CAEA,OAAO;AACT"}