@warlock.js/cascade 4.0.162 → 4.0.164

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

@@ -0,0 +1,130 @@
+import {DataSource}from'../data-source/data-source.js';import {dataSourceRegistry}from'../data-source/data-source-registry.js';import {MongoDbDriver}from'../drivers/mongodb/mongodb-driver.js';import {PostgresDriver}from'../drivers/postgres/postgres-driver.js';import'../context/database-transaction-context.js';/**
+ * 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) {
+    // Default values
+    const driverType = options.driver ?? "mongodb";
+    const dataSourceName = options.name ?? "default";
+    const isDefault = options.isDefault ?? true;
+    // Create driver based on type
+    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,
+                // Spread any additional client options (pool settings, SSL, etc.)
+                ...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`);
+    }
+    // Create data source
+    const dataSource = new DataSource({
+        name: dataSourceName,
+        driver,
+        isDefault,
+        defaultDeleteStrategy: options.defaultDeleteStrategy,
+        defaultTrashTable: options.defaultTrashTable,
+        modelDefaults: options.modelOptions,
+        migrationDefaults: options.migrationOptions,
+        migrations: options.migrations,
+    });
+    // Register data source
+    dataSourceRegistry.register(dataSource);
+    // Connect to the database
+    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() {
+    const driver = dataSourceRegistry.get().driver;
+    return driver;
+}
+/**
+ * Perform database transaction(s)
+ * Shorthand to `dataSourceRegister.get().driver.transaction
+ */
+async function transaction(fn, options) {
+    return getDatabaseDriver().transaction(fn, options);
+}export{connectToDatabase,getDatabaseDriver,transaction};//# sourceMappingURL=connect-to-database.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-database.js","sources":["../../src/utils/connect-to-database.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-writer.utils.d.ts","sourceRoot":"","sources":["../../src/utils/database-writer.utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,GAAG,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,MAAM,CAAC;AAEnF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,sBAAsB,uBAWnE"}

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

@@ -0,0 +1,14 @@
+/**
+ * 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;
+}export{useModelTransformer};//# sourceMappingURL=database-writer.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-writer.utils.js","sources":["../../src/utils/database-writer.utils.ts"],"sourcesContent":[null],"names":[],"mappings":"AAaA;;AAEG;AACG,SAAU,mBAAmB,CAAC,QAAgC,EAAA;IAClE,MAAM,iBAAiB,GAAwB,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAI;AACnE,QAAA,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,KAAc,CAAC;AAClD,QAAA,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC;QACnB,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACxC,QAAA,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;AAC1B,QAAA,OAAO,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9D,KAAC,CAAC;AAEF,IAAA,OAAO,iBAAiB,CAAC;AAC3B"}

package/esm/utils/define-model.js

@@ -0,0 +1,100 @@
+import {Model}from'../model/model.js';import {registerModelInRegistry}from'../model/register-model.js';/**
+ * Define a model with a clean, concise API.
+ *
+ * This utility function creates a Model class with the specified configuration,
+ * reducing boilerplate and providing a more declarative way to define models.
+ *
+ * @param options - Model configuration options
+ * @returns A Model class with the specified configuration
+ *
+ * @example
+ * ```typescript
+ * import { defineModel } from "@warlock.js/cascade";
+ * import { v } from "@warlock.js/seal";
+ *
+ * export const User = defineModel({
+ *   table: "users",
+ *   schema: v.object({
+ *     name: v.string().required().trim(),
+ *     email: v.string().email().required().lowercase(),
+ *     password: v.string().required().min(6),
+ *     role: v.string().default("user"),
+ *   }),
+ *   deleteStrategy: "soft",
+ * });
+ *
+ * // Usage
+ * const user = await User.create({
+ *   name: "John Doe",
+ *   email: "john@example.com",
+ *   password: "secret123",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With type inference
+ * export const Post = defineModel({
+ *   table: "posts",
+ *   schema: v.object({
+ *     title: v.string().required(),
+ *     content: v.string().required(),
+ *     authorId: v.number().required(),
+ *     published: v.boolean().default(false),
+ *   }),
+ * });
+ *
+ * // TypeScript knows the exact type!
+ * const post = await Post.create({
+ *   title: "Hello World",
+ *   content: "My first post",
+ *   authorId: 1,
+ * });
+ *
+ * console.log(post.title); // ✅ Type-safe!
+ * ```
+ */
+function defineModel(options) {
+    class DefinedModel extends Model {
+        /**
+         * Table/collection name
+         */
+        static table = options.table;
+        /**
+         * Validation schema
+         */
+        static schema = options.schema;
+        /**
+         * Delete strategy
+         */
+        static deleteStrategy = options.deleteStrategy || "trash";
+        /**
+         * Strict mode
+         */
+        static strictMode = options.strictMode || "strip";
+        /**
+         * Auto-generate ID
+         */
+        static autoGenerateId = options.autoGenerateId || false;
+        /**
+         * Random increment
+         */
+        static randomIncrement = options.randomIncrement || false;
+        /**
+         * Initial ID
+         */
+        static initialId = options.initialId || 1;
+    }
+    // Apply custom instance properties (getters/setters/methods)
+    if (options.properties) {
+        Object.defineProperties(DefinedModel.prototype, Object.getOwnPropertyDescriptors(options.properties));
+    }
+    if (options.name) {
+        registerModelInRegistry(options.name, DefinedModel);
+    }
+    // Apply custom static methods
+    if (options.statics) {
+        Object.defineProperties(DefinedModel, Object.getOwnPropertyDescriptors(options.statics));
+    }
+    return DefinedModel;
+}export{defineModel};//# sourceMappingURL=define-model.js.map

