@warlock.js/cascade 4.0.157 → 4.0.158

package/cjs/model/model.js

@@ -1,1657 +0,0 @@
-'use strict';var modelEvents=require('../events/model-events.js'),relationLoader=require('../relations/relation-loader.js'),modelSync=require('../sync/model-sync.js'),accessorMethods=require('./methods/accessor-methods.js'),deleteMethods=require('./methods/delete-methods.js'),dirtyMethods=require('./methods/dirty-methods.js'),hydrationMethods=require('./methods/hydration-methods.js'),instanceEventMethods=require('./methods/instance-event-methods.js'),metaMethods=require('./methods/meta-methods.js'),queryMethods=require('./methods/query-methods.js'),restoreMethods=require('./methods/restore-methods.js'),scopeMethods=require('./methods/scope-methods.js'),serializationMethods=require('./methods/serialization-methods.js'),staticEventMethods=require('./methods/static-event-methods.js'),writeMethods=require('./methods/write-methods.js'),registerModel=require('./register-model.js');/**
- * Base class that powers all Cascade models.
- *
- * Provides:
- * - Type-safe value accessors with dot-notation support (get, set, has, unset, merge)
- * - Automatic dirty tracking for efficient partial updates
- * - Lifecycle event hooks (saving, created, deleting, etc.)
- * - Integration with the data-source registry for multi-database support
- * - Support for both per-model and global event listeners
- *
- * @template TSchema - The shape of the model's underlying data
- *
- * @example
- * ```typescript
- * interface UserSchema {
- *   id: number;
- *   name: string;
- *   email: string;
- * }
- *
- * class User extends Model<UserSchema> {
- *   public static table = "users";
- * }
- *
- * const user = new User({ name: "Alice" });
- * user.set("email", "alice@example.com");
- * console.log(user.hasChanges()); // true
- * ```
- */
-class Model {
-    /**
-     * The database table or collection name associated with this model.
-     *
-     * Must be defined by each concrete model subclass.
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static table = "users";
-     * }
-     * ```
-     */
-    static table;
-    /**
-     * Resource for this model.
-     * It is a class that holds a toJSON function
-     * Called when the model is being converted to JSON (by calling toJSON or JSON.stringify(model))
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static resource = UserResource;
-     * }
-     * ```
-     */
-    static resource;
-    /**
-     * Resource columns
-     * Define what columns should be sent to the resource (if any) when converting to JSON
-     */
-    static resourceColumns;
-    /**
-     * JSON keys for this model.
-     * This could be used if resource is not passed
-     * It will select only these keys from the model
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static toJsonColumns = ["id", "name"];
-     * }
-     * ```
-     */
-    static toJsonColumns;
-    /**
-     * Data source reference for this model.
-     *
-     * Can be:
-     * - A string name registered in the data-source registry
-     * - A DataSource instance
-     * - Undefined (falls back to the default data source)
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static dataSource = "primary";
-     * }
-     * ```
-     */
-    static dataSource;
-    /**
-     * Query builder class
-     */
-    static builder;
-    /**
-     * Primary key field name used to identify records.
-     *
-     * @default "id"
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static primaryKey = "_id"; // MongoDB
-     * }
-     *
-     * class Product extends Model {
-     *   public static primaryKey = "id"; // SQL
-     * }
-     * ```
-     */
-    static primaryKey = "id";
-    /**
-     * Embeded fields when document is Being embeded
-     */
-    static embed;
-    /**
-     * Validation and casting schema using @warlock.js/seal.
-     *
-     * Defines validation rules and data transformations for the model.
-     * Used automatically during save operations.
-     *
-     * @example
-     * ```typescript
-     * import { v } from "@warlock.js/seal";
-     *
-     * class User extends Model {
-     *   public static schema = v.object({
-     *     name: v.string().required().trim(),
-     *     age: v.number().min(0).max(120),
-     *     email: v.string().email().required().toLowerCase(),
-     *     createdAt: v.date().default(() => new Date()),
-     *   });
-     * }
-     * ```
-     */
-    static schema;
-    /**
-     * Strict mode behavior for unknown fields.
-     *
-     * - `"strip"`: Remove unknown fields silently (default, recommended for APIs)
-     * - `"fail"`: Throw validation error on unknown fields (strict validation)
-     * - `"allow"`: Allow unknown fields to pass through (permissive)
-     *
-     * @default "strip"
-     *
-     * @example
-     * ```typescript
-     * import { Model, type StrictMode } from "@warlock.js/cascade";
-     *
-     * class User extends Model {
-     *   public static strictMode: StrictMode = "fail"; // Throw on unknown fields
-     * }
-     *
-     * const user = new User({ name: "Alice", unknownField: "value" });
-     * await user.save(); // DatabaseWriterValidationError: unknown field
-     * ```
-     */
-    static strictMode = "strip";
-    /**
-     * Auto-generate incremental `id` field on insert (NoSQL only).
-     *
-     * When enabled, the ID generator creates a sequential integer ID
-     * separate from the database's native ID (_id for MongoDB).
-     *
-     * **Note:** SQL databases use native AUTO_INCREMENT and don't need this.
-     *
-     * @default true
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static autoGenerateId = true;
-     * }
-     *
-     * const user = new User({ name: "Alice" });
-     * await user.save();
-     * console.log(user.get("_id")); // ObjectId("...") - MongoDB
-     * console.log(user.get("id")); // 1 - Generated
-     * ```
-     */
-    static autoGenerateId = true;
-    /**
-     * Initial ID value for the first record.
-     *
-     * If not set, defaults to 1 or uses `randomInitialId`.
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static initialId = 1000; // Start from 1000
-     * }
-     * ```
-     */
-    static initialId;
-    /**
-     * Randomly generate the initial ID.
-     *
-     * Can be:
-     * - `true`: Generate random ID between 10000-499999
-     * - Function: Custom random ID generator
-     * - `false`: Use `initialId` or default to 1
-     *
-     * @default false
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static randomInitialId = true; // Random 10000-499999
-     * }
-     *
-     * class Product extends Model {
-     *   public static randomInitialId = () => Math.floor(Math.random() * 1000000);
-     * }
-     * ```
-     */
-    static randomInitialId;
-    /**
-     * Amount to increment ID by for each new record.
-     *
-     * If not set, defaults to 1 or uses `randomIncrement`.
-     *
-     * @default 1
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static incrementIdBy = 5; // Increment by 5
-     * }
-     * ```
-     */
-    static incrementIdBy = 1;
-    /**
-     * Randomly generate the increment amount.
-     *
-     * Can be:
-     * - `true`: Generate random increment between 1-10
-     * - Function: Custom random increment generator
-     * - `false`: Use `incrementIdBy` or default to 1
-     *
-     * @default false
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static randomIncrement = true; // Random 1-10
-     * }
-     *
-     * class Product extends Model {
-     *   public static randomIncrement = () => Math.floor(Math.random() * 100);
-     * }
-     * ```
-     */
-    static randomIncrement;
-    /**
-     * Created at column name.
-     */
-    static createdAtColumn;
-    /**
-     * Updated at column name.
-     */
-    static updatedAtColumn;
-    /**
-     * Delete strategy for this model.
-     *
-     * Controls how models are deleted:
-     * - `"trash"` - Moves to trash collection, then deletes
-     * - `"permanent"` - Direct deletion (hard delete)
-     * - `"soft"` - Sets deletedAt timestamp (soft delete)
-     *
-     * Can be overridden by destroy() options.
-     * Falls back to data source default if not set.
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static deleteStrategy: DeleteStrategy = "soft";
-     * }
-     * ```
-     */
-    static deleteStrategy;
-    /**
-     * Column name for soft delete timestamp.
-     *
-     * Used when delete strategy is "soft".
-     *
-     * @default "deletedAt"
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static deletedAtColumn = "archivedAt";
-     * }
-     * ```
-     */
-    static deletedAtColumn = "deletedAt";
-    /**
-     * Trash table/collection name override.
-     *
-     * If not set, defaults to `{table}Trash` or data source default.
-     * Used when delete strategy is "trash".
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static trashTable = "userRecycleBin";
-     * }
-     * ```
-     */
-    static trashTable;
-    /**
-     * Global scopes that are automatically applied to all queries.
-     * These scopes are inherited by child models.
-     */
-    static globalScopes = new Map();
-    /**
-     * Local scopes that can be manually applied to queries.
-     * These are reusable query snippets that developers opt into.
-     */
-    static localScopes = new Map();
-    /**
-     * Relation definitions for this model.
-     *
-     * Define relationships to other models using helper functions:
-     * - `hasMany()` - One-to-many (User has many Posts)
-     * - `hasOne()` - One-to-one (User has one Profile)
-     * - `belongsTo()` - Inverse of hasMany/hasOne (Post belongs to User)
-     * - `belongsToMany()` - Many-to-many with pivot table (User has many Roles)
-     *
-     * @example
-     * ```typescript
-     * import { hasMany, belongsTo, belongsToMany, hasOne } from "@warlock.js/cascade";
-     *
-     * class User extends Model {
-     *   public posts?: Post[];  // Optional: for TypeScript autocomplete
-     *
-     *   static relations = {
-     *     posts: hasMany("Post"),
-     *     profile: hasOne("Profile"),
-     *     organization: belongsTo("Organization"),
-     *     roles: belongsToMany("Role", { pivot: "user_roles" }),
-     *   };
-     * }
-     *
-     * // Usage:
-     * const users = await User.query().with("posts").get();
-     * console.log(users[0].posts); // Post[]
-     * ```
-     */
-    static relations = {};
-    /**
-     * Flag indicating whether this model instance represents a new (unsaved) record.
-     *
-     * - `true`: The model has not been persisted to the database yet
-     * - `false`: The model represents an existing database record
-     *
-     * This flag is used by the writer to determine whether to perform an insert or update.
-     */
-    isNew = true;
-    /**
-     * The raw mutable data backing this model instance.
-     *
-     * All field accessors (get, set, merge, etc.) operate on this object.
-     */
-    data;
-    /**
-     * Dirty tracker that monitors changes to the model's data.
-     *
-     * Tracks:
-     * - Which fields have been modified (dirty columns)
-     * - Which fields have been removed
-     * - Original vs. current values for each dirty field
-     *
-     * Used by the writer to generate efficient partial update payloads.
-     */
-    dirtyTracker;
-    /**
-     * Model instance events.
-     * Allows registering listeners for lifecycle events on this specific instance.
-     */
-    events = new modelEvents.ModelEvents();
-    /**
-     * Map of loaded relations for this model instance.
-     *
-     * Populated automatically when using `with()` for eager loading,
-     * or when calling `load()` for lazy loading.
-     *
-     * @example
-     * ```typescript
-     * const user = await User.query().with("posts").first();
-     * console.log(user.loadedRelations.get("posts")); // Post[]
-     *
-     * // Also accessible as direct properties:
-     * console.log(user.posts); // Post[]\n   * ```
-     */
-    loadedRelations = new Map();
-    /**
-     * Column name for active status.
-     */
-    isActiveColumn = "isActive";
-    /**
-     * Constructs a new model instance with optional initial data.
-     *
-     * Initializes the dirty tracker with a snapshot of the provided data.
-     *
-     * @param initialData - Partial data to populate the model
-     *
-     * @example
-     * ```typescript
-     * const user = new User({ name: "Alice", email: "alice@example.com" });
-     * ```
-     */
-    constructor(initialData = {}) {
-        this.data = initialData;
-        this.dirtyTracker = this.self().getDriver().getDirtyTracker(this.data);
-    }
-    /**
-     * Lazily load one or more relations for this model instance.
-     *
-     * This method loads relations on-demand after the model has been fetched.
-     * The loaded relations are attached directly to the model instance and
-     * also stored in `loadedRelations` map.
-     *
-     * @param relations - Relation name(s) to load
-     * @returns This model instance for chaining
-     *
-     * @example
-     * ```typescript
-     * const user = await User.first();
-     *
-     * // Load single relation
-     * await user.load("posts");
-     * console.log(user.posts); // Post[]
-     *
-     * // Load multiple relations
-     * await user.load("posts", "organization");
-     *
-     * // Chain with other operations
-     * const posts = await user.load("posts").then(() => user.posts);
-     * ```
-     */
-    async load(...relations) {
-        const ModelClass = this.constructor;
-        const loader = new relationLoader.RelationLoader([this], ModelClass);
-        await loader.load(relations);
-        return this;
-    }
-    /**
-     * Check if a relation has been loaded.
-     *
-     * @param relationName - Name of the relation to check
-     * @returns True if the relation has been loaded
-     *
-     * @example
-     * ```typescript
-     * const user = await User.first();
-     *
-     * console.log(user.isLoaded("posts")); // false
-     * await user.load("posts");
-     * console.log(user.isLoaded("posts")); // true
-     * ```
-     */
-    isLoaded(relationName) {
-        return this.loadedRelations.has(relationName);
-    }
-    /**
-     * Get a loaded relation by name.
-     *
-     * Returns undefined if the relation has not been loaded.
-     *
-     * @param relationName - Name of the relation to get
-     * @returns The loaded relation data, or undefined
-     *
-     * @example
-     * ```typescript
-     * const user = await User.query().with("posts").first();
-     *
-     * const posts = user.getRelation<Post[]>("posts");
-     * console.log(posts?.length);
-     * ```
-     */
-    getRelation(relationName) {
-        return this.loadedRelations.get(relationName);
-    }
-    /**
-     * Get a model class by its name from the global registry.
-     *
-     * Models must be decorated with @RegisterModel() to be available in the registry.
-     *
-     * @param name - The model class name
-     * @returns The model class or undefined if not found
-     *
-     * @example
-     * ```typescript
-     * const UserModel = Model.getModel("User");
-     * if (UserModel) {
-     *   const user = await UserModel.find(1);
-     * }
-     * ```
-     */
-    static getModel(name) {
-        return registerModel.getModelFromRegistry(name);
-    }
-    /**
-     * Get all registered models from the global registry.
-     *
-     * Only models decorated with @RegisterModel() will appear here.
-     *
-     * @returns A Map of all registered model classes by name
-     *
-     * @example
-     * ```typescript
-     * const allModels = Model.getAllModels();
-     * for (const [name, ModelClass] of allModels) {
-     *   console.log(`Found model: ${name} with table: ${ModelClass.table}`);
-     * }
-     * ```
-     */
-    static getAllModels() {
-        return registerModel.getAllModelsFromRegistry();
-    }
-    // ============================================================================
-    // STATIC SYNC METHODS
-    // ============================================================================
-    /**
-     * Create a sync operation for a single embedded document.
-     *
-     * When this model is updated, the target model's field
-     * will be updated with the embedded data.
-     *
-     * @param TargetModel - Target model class that receives data
-     * @param targetField - Field path in target model
-     * @returns Sync operation for chaining configuration
-     *
-     * @example
-     * ```typescript
-     * // When Category updates, update Product.category
-     * Category.sync(Product, "category");
-     * ```
-     */
-    static sync(TargetModel, targetField) {
-        return modelSync.modelSync.sync(this, TargetModel, targetField);
-    }
-    /**
-     * Create a sync operation for an array of embedded documents.
-     *
-     * When this model is updated, the corresponding element
-     * in the target model's array field will be updated.
-     *
-     * @param TargetModel - Target model class that receives data
-     * @param targetField - Array field path in target model
-     * @returns Sync operation for chaining configuration
-     *
-     * @example
-     * ```typescript
-     * // When Tag updates, update Post.tags[i] where tags[i].id matches
-     * Tag.syncMany(Post, "tags").identifyBy("id");
-     * ```
-     */
-    static syncMany(TargetModel, targetField) {
-        return modelSync.modelSync.syncMany(this, TargetModel, targetField);
-    }
-    /**
-     * Get model id
-     */
-    get id() {
-        return this.get("id");
-    }
-    /**
-     * Get uuid
-     */
-    get uuid() {
-        return this.get("id");
-    }
-    get(field, defaultValue) {
-        return accessorMethods.getFieldValue(this, field, defaultValue);
-    }
-    only(fields) {
-        return accessorMethods.getOnlyFields(this, fields);
-    }
-    /**
-     * Get a string value
-     */
-    string(key, defaultValue) {
-        return accessorMethods.getStringField(this, key, defaultValue);
-    }
-    /**
-     * Get a number value
-     */
-    number(key, defaultValue) {
-        return accessorMethods.getNumberField(this, key, defaultValue);
-    }
-    /**
-     * Get a boolean value
-     */
-    boolean(key, defaultValue) {
-        return accessorMethods.getBooleanField(this, key, defaultValue);
-    }
-    set(field, value) {
-        return accessorMethods.setFieldValue(this, field, value);
-    }
-    has(field) {
-        return accessorMethods.hasField(this, field);
-    }
-    increment(field, amount) {
-        return accessorMethods.incrementField(this, field, amount);
-    }
-    decrement(field, amount) {
-        return accessorMethods.decrementField(this, field, amount);
-    }
-    unset(...fields) {
-        return accessorMethods.unsetFields(this, ...fields);
-    }
-    merge(values) {
-        return accessorMethods.mergeFields(this, values);
-    }
-    /**
-     * Perform atomoic update from current model instance
-     * Please note that it would require the id to be existing in the current
-     * model instance
-     * @returns number of affected records
-     */
-    async atomicUpdate(operations) {
-        return metaMethods.performAtomicUpdate(this, operations);
-    }
-    /**
-     * Perform atomic increment
-     * This would issue a query update and update the given field without
-     * saving the model
-     */
-    async atomicIncrement(field, amount = 1) {
-        return metaMethods.performAtomicIncrement(this, field, amount);
-    }
-    /**
-     * Perform atomic decrement
-     * This would issue a query update and update the given field without
-     * saving the model
-     */
-    async atomicDecrement(field, amount = 1) {
-        return metaMethods.performAtomicDecrement(this, field, amount);
-    }
-    /**
-     * Determine if current model is active
-     */
-    get isActive() {
-        return this.get(this.isActiveColumn);
-    }
-    /**
-     * Get created at date
-     */
-    get createdAt() {
-        const createdAtColumn = this.self().createdAtColumn;
-        if (!createdAtColumn)
-            return;
-        return this.get(createdAtColumn);
-    }
-    /**
-     * Get updated at date
-     */
-    get updatedAt() {
-        const updatedAtColumn = this.self().updatedAtColumn;
-        if (!updatedAtColumn)
-            return;
-        return this.get(updatedAtColumn);
-    }
-    /**
-     * Check if current model record is created by the given user model
-     */
-    isCreatedBy(user) {
-        return this.get(`createdBy.id`) === user.id;
-    }
-    /**
-     * Checks whether the model's data has changed since instantiation or last reset.
-     *
-     * @returns `true` if any fields have been modified or removed, `false` otherwise
-     *
-     * @example
-     * ```typescript
-     * const user = new User({ name: "Alice" });
-     * user.hasChanges(); // false
-     * user.set("name", "Bob");
-     * user.hasChanges(); // true
-     * ```
-     */
-    hasChanges() {
-        return dirtyMethods.checkHasChanges(this);
-    }
-    /**
-     * Check if the given column has been modified.
-     *
-     * @param column - The column name to check
-     * @returns `true` if the column has been modified, `false` otherwise
-     *
-     * @example
-     * ```typescript
-     * user.set("name", "Bob");
-     * user.isDirty("name"); // true
-     * ```
-     */
-    isDirty(column) {
-        return dirtyMethods.checkIsDirty(this, column);
-    }
-    /**
-     * Retrieves all dirty columns with their old and new values.
-     *
-     * @returns A record mapping each dirty column to its previous and current value
-     *
-     * @example
-     * ```typescript
-     * user.set("name", "Bob");
-     * user.getDirtyColumnsWithValues();
-     * // { name: { oldValue: "Alice", newValue: "Bob" } }
-     * ```
-     */
-    getDirtyColumnsWithValues() {
-        return dirtyMethods.getDirtyColumnsWithValues(this);
-    }
-    /**
-     * Lists all columns that have been removed from the model's data.
-     *
-     * @returns An array of field names that were present initially but have been unset
-     *
-     * @example
-     * ```typescript
-     * user.unset("tempField");
-     * user.getRemovedColumns(); // ["tempField"]
-     * ```
-     */
-    getRemovedColumns() {
-        return dirtyMethods.getRemovedColumns(this);
-    }
-    /**
-     * Lists all columns that have been modified since instantiation or last reset.
-     *
-     * @returns An array of field names that have changed
-     *
-     * @example
-     * ```typescript
-     * user.set("name", "Bob");
-     * user.getDirtyColumns(); // ["name"]
-     * ```
-     */
-    getDirtyColumns() {
-        return dirtyMethods.getDirtyColumns(this);
-    }
-    /**
-     * Emits a lifecycle event to both per-model and global listeners.
-     *
-     * This method is public so that external services (like the writer) can trigger
-     * lifecycle events when appropriate.
-     *
-     * @param event - The event name (e.g., "saving", "created", "deleting")
-     * @param context - Optional context data to pass to listeners
-     *
-     * @example
-     * ```typescript
-     * await user.emitEvent("saving");
-     * await user.emitEvent("validated", { errors: [] });
-     * ```
-     */
-    async emitEvent(event, context) {
-        return instanceEventMethods.emitModelEvent(this, event, context);
-    }
-    /**
-     * Register a listener for a model lifecycle event on this instance.
-     *
-     * @param event - Event name (e.g., "saving", "updated")
-     * @param listener - Callback function
-     * @returns Unsubscribe function
-     */
-    on(event, listener) {
-        return instanceEventMethods.onModelEvent(this, event, listener);
-    }
-    /**
-     * Register a one-time listener for a model lifecycle event on this instance.
-     *
-     * @param event - Event name
-     * @param listener - Callback function
-     * @returns Unsubscribe function
-     */
-    once(event, listener) {
-        return instanceEventMethods.onceModelEvent(this, event, listener);
-    }
-    /**
-     * Remove a listener from this instance.
-     *
-     * @param event - Event name
-     * @param listener - Callback function to remove
-     */
-    off(event, listener) {
-        instanceEventMethods.offModelEvent(this, event, listener);
-    }
-    /**
-     * Resolves the data source associated with this model.
-     *
-     * Resolution order:
-     * 1. If `dataSource` is a string, looks it up in the data-source registry
-     * 2. If `dataSource` is a DataSource instance, returns it directly
-     * 3. Otherwise, returns the default data source from the registry
-     *
-     * @returns The resolved DataSource instance
-     * @throws Error if no data source is found
-     *
-     * @example
-     * ```typescript
-     * class User extends Model {
-     *   public static dataSource = "primary";
-     * }
-     *
-     * const ds = User.getDataSource();
-     * ```
-     */
-    static getDataSource() {
-        return queryMethods.resolveDataSource(this);
-    }
-    /**
-     * Get driver instance
-     */
-    static getDriver() {
-        return this.getDataSource().driver;
-    }
-    /**
-     * Generate next id and set it to current model's id
-     */
-    async generateNextId() {
-        return metaMethods.generateModelNextId(this);
-    }
-    /**
-     * Apply model defaults from data source configuration.
-     *
-     * This is called automatically by getDataSource() the first time
-     * a model accesses its data source. Defaults are only applied if
-     * the model doesn't already have its own value set.
-     *
-     * The hierarchy is:
-     * 1. Model static property (highest priority - skipped here)
-     * 2. Database config modelDefaults (passed here)
-     * 3. Driver modelDefaults (merged before passing here)
-     * 4. Framework defaults (fallback values in the code)
-     *
-     * @param defaults - Model default configuration from data source
-     */
-    static applyModelDefaults(defaults) {
-        metaMethods.applyDefaultsToModel(this, defaults);
-    }
-    /**
-     * Add a global scope that is automatically applied to all queries.
-     *
-     * Global scopes are inherited by child models and applied before query execution.
-     * Use for security filters, multi-tenancy, soft deletes, etc.
-     *
-     * @param name - Unique name for the scope
-     * @param callback - Function that modifies the query
-     * @param options - Scope options (timing: 'before' | 'after')
-     *
-     * @example
-     * ```typescript
-     * // Multi-tenancy scope
-     * Model.addGlobalScope('tenant', (query) => {
-     *   query.where('tenantId', getCurrentTenant());
-     * }, { timing: 'before' });
-     *
-     * // Soft delete scope
-     * User.addGlobalScope('notDeleted', (query) => {
-     *   query.whereNull('deletedAt');
-     * });
-     * ```
-     */
-    static addGlobalScope(name, callback, options = {}) {
-        scopeMethods.addGlobalModelScope(this, name, callback, options);
-    }
-    /**
-     * Remove a global scope by name.
-     *
-     * @param name - Name of the scope to remove
-     *
-     * @example
-     * ```typescript
-     * Model.removeGlobalScope('tenant');
-     * ```
-     */
-    static removeGlobalScope(name) {
-        scopeMethods.removeGlobalModelScope(this, name);
-    }
-    /**
-     * Add a local scope that can be manually applied to queries.
-     *
-     * Local scopes are reusable query snippets that developers opt into.
-     * They are not automatically applied.
-     *
-     * @param name - Unique name for the scope
-     * @param callback - Function that modifies the query
-     *
-     * @example
-     * ```typescript
-     * // Define reusable scopes
-     * User.addScope('active', (query) => {
-     *   query.where('isActive', true);
-     * });
-     *
-     * User.addScope('admins', (query) => {
-     *   query.where('role', 'admin');
-     * });
-     *
-     * // Use explicitly
-     * await User.query().scope('active').get();
-     * await User.query().scope('admins').get();
-     * ```
-     */
-    static addScope(name, callback) {
-        scopeMethods.addLocalModelScope(this, name, callback);
-    }
-    /**
-     * Remove a local scope by name.
-     *
-     * @param name - Name of the scope to remove
-     *
-     * @example
-     * ```typescript
-     * User.removeScope('active');
-     * ```
-     */
-    static removeScope(name) {
-        scopeMethods.removeLocalModelScope(this, name);
-    }
-    /**
-     * Create a new query builder for this model
-     */
-    static query() {
-        return queryMethods.buildQuery(this, Model);
-    }
-    static with(...args) {
-        return this.query().with(...args);
-    }
-    /**
-     * Load relations using database JOINs in a single query.
-     *
-     * Unlike `with()` which uses separate queries, `joinWith()` uses
-     * LEFT JOIN (SQL) or $lookup (MongoDB) to fetch related data
-     * in a single query. The related data is hydrated into proper
-     * model instances and attached to the main model.
-     *
-     * Best for: belongsTo and hasOne relations where you need
-     * efficient single-query loading.
-     *
-     * @param relations - Relation names to load via JOIN
-     * @returns Query builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Single relation
-     * const post = await Post.joinWith("author").first();
-     * console.log(post.author); // User model instance
-     * console.log(post.data);   // { id, title, authorId } - no author data
-     *
-     * // Multiple relations
-     * const post = await Post.joinWith("author", "category").first();
-     * ```
-     */
-    static joinWith(...relations) {
-        return this.query().joinWith(...relations);
-    }
-    /**
-     * Create new query builder.
-     *
-     * If the model has a static `builder` property set to a query builder class,
-     * it will be instantiated instead of the default driver query builder.
-     *
-     * @example
-     * ```typescript
-     * class UserQueryBuilder<T = User> extends MongoQueryBuilder<T> {
-     *   active() { return this.where("isActive", true); }
-     * }
-     *
-     * class User extends Model {
-     *   static builder = UserQueryBuilder;  // That's it! ✨
-     * }
-     *
-     * // Now User.query() returns UserQueryBuilder<User> with autocomplete!
-     * ```
-     */
-    static newQueryBuilder() {
-        return queryMethods.buildNewQueryBuilder(this);
-    }
-    /**
-     * Get First matched record for the given filter
-     */
-    static async first(filter) {
-        return queryMethods.findFirst(this, filter);
-    }
-    /**
-     * Get last matched record for the given filter
-     */
-    static async last(filter) {
-        return queryMethods.findLast(this, filter);
-    }
-    static where(...args) {
-        return this.query().where(...args);
-    }
-    /**
-     * Count the number of records in the table
-     * @param filter - The filter to apply to the query
-     */
-    static count(filter) {
-        return queryMethods.countRecords(this, filter);
-    }
-    /**
-     * Find record by id
-     */
-    static async find(id) {
-        return queryMethods.findById(this, id);
-    }
-    /**
-     * Get all records from the table
-     *
-     * @param filter - The filter to apply to the query
-     * @returns All records from the table
-     */
-    static async all(filter) {
-        return queryMethods.findAll(this, filter);
-    }
-    /**
-     * Perform pagination
-     */
-    static async paginate(options = {}) {
-        return queryMethods.paginateRecords(this, options);
-    }
-    /**
-     * Get latest records from the table
-     *
-     * @param filter - The filter to apply to the query
-     */
-    static async latest(filter) {
-        return queryMethods.findLatest(this, filter);
-    }
-    /**
-     * Increment the given field by the given amount using atomic update
-     *
-     * @example ```typescript
-     * // Increase age by 1 for user id 1
-     * User.increment({id: 1}, "age", 1);
-     * // Increase age by 1 and views by 2 for user id 1
-     * User.increment({id: 1}, {age: 1, views: 2});
-     * ```
-     */
-    static increase(filter, field, amount) {
-        return queryMethods.increaseField(this, filter, field, amount);
-    }
-    /**
-     * Decrement the given field by the given amount using atomic update
-     * @example ```typescript
-     * // Decrease age by 1 for user id 1
-     * User.decrement({id: 1}, "age", 1);
-     * // Decrease age by 1 and views by 2 for user id 1
-     * User.decrement({id: 1}, {age: 1, views: 2});
-     * ```
-     */
-    static decrease(filter, field, amount) {
-        return queryMethods.decreaseField(this, filter, field, amount);
-    }
-    /**
-     * Perform atomic operation
-     * Example
-     *
-     * ```typescript
-     * const user = await User.atomic({id: 1}, {$inc: {age: 1}})
-     * Returns user model with updated age
-     */
-    static async atomic(filter, operations) {
-        return queryMethods.performAtomic(this, filter, operations);
-    }
-    /**
-     * Perform a direct update $set for the given id
-     */
-    static async update(id, data) {
-        return queryMethods.updateById(this, id, data);
-    }
-    /**
-     * Find one and update multiple records that matches the provided filter and return the updated record
-     * @param filter - Filter conditions
-     * @param update - Update operations ($set, $unset, $inc)
-     * @returns The updated records
-     */
-    static async findAndUpdate(filter, update) {
-        return queryMethods.findAndUpdateRecords(this, filter, update);
-    }
-    /**
-     * Find one and update a single record that matches the provided filter and return the updated record
-     * @param filter - Filter conditions
-     * @param update - Update operations ($set, $unset, $inc)
-     * @returns The updated record or null
-     */
-    static async findOneAndUpdate(filter, update) {
-        return queryMethods.findOneAndUpdateRecord(this, filter, update);
-    }
-    /**
-     * Find and replace the entire document that matches the provided filter and return the replaced document
-     */
-    static async findAndReplace(filter, document) {
-        return queryMethods.findAndReplaceRecord(this, filter, document);
-    }
-    /**
-     * Destroy (delete) the current model instance from the database.
-     *
-     * Emits lifecycle events:
-     * - `deleting` - Before deletion
-     * - `deleted` - After successful deletion
-     *
-     * @param options - Destroy options (strategy override, skipEvents)
-     * @throws {Error} If the model is new (not saved) or if deletion fails
-     *
-     * @example
-     * ```typescript
-     * const user = await User.find(1);
-     * await user.destroy(); // Uses default strategy
-     * await user.destroy({ strategy: "permanent" }); // Override strategy
-     * await user.destroy({ skipEvents: true }); // Silent delete
-     * ```
-     */
-    async destroy(options) {
-        return deleteMethods.destroyModel(this, options);
-    }
-    /**
-     * Get the class constructor from an instance.
-     *
-     * This helper method allows instance methods to access static properties
-     * and methods of the model class in a type-safe way.
-     *
-     * @returns The model class constructor
-     *
-     * @example
-     * ```typescript
-     * const constructor = this.self();
-     * const table = constructor.table;
-     * await constructor.deleteOne({ id: 1 });
-     * ```
-     */
-    self() {
-        return this.constructor;
-    }
-    /**
-     * Creates an immutable clone of the model with its current state.
-     *
-     * The cloned model:
-     * - Contains a deep copy of all current data
-     * - Has frozen (immutable) data that cannot be modified
-     * - Preserves the `isNew` flag from the original
-     * - Has no dirty changes (clean state)
-     * - Cannot be saved or modified
-     *
-     * This is useful for:
-     * - Creating snapshots of model state
-     * - Passing read-only model data to other parts of the application
-     * - Preventing accidental mutations
-     * - Maintaining historical records
-     *
-     * @returns A new immutable model instance with the current state
-     *
-     * @example
-     * ```typescript
-     * const user = new User({ name: "Alice", email: "alice@example.com" });
-     * await user.save();
-     *
-     * // Create an immutable snapshot
-     * const snapshot = user.clone();
-     *
-     * // This will throw an error because the clone is immutable
-     * snapshot.set("name", "Bob"); // TypeError: Cannot assign to read only property
-     *
-     * // Original can still be modified
-     * user.set("name", "Bob");
-     * await user.save();
-     * ```
-     */
-    clone() {
-        return hydrationMethods.cloneModel(this);
-    }
-    /**
-     * Recursively freezes an object and all its nested properties.
-     *
-     * @param obj - The object to freeze
-     * @returns The frozen object
-     */
-    deepFreeze(obj) {
-        return hydrationMethods.deepFreezeObject(obj);
-    }
-    /**
-     * Get table name
-     */
-    getTableName() {
-        return this.self().table;
-    }
-    /**
-     * Get primary key name
-     */
-    getPrimaryKey() {
-        return this.self().primaryKey;
-    }
-    /**
-     * Get model schema
-     */
-    getSchema() {
-        return this.self().schema;
-    }
-    /**
-     * Check if schema has the given key
-     */
-    schemaHas(key) {
-        return this.self().schema?.schema[key] !== undefined;
-    }
-    /**
-     * Get strict mode
-     */
-    getStrictMode() {
-        return this.self().strictMode;
-    }
-    /**
-     * Get data source (Connection)
-     */
-    getConnection() {
-        return this.self().getDataSource();
-    }
-    /**
-     * Delete all matching documents from the table.
-     */
-    static async delete(filter) {
-        return deleteMethods.deleteRecords(this, filter);
-    }
-    /**
-     * Delete a single matching document from the table.
-     */
-    static async deleteOne(filter) {
-        return deleteMethods.deleteOneRecord(this, filter);
-    }
-    /**
-     * Restore a single deleted record by its ID.
-     *
-     * Automatically detects whether the record was deleted via "trash" or "soft" strategy.
-     * Handles ID conflicts based on options.
-     *
-     * @param id - The primary key value of the record to restore
-     * @param options - Restorer options (onIdConflict, skipEvents)
-     * @returns The restored model instance
-     *
-     * @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 user = await User.restore(123);
-     *
-     * // Restore and fail if ID conflict
-     * const user = await User.restore(123, { onIdConflict: "fail" });
-     *
-     * // Silent restore (skip events)
-     * const user = await User.restore(123, { skipEvents: true });
-     * ```
-     */
-    static async restore(id, options) {
-        return restoreMethods.restoreRecord(this, id, options);
-    }
-    /**
-     * 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 (onIdConflict, skipEvents)
-     * @returns Array of restored model instances
-     *
-     * @example
-     * ```typescript
-     * // Restore all with default options
-     * const users = await User.restoreAll();
-     *
-     * // Restore all and fail on any ID conflict
-     * const users = await User.restoreAll({ onIdConflict: "fail" });
-     * ```
-     */
-    static async restoreAll(options) {
-        return restoreMethods.restoreAllRecords(this, options);
-    }
-    /**
-     * Create a new record in database and return the model instance.
-     *
-     * The data type is automatically inferred from the model's schema type.
-     *
-     * @param data - Partial data matching the model's schema type
-     * @returns The created model instance
-     *
-     * @example
-     * ```typescript
-     * // TypeScript automatically infers UserSchema from User model
-     * const user = await User.create({
-     *   name: "Alice",
-     *   email: "alice@example.com",
-     *   age: 30
-     * });
-     * // Type: User (with UserSchema inferred)
-     * ```
-     */
-    static async create(data) {
-        return writeMethods.createRecord(this, data);
-    }
-    /**
-     * Create many documents and return an array of created models
-     */
-    static async createMany(data) {
-        return writeMethods.createManyRecords(this, data);
-    }
-    /**
-     * Find a record or create it if not found.
-     *
-     * Does NOT update existing records - returns them as-is.
-     * Useful when you want to ensure a record exists without modifying it.
-     *
-     * @param filter - Conditions to find by
-     * @param data - Data to create if not found (merged with filter)
-     * @returns Promise resolving to found or created model
-     *
-     * @example
-     * ```typescript
-     * // Ensure default admin exists (don't modify if exists)
-     * const admin = await User.findOrCreate(
-     *   { email: "admin@example.com" },
-     *   { email: "admin@example.com", name: "Admin", role: "admin" }
-     * );
-     * // If admin exists, returns existing (password unchanged)
-     * // If not found, creates new admin
-     * ```
-     */
-    static async findOrCreate(filter, data) {
-        return writeMethods.findOrCreateRecord(this, filter, data);
-    }
-    /**
-     * Upsert (insert or update) a record atomically.
-     *
-     * Uses the driver's native upsert operation for atomic insert-or-update.
-     * More efficient than updateOrCreate as it's a single database operation.
-     *
-     * Includes full Model features:
-     * - ID generation (if creating)
-     * - createdAt timestamp (if creating)
-     * - updatedAt timestamp (always)
-     * - Validation & casting
-     * - Lifecycle events
-     *
-     * @param filter - Conditions to find by (used for conflict detection)
-     * @param data - Data to update or create (merged with filter)
-     * @param options - Upsert options (conflictColumns for PostgreSQL, etc.)
-     * @returns Promise resolving to upserted model
-     *
-     * @example
-     * ```typescript
-     * // PostgreSQL: upsert on unique email
-     * const user = await User.upsert(
-     *   { email: "user@example.com" },
-     *   {
-     *     email: "user@example.com",
-     *     name: "John Updated",
-     *     lastSyncedAt: new Date()
-     *   },
-     *   { conflictColumns: ["email"] }
-     * );
-     *
-     * // MongoDB: upsert by filter
-     * const user = await User.upsert(
-     *   { externalId: "ext-123" },
-     *   {
-     *     externalId: "ext-123",
-     *     name: "John Updated",
-     *     email: "john.new@example.com"
-     *   }
-     * );
-     * ```
-     */
-    static async upsert(filter, data, options) {
-        return writeMethods.upsertRecord(this, filter, data, options);
-    }
-    /**
-     * Update a record or create it if not found (upsert).
-     *
-     * @deprecated Use `upsert()` instead for better performance and atomicity.
-     * This method is kept for backward compatibility but uses upsert internally.
-     *
-     * @param filter - Conditions to find by
-     * @param data - Data to update or create (merged with filter)
-     * @returns Promise resolving to updated or created model
-     */
-    static async updateOrCreate(filter, data, options) {
-        // Use upsert internally for better performance
-        return await this.upsert(filter, data, options);
-    }
-    /**
-     * Find one and delete a record that matches the filter and return the deleted record.
-     *
-     * @param filter - Filter conditions
-     * @param options - Optional delete options
-     * @returns The deleted model instance or null if not found
-     *
-     * @example
-     * ```typescript
-     * const deleted = await User.findOneAndDelete({ id: 1 });
-     * if (deleted) {
-     *   console.log('Deleted user:', deleted.get('name'));
-     * }
-     * ```
-     */
-    static async findOneAndDelete(filter, options) {
-        return queryMethods.findOneAndDeleteRecord(this, filter, options);
-    }
-    /**
-     * Returns embedded data for sync operations.
-     * Excludes internal MongoDB fields and ensures proper date serialization.
-     *
-     * @returns Embedded data object suitable for syncing
-     *
-     * @example
-     * ```typescript
-     * const user = await User.find(1);
-     * const embedData = user.embedData;
-     * // Returns: { id: 1, name: "Alice", email: "alice@example.com", ... }
-     * // Excludes: _id
-     * ```
-     */
-    get embedData() {
-        return this.self().embed ? this.only(this.self().embed) : this.data;
-    }
-    /**
-     * Cleanup model events
-     */
-    static $cleanup() {
-        staticEventMethods.cleanupModelEvents(this);
-    }
-    /**
-     * Accesses the event emitter dedicated to this model constructor.
-     *
-     * Each model subclass gets its own isolated event emitter, allowing you to
-     * register lifecycle hooks that only apply to that specific model.
-     *
-     * @returns The ModelEvents instance for this model constructor
-     *
-     * @example
-     * ```typescript
-     * User.events().onSaving((user) => {
-     *   console.log("User is being saved:", user);
-     * });
-     * ```
-     */
-    static events() {
-        return staticEventMethods.getModelEvents(this);
-    }
-    /**
-     * Registers an event listener for this model constructor.
-     *
-     * Convenience shorthand for `Model.events().on(...)`.
-     *
-     * @param event - The event name (e.g., "saving", "created")
-     * @param listener - The callback to invoke when the event fires
-     * @returns An unsubscribe function
-     *
-     * @example
-     * ```typescript
-     * const unsubscribe = User.on("saving", (user) => {
-     *   console.log("Saving user:", user);
-     * });
-     * ```
-     */
-    static on(event, listener) {
-        return staticEventMethods.onStaticEvent(this, event, listener);
-    }
-    /**
-     * Registers a one-time event listener for this model constructor.
-     *
-     * The listener will automatically unsubscribe after its first invocation.
-     * Convenience shorthand for `Model.events().once(...)`.
-     *
-     * @param event - The event name (e.g., "saving", "created")
-     * @param listener - The callback to invoke when the event fires
-     * @returns An unsubscribe function
-     *
-     * @example
-     * ```typescript
-     * User.once("created", (user) => {
-     *   console.log("First user created:", user);
-     * });
-     * ```
-     */
-    static once(event, listener) {
-        return staticEventMethods.onceStaticEvent(this, event, listener);
-    }
-    /**
-     * Removes an event listener from this model constructor.
-     *
-     * Convenience shorthand for `Model.events().off(...)`.
-     *
-     * @param event - The event name
-     * @param listener - The callback to remove
-     *
-     * @example
-     * ```typescript
-     * const listener = (user) => console.log(user);
-     * User.on("saving", listener);
-     * User.off("saving", listener);
-     * ```
-     */
-    static off(event, listener) {
-        staticEventMethods.offStaticEvent(this, event, listener);
-    }
-    /**
-     * Accesses the global event emitter shared by all model instances.
-     *
-     * Use this for cross-cutting concerns like auditing, logging, or injecting
-     * common fields (e.g., `createdBy`, `updatedBy`) across all models.
-     *
-     * @returns The global ModelEvents instance
-     *
-     * @example
-     * ```typescript
-     * Model.globalEvents().onSaving((model) => {
-     *   model.set("updatedAt", new Date());
-     * });
-     * ```
-     */
-    static globalEvents() {
-        return staticEventMethods.getGlobalEvents();
-    }
-    /**
-     * Replace the model's data entirely.
-     *
-     * Used internally by the writer after validation to update the model
-     * with validated/casted data.
-     *
-     * **Warning:** This replaces all data and updates the dirty tracker.
-     * Use with caution in application code.
-     *
-     * @param data - New data to replace current data
-     *
-     * @example
-     * ```typescript
-     * // Internal usage by writer
-     * model.replaceData(validatedData);
-     * ```
-     */
-    replaceData(data) {
-        hydrationMethods.replaceModelData(this, data);
-    }
-    /**
-     * Save the model to the database.
-     *
-     * Performs insert if `isNew === true`, otherwise performs update.
-     * Automatically validates, casts, generates IDs, and emits lifecycle events.
-     *
-     * **Features:**
-     * - Validation via @warlock.js/seal schema
-     * - Data casting (string → number, etc.)
-     * - ID generation (NoSQL only)
-     * - Partial updates (only changed fields)
-     * - Lifecycle events (validating, saving, created/updated, saved)
-     *
-     * @param data - Optional data to merge before saving
-     * @param options - Save options
-     * @returns The model instance for method chaining
-     *
-     * @throws {ValidationError} If validation fails
-     * @throws {Error} If database operation fails
-     *
-     * @example
-     * ```typescript
-     * // Simple save
-     * const user = new User({ name: "Alice" });
-     * await user.save();
-     *
-     * // Merge data before saving
-     * await user.save({ age: 31, email: "alice@example.com" });
-     *
-     * // Silent save (no events)
-     * await user.save(null, { skipEvents: true });
-     *
-     * // Skip validation
-     * await user.save(null, { skipValidation: true });
-     *
-     * // Method chaining
-     * await user.set("name", "Bob").save();
-     * ```
-     */
-    async save(options) {
-        return writeMethods.saveModel(this, options);
-    }
-    /**
-     * Serialize the model data for storage in the database.
-     *
-     * Uses the driver's `serialize` to apply driver-specific type transformations
-     * (e.g. Date → ISO string, BigInt → string for Postgres).
-     *
-     * **Not** the same as `toSnapshot` — this is a DB write concern, not a cache concern.
-     */
-    serialize() {
-        return hydrationMethods.serializeModel(this);
-    }
-    /**
-     * Produce a plain-object snapshot of this model suitable for cache storage.
-     *
-     * - `data`: The model's own fields, serialized via the driver (handles Dates, BigInt, ObjectId).
-     * - `relations`: Each entry in `loadedRelations` recursively snapshotted via `toSnapshot`.
-     *   A relation that was loaded but resolved to `null` is stored as `null` (not omitted),
-     *   so that `fromSnapshot` can distinguish "loaded + null" from "never loaded".
-     *
-     * Use `Model.fromSnapshot(snapshot)` to reconstruct.
-     *
-     * @example
-     * ```typescript
-     * await cache.set(key, chat.toSnapshot());
-     * ```
-     */
-    toSnapshot() {
-        return hydrationMethods.modelToSnapshot(this);
-    }
-    /**
-     * Reconstruct a model instance (with relations) from a cache snapshot.
-     *
-     * Counterpart to `toSnapshot`. Applies driver deserialization (e.g. ISO string → Date)
-     * and recursively hydrates any nested relation snapshots via `RelationHydrator`.
-     *
-     * @example
-     * ```typescript
-     * const snapshot = await cache.get(key);
-     * const chat = Chat.fromSnapshot(snapshot);
-     * chat.unit; // Unit model instance, fully hydrated
-     * ```
-     */
-    static fromSnapshot(snapshot) {
-        return hydrationMethods.modelFromSnapshot(this, snapshot);
-    }
-    /**
-     * Create a model instance from raw data (no relations).
-     *
-     * This is the data-only hydration path, used by the query builder when
-     * converting a raw DB row into a model instance. Relations are NOT restored
-     * here — use `fromSnapshot` when restoring from a cache snapshot that
-     * includes relation data.
-     *
-     * @example
-     * ```typescript
-     * // Query builder internals:
-     * const user = User.hydrate(rawRow);
-     * ```
-     */
-    static hydrate(data) {
-        return hydrationMethods.hydrateModel(this, data);
-    }
-    /**
-     * Convert the model into JSON
-     */
-    toJSON() {
-        return serializationMethods.modelToJSON(this);
-    }
-}exports.Model=Model;//# sourceMappingURL=model.js.map