package/esm/utils/define-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-model.js","sources":["../../src/utils/define-model.ts"],"sourcesContent":[null],"names":[],"mappings":"uGAuGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDG;AACG,SAAU,WAAW,CAMzB,OAIC,EAAA;IAID,MAAM,YAAa,SAAQ,KAAqB,CAAA;AAC9C;;AAEG;AACI,QAAA,OAAO,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;AAEpC;;AAEG;AACI,QAAA,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AAEtC;;AAEG;QACI,OAAO,cAAc,GAAmB,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC;AAEjF;;AAEG;QACI,OAAO,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC;AAEzD;;AAEG;QACI,OAAO,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;AAE/D;;AAEG;QACI,OAAO,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;AAEjE;;AAEG;QACI,OAAO,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;;;IAInD,IAAI,OAAO,CAAC,UAAU,EAAE;AACtB,QAAA,MAAM,CAAC,gBAAgB,CACrB,YAAY,CAAC,SAAS,EACtB,MAAM,CAAC,yBAAyB,CAAC,OAAO,CAAC,UAAU,CAAC,CACrD,CAAC;AACH,KAAA;IAED,IAAI,OAAO,CAAC,IAAI,EAAE;AAChB,QAAA,uBAAuB,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACrD,KAAA;;IAGD,IAAI,OAAO,CAAC,OAAO,EAAE;AACnB,QAAA,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1F,KAAA;AAQD,IAAA,OAAO,YAAqC,CAAC;AAC/C"}

package/esm/utils/is-valid-date-value.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check if the given value is a valid date value
+ */
+export declare function isValidDateValue(value: unknown): boolean;
+//# sourceMappingURL=is-valid-date-value.d.ts.map

package/esm/utils/is-valid-date-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-valid-date-value.d.ts","sourceRoot":"","sources":["../../src/utils/is-valid-date-value.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAsBxD"}

package/esm/utils/is-valid-date-value.js

@@ -0,0 +1,25 @@
+const isoRegex = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?)?$/;
+/**
+ * Check if the given value is a valid date value
+ */
+function isValidDateValue(value) {
+    // ✅ Handle timestamps
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return false;
+        const date = new Date(value);
+        return !Number.isNaN(date.getTime());
+    }
+    // ❌ Only allow strict ISO strings
+    if (typeof value !== "string")
+        return false;
+    if (!isoRegex.test(value))
+        return false;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return false;
+    // 🔥 Critical step: prevent JS auto-correction
+    // Example: "2023-02-31" → March 3 (WRONG but "valid")
+    const [y, m, d] = value.split("T")[0].split("-").map(Number);
+    return date.getUTCFullYear() === y && date.getUTCMonth() + 1 === m && date.getUTCDate() === d;
+}export{isValidDateValue};//# sourceMappingURL=is-valid-date-value.js.map

package/esm/utils/is-valid-date-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-valid-date-value.js","sources":["../../src/utils/is-valid-date-value.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,sDAAsD,CAAC;AAExE;;AAEG;AACG,SAAU,gBAAgB,CAAC,KAAc,EAAA;;AAE7C,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;AAC7B,QAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;AAAE,YAAA,OAAO,KAAK,CAAC;AAE1C,QAAA,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AACtC,KAAA;;IAGD,IAAI,OAAO,KAAK,KAAK,QAAQ;AAAE,QAAA,OAAO,KAAK,CAAC;AAE5C,IAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;AAAE,QAAA,OAAO,KAAK,CAAC;AAExC,IAAA,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;AAAE,QAAA,OAAO,KAAK,CAAC;;;IAI/C,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE7D,OAAO,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;AAChG"}

package/esm/utils/once-connected.d.ts

@@ -0,0 +1,146 @@
+import type { DataSource } from "../data-source/data-source";
+/**
+ * Execute a callback once the driver is connected.
+ *
+ * If the driver is already connected, the callback is executed immediately.
+ * Otherwise, it waits for the "connected" event.
+ *
+ * **Use Case:**
+ * Useful for ensuring database-dependent operations only run after connection
+ * is established, especially in small to medium projects with a single data source.
+ *
+ * @param dataSourceOrNameOrCallback - Data source instance, name, or callback function
+ * @param callback - Function to execute once connected (optional if first param is callback)
+ *
+ * @example
+ * ```typescript
+ * // With default data source (just callback)
+ * await connectToDatabase({ database: "myapp" });
+ *
+ * onceConnected((ds) => {
+ *   console.log("Database is ready!");
+ *   console.log("Connected to:", ds.name);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source name
+ * onceConnected("primary", (ds) => {
+ *   console.log("Primary database is ready!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source instance
+ * const dataSource = await connectToDatabase({ database: "myapp" });
+ *
+ * onceConnected(dataSource, (ds) => {
+ *   console.log("Database is ready!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With driver instance
+ * const driver = new MongoDbDriver(config);
+ * const dataSource = new DataSource({ name: "primary", driver });
+ *
+ * onceConnected(dataSource, () => {
+ *   // Start application server
+ *   app.listen(3000);
+ * });
+ *
+ * // Connect after setting up the callback
+ * await driver.connect();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Chaining operations
+ * onceConnected(async (ds) => {
+ *   // Seed database
+ *   await seedDatabase();
+ *
+ *   // Run migrations
+ *   await runMigrations();
+ *
+ *   console.log("Database ready!");
+ * });
+ * ```
+ */
+export declare function onceConnected(dataSourceOrNameOrCallback: DataSource | string | ((dataSource: DataSource) => void), callback?: (dataSource: DataSource) => void): void;
+/**
+ * Execute a callback once the driver is disconnected.
+ *
+ * If the driver is already disconnected, the callback is executed immediately.
+ * Otherwise, it waits for the "disconnected" event.
+ *
+ * **Use Case:**
+ * Useful for cleanup operations, graceful shutdown, or reconnection logic.
+ *
+ * @param dataSourceOrNameOrCallback - Data source instance, name, or callback function
+ * @param callback - Function to execute once disconnected (optional if first param is callback)
+ *
+ * @example
+ * ```typescript
+ * // With default data source (just callback)
+ * await connectToDatabase({ database: "myapp" });
+ *
+ * onceDisconnected((ds) => {
+ *   console.log("Database disconnected!");
+ *   console.log("Attempting reconnection...");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source name
+ * onceDisconnected("primary", (ds) => {
+ *   console.log("Primary database disconnected!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With data source instance
+ * const dataSource = await connectToDatabase({ database: "myapp" });
+ *
+ * onceDisconnected(dataSource, (ds) => {
+ *   console.log("Database disconnected!");
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Graceful shutdown with default data source
+ * process.on("SIGTERM", async () => {
+ *   console.log("Shutting down...");
+ *
+ *   onceDisconnected(() => {
+ *     console.log("Database closed, exiting process");
+ *     process.exit(0);
+ *   });
+ *
+ *   const dataSource = DataSourceRegistry.getDefault();
+ *   await dataSource?.driver.disconnect();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cleanup resources on disconnect
+ * onceDisconnected(async (ds) => {
+ *   // Close file handles
+ *   await closeFileHandles();
+ *
+ *   // Clear caches
+ *   clearCaches();
+ *
+ *   console.log("Cleanup complete");
+ * });
+ * ```
+ */
+export declare function onceDisconnected(dataSourceOrNameOrCallback: DataSource | string | ((dataSource: DataSource) => void), callback?: (dataSource: DataSource) => void): void;
+//# sourceMappingURL=once-connected.d.ts.map

package/esm/utils/once-connected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once-connected.d.ts","sourceRoot":"","sources":["../../src/utils/once-connected.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,aAAa,CAC3B,0BAA0B,EAAE,UAAU,GAAG,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC,EACpF,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,GAC1C,IAAI,CAyDN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,gBAAgB,CAC9B,0BAA0B,EAAE,UAAU,GAAG,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC,EACpF,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,GAC1C,IAAI,CAyDN"}