@zintrust/core 3.5.1 → 3.6.0

package/src/orm/Model.js

@@ -0,0 +1,848 @@
+/**
+ * Enhanced Model with Relationships
+ * Full ORM capabilities with eager/lazy loading
+ */
+import { generateUuid } from '../common/utility.js';
+import { DEFAULTS } from '../config/constants.js';
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { isFunction, isMissingLike, isObject, isWhitespaceOnly } from '../helper/index.js';
+import { useDatabase } from './Database.js';
+import { QueryBuilder } from './QueryBuilder.js';
+import { RelationBootstrapDiagnostics, } from './RelationBootstrapDiagnostics.js';
+import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, } from './Relationships.js';
+const getRelatedTableName = (relatedModel) => {
+    if (typeof relatedModel.getTable === 'function') {
+        return relatedModel.getTable();
+    }
+    throw ErrorFactory.createConfigError('Related model does not provide a table name');
+};
+const isHydratedModelInstance = (value) => {
+    if (!isObject(value))
+        return false;
+    return (isFunction(value['getAttribute']) &&
+        isFunction(value['setAttribute']) &&
+        isFunction(value['getAttributes']) &&
+        isFunction(value['save']) &&
+        isFunction(value['exists']));
+};
+/**
+ * Cast attribute value based on config
+ */
+const castAttribute = (config, key, value) => {
+    const castType = config.casts ? config.casts[key] : undefined;
+    if (castType === undefined)
+        return value;
+    switch (castType) {
+        case 'boolean':
+            return value === true || value === 1 || value === '1';
+        case 'integer':
+            return Number.parseInt(String(value), 10);
+        case 'bigint': {
+            // Native BigInt if supported, otherwise string
+            try {
+                return BigInt(value);
+            }
+            catch {
+                return String(value);
+            }
+        }
+        case 'uuid':
+            return String(value);
+        case 'float':
+            return Number.parseFloat(String(value));
+        case 'date':
+            return new Date(String(value)).toISOString().split('T')[0];
+        case 'datetime':
+            return new Date(String(value)).toISOString();
+        case 'json':
+            return typeof value === 'string' ? JSON.parse(value) : value;
+        default:
+            return value;
+    }
+};
+const assignAttributes = (config, attrs, newAttrs, options) => {
+    for (const [key, value] of Object.entries(newAttrs)) {
+        if (options.respectFillable && config.fillable.length > 0 && !config.fillable.includes(key)) {
+            continue;
+        }
+        const nextValue = options.applyMutators
+            ? (config.mutators?.[key]?.(value, attrs) ?? value)
+            : value;
+        attrs[key] = castAttribute(config, key, nextValue);
+    }
+};
+/**
+ * Fill attributes based on fillable config
+ */
+const fillAttributes = (config, attrs, newAttrs) => {
+    assignAttributes(config, attrs, newAttrs, { applyMutators: true, respectFillable: true });
+};
+const hydrateAttributes = (config, attrs, storedAttrs) => {
+    assignAttributes(config, attrs, storedAttrs, { applyMutators: false, respectFillable: false });
+};
+const applyAccessor = (config, key, attrs) => {
+    const raw = attrs[key];
+    const accessor = config.accessors?.[key];
+    return accessor ? accessor(raw, attrs) : raw;
+};
+const runObservers = async (config, hook, model) => {
+    const observers = config.observers;
+    if (observers === undefined || observers.length === 0)
+        return;
+    // Run "before" hooks sequentially to ensure safety and consistent state changes.
+    // This allows observers to modify the model or throw errors to cancel the operation.
+    const isBeforeHook = ['saving', 'creating', 'updating', 'deleting'].includes(hook);
+    if (isBeforeHook) {
+        for (const observer of observers) {
+            const fn = observer[hook];
+            if (typeof fn === 'function') {
+                // eslint-disable-next-line no-await-in-loop
+                await fn(model);
+            }
+        }
+        return;
+    }
+    // Run "after" hooks in parallel for better performance.
+    // These are typically side effects (logging, notifications) that don't depend on each other.
+    await Promise.all(observers.map(async (observer) => {
+        const fn = observer[hook];
+        return typeof fn === 'function' ? Promise.resolve(fn(model)) : Promise.resolve();
+    }));
+};
+const createModelJSON = (config, attrs) => {
+    const json = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (config.hidden.includes(key))
+            continue;
+        // Serialize BigInt as string to keep JSON stable
+        if (typeof value === 'bigint') {
+            json[key] = String(value);
+            continue;
+        }
+        // Convert Dates to ISO strings for JSON
+        if (value instanceof Date) {
+            json[key] = value.toISOString();
+            continue;
+        }
+        json[key] = value;
+    }
+    return json;
+};
+const createHasOneFactory = (config) => (relatedModel, foreignKey) => HasOne.create(relatedModel, foreignKey ?? `${config.table.slice(0, -1)}_id`, 'id');
+const createHasManyFactory = (config) => (relatedModel, foreignKey) => HasMany.create(relatedModel, foreignKey ?? `${config.table.slice(0, -1)}_id`, 'id');
+const createBelongsToFactory = () => (relatedModel, foreignKey) => {
+    const relatedTable = getRelatedTableName(relatedModel);
+    return BelongsTo.create(relatedModel, foreignKey ?? `${relatedTable.slice(0, -1)}_id`, 'id');
+};
+const createBelongsToManyFactory = (config) => (relatedModel, throughTable, foreignKey, relatedKey) => {
+    const relatedTable = getRelatedTableName(relatedModel);
+    const table = throughTable ?? [config.table, relatedTable].sort((a, b) => a.localeCompare(b)).join('_');
+    return BelongsToMany.create(relatedModel, table, foreignKey ?? `${config.table.slice(0, -1)}_id`, relatedKey ?? `${relatedTable.slice(0, -1)}_id`);
+};
+const createMorphOneFactory = () => (relatedModel, morphName, morphType, morphId, localKey) => MorphOne.create(relatedModel, morphName, morphType, morphId, localKey);
+const createMorphManyFactory = () => (relatedModel, morphName, morphType, morphId, localKey) => MorphMany.create(relatedModel, morphName, morphType, morphId, localKey);
+const createMorphToFactory = () => (morphName, morphMap, morphType, morphId) => MorphTo.create(morphName, morphMap, morphType, morphId);
+const createHasOneThroughFactory = () => (relatedModel, through, foreignKey, throughForeignKey, localKey, secondLocalKey) => HasOneThrough.create(relatedModel, through, foreignKey, throughForeignKey, localKey, secondLocalKey);
+const createHasManyThroughFactory = () => (relatedModel, through, foreignKey, throughForeignKey, localKey, secondLocalKey) => HasManyThrough.create(relatedModel, through, foreignKey, throughForeignKey, localKey, secondLocalKey);
+const createModelRelationships = (config) => {
+    return {
+        hasOne: createHasOneFactory(config),
+        hasMany: createHasManyFactory(config),
+        belongsTo: createBelongsToFactory(),
+        belongsToMany: createBelongsToManyFactory(config),
+        morphOne: createMorphOneFactory(),
+        morphMany: createMorphManyFactory(),
+        morphTo: createMorphToFactory(),
+        hasOneThrough: createHasOneThroughFactory(),
+        hasManyThrough: createHasManyThroughFactory(),
+    };
+};
+const applySaveTimestamps = (config, attrs, isCreate) => {
+    if ((config.timestamps ?? false) === false)
+        return;
+    const now = new Date().toISOString();
+    attrs['updated_at'] = now;
+    if (isCreate) {
+        attrs['created_at'] = attrs['created_at'] ?? now;
+    }
+};
+const buildTraceModelChanges = (attrs, dirtyFields) => {
+    if (dirtyFields.length === 0)
+        return undefined;
+    const changes = {};
+    for (const field of dirtyFields) {
+        changes[field] = attrs[field];
+    }
+    return changes;
+};
+const emitTraceModelEvent = (action, config, attrs, dirtyFields = []) => {
+    const emit = globalThis.__zintrust_trace_model_emit__;
+    if (typeof emit !== 'function')
+        return;
+    try {
+        const id = attrs['id'];
+        emit(action, config.table, typeof id === 'string' || typeof id === 'number' ? id : undefined, buildTraceModelChanges(attrs, dirtyFields));
+    }
+    catch {
+        // best-effort trace emission must not affect ORM operations
+    }
+};
+const isMissingPrimaryKeyValue = (value) => {
+    if (isMissingLike(value))
+        return true;
+    return typeof value === 'string' && (value.length === 0 || isWhitespaceOnly(value));
+};
+const createPrimaryKeyObserver = (options) => {
+    const key = options.key ?? 'id';
+    const whenMissing = options.whenMissing ?? true;
+    return Object.freeze({
+        creating(model) {
+            if (!whenMissing)
+                return;
+            const currentValue = model.getAttribute(key);
+            if (!isMissingPrimaryKeyValue(currentValue))
+                return;
+            const nextValue = options.generate();
+            if (isMissingPrimaryKeyValue(nextValue)) {
+                throw ErrorFactory.createValidationError(`Generated primary key for ${key} is missing or blank`);
+            }
+            model.setAttribute(key, nextValue);
+        },
+    });
+};
+const ModelPrimaryKey = Object.freeze({
+    isMissing: isMissingPrimaryKeyValue,
+    using: (options) => createPrimaryKeyObserver(options),
+    uuid: (key = 'id') => createPrimaryKeyObserver({ key, whenMissing: true, generate: generateUuid }),
+});
+const buildPrimaryKeyObservers = (config) => {
+    if (config.primaryKey?.strategy !== 'uuid') {
+        return [];
+    }
+    return [ModelPrimaryKey.uuid(config.primaryKey.key ?? 'id')];
+};
+const normalizeModelConfig = (config) => {
+    const generatedObservers = buildPrimaryKeyObservers(config);
+    if (generatedObservers.length === 0) {
+        return config;
+    }
+    return {
+        ...config,
+        observers: [...generatedObservers, ...(config.observers ?? [])],
+    };
+};
+const persistNewModel = async (config, db, attrs) => {
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
+    const result = await builder.insert({ ...attrs });
+    if (attrs['id'] === undefined && result.id !== null) {
+        attrs['id'] = result.id;
+    }
+};
+const collectDirtyValues = (config, attrs, dirtyFields) => {
+    const keys = new Set(dirtyFields);
+    if (config.timestamps ?? false) {
+        keys.add('updated_at');
+    }
+    return Object.fromEntries([...keys].filter((key) => key in attrs).map((key) => [key, attrs[key]]));
+};
+const persistExistingModel = async (config, db, attrs, dirtyFields) => {
+    const values = collectDirtyValues(config, attrs, dirtyFields);
+    if (Object.keys(values).length === 0)
+        return;
+    const primaryKey = attrs['id'];
+    if (primaryKey === undefined || primaryKey === null || primaryKey === '') {
+        throw ErrorFactory.createDatabaseError('Cannot update a persisted model without an id');
+    }
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
+    await builder.where('id', '=', primaryKey).update(values);
+};
+const persistModelState = async (config, db, attrs, isCreate, dirtyFields) => {
+    if (isCreate) {
+        await persistNewModel(config, db, attrs);
+        return;
+    }
+    await persistExistingModel(config, db, attrs, dirtyFields);
+};
+const mergeDirtyFieldsAfterSaving = (trackedDirtyFields, attrs, original) => {
+    const keys = new Set(trackedDirtyFields);
+    for (const key of Object.keys(attrs)) {
+        if (attrs[key] !== original[key]) {
+            keys.add(key);
+        }
+    }
+    return [...keys];
+};
+const performModelSave = async (model, config, attrs, getDb, context) => {
+    const db = getDb();
+    if (db === undefined)
+        throw ErrorFactory.createDatabaseError('Database not initialized');
+    const isCreate = context.isExists === false;
+    await runObservers(config, 'saving', model);
+    await runObservers(config, isCreate ? 'creating' : 'updating', model);
+    const dirtyFields = isCreate
+        ? context.getDirtyFields()
+        : mergeDirtyFieldsAfterSaving(context.getDirtyFields(), attrs, context.getOriginal());
+    applySaveTimestamps(config, attrs, isCreate);
+    await persistModelState(config, db, attrs, isCreate, dirtyFields);
+    emitTraceModelEvent(isCreate ? 'create' : 'update', config, attrs, dirtyFields);
+    context.setExists(true);
+    context.updateOriginal({ ...attrs });
+    context.clearDirty();
+    await runObservers(config, isCreate ? 'created' : 'updated', model);
+    await runObservers(config, 'saved', model);
+    return true;
+};
+const performModelDelete = async (model, config, getDb, isExists) => {
+    const db = getDb();
+    if (!isExists || db === undefined)
+        return false;
+    await runObservers(config, 'deleting', model);
+    emitTraceModelEvent('delete', config, model.getAttributes());
+    await runObservers(config, 'deleted', model);
+    return true;
+};
+const createAttributeApi = (config, attrs, relations, context) => ({
+    fill: (newAttrs) => {
+        fillAttributes(config, attrs, newAttrs);
+        const original = context.getOriginal();
+        for (const key of Object.keys(newAttrs)) {
+            context.syncReadableProperty(key);
+            if (attrs[key] !== original[key]) {
+                context.dirtyFields.add(key);
+            }
+        }
+        return context.getModel();
+    },
+    setAttribute: (key, value) => {
+        const mutator = config.mutators?.[key];
+        const nextValue = mutator ? mutator(value, attrs) : value;
+        const castedValue = castAttribute(config, key, nextValue);
+        attrs[key] = castedValue;
+        context.syncReadableProperty(key);
+        const original = context.getOriginal();
+        if (original[key] === castedValue) {
+            context.dirtyFields.delete(key);
+        }
+        else {
+            context.dirtyFields.add(key);
+        }
+        return context.getModel();
+    },
+    getAttribute: (key) => {
+        if (relations[key] !== undefined)
+            return relations[key];
+        return applyAccessor(config, key, attrs);
+    },
+    getAttributes: () => ({ ...attrs }),
+    setRelation: (name, value) => {
+        relations[name] = value;
+        context.syncReadableProperty(name);
+    },
+    getRelation: (name) => relations[name],
+    toJSON: () => createModelJSON(config, attrs),
+    isDirty: (key) => {
+        if (key !== undefined)
+            return context.dirtyFields.has(key);
+        return context.dirtyFields.size > 0;
+    },
+    getTable: () => config.table,
+    exists: () => context.exists(),
+    setExists: (nextExists) => {
+        context.setExists(nextExists);
+    },
+});
+const createLifecycleApi = (config, attrs, getDb, context) => ({
+    save: async () => performModelSave(context.getModel(), config, attrs, getDb, {
+        isExists: context.exists(),
+        setExists: context.setExists,
+        updateOriginal: context.setOriginal,
+        clearDirty: () => context.dirtyFields.clear(),
+        getDirtyFields: () => [...context.dirtyFields],
+        getOriginal: context.getOriginal,
+    }),
+    delete: async () => performModelDelete(context.getModel(), config, getDb, context.exists()),
+    restore: async () => {
+        if (config.softDeletes !== true || !context.exists())
+            return false;
+        await Promise.resolve();
+        const deleteAtColumn = config.deleteAtColumn ?? 'deleted_at';
+        attrs[deleteAtColumn] = null;
+        context.dirtyFields.add(deleteAtColumn);
+        return true;
+    },
+    forceDelete: async () => {
+        if (!context.exists())
+            return false;
+        const model = context.getModel();
+        await runObservers(config, 'deleting', model);
+        emitTraceModelEvent('delete', config, attrs);
+        await runObservers(config, 'deleted', model);
+        return true;
+    },
+    isDeleted: () => {
+        if (config.softDeletes !== true)
+            return false;
+        const deleteAtColumn = config.deleteAtColumn ?? 'deleted_at';
+        const deletedValue = attrs[deleteAtColumn];
+        return deletedValue !== null && deletedValue !== undefined;
+    },
+});
+const defineReadableProperty = (model, config, attrs, relations, key) => {
+    if (key.length === 0 || key in model) {
+        return;
+    }
+    Object.defineProperty(model, key, {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+            if (relations[key] !== undefined) {
+                return relations[key];
+            }
+            return applyAccessor(config, key, attrs);
+        },
+        set: (value) => {
+            if (relations[key] !== undefined) {
+                relations[key] = value;
+                return;
+            }
+            model.setAttribute(key, value);
+        },
+    });
+};
+/**
+ * Create a new model instance
+ */
+export const createModel = (config, attributes = {}, options) => {
+    const connection = config.connection ?? DEFAULTS.CONNECTION;
+    const getDb = () => useDatabase(undefined, connection);
+    const attrs = {};
+    const relations = {}; // Store eager loaded relations
+    let original = {};
+    let isExists = options?.exists === true;
+    const dirtyFields = new Set();
+    if (options?.hydrate === true) {
+        hydrateAttributes(config, attrs, attributes);
+    }
+    else {
+        fillAttributes(config, attrs, attributes);
+    }
+    original = { ...attrs };
+    let modelApi = {};
+    const syncReadableProperty = (key) => {
+        if (key in attrs || key in relations) {
+            defineReadableProperty(modelApi, config, attrs, relations, key);
+        }
+    };
+    modelApi = {
+        ...createAttributeApi(config, attrs, relations, {
+            dirtyFields,
+            getModel: () => modelApi,
+            getOriginal: () => original,
+            exists: () => isExists,
+            setExists: (exists) => {
+                isExists = exists;
+            },
+            syncReadableProperty,
+        }),
+        ...createLifecycleApi(config, attrs, getDb, {
+            dirtyFields,
+            getModel: () => modelApi,
+            exists: () => isExists,
+            setExists: (exists) => {
+                isExists = exists;
+            },
+            setOriginal: (value) => {
+                original = value;
+            },
+            getOriginal: () => original,
+        }),
+    };
+    Object.assign(modelApi, createModelRelationships(config));
+    Object.keys(attrs).forEach(syncReadableProperty);
+    return modelApi;
+};
+const createPersistedModel = async (config, attributes = {}) => {
+    const model = createModel(config, attributes);
+    await model.save();
+    return model;
+};
+/**
+ * Get a query builder for a table
+ */
+export const query = (table, connection) => {
+    const db = useDatabase(undefined, connection ?? DEFAULTS.CONNECTION);
+    return QueryBuilder.create(table, db);
+};
+const buildSoftDeleteOptions = (config) => {
+    if (config.softDeletes !== true)
+        return undefined;
+    return { softDeleteColumn: 'deleted_at', softDeleteMode: 'exclude' };
+};
+/**
+ * Find a model by ID
+ */
+export const find = async (config, id) => {
+    const db = useDatabase(undefined, config.connection ?? DEFAULTS.CONNECTION);
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
+    builder.where('id', '=', String(id)).limit(1);
+    const result = await builder.first();
+    if (result === null)
+        return null;
+    return createModel(config, result, { hydrate: true, exists: true });
+};
+/**
+ * Get all records for a model
+ */
+export const all = async (config) => {
+    const db = useDatabase(undefined, config.connection ?? DEFAULTS.CONNECTION);
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
+    const results = await builder.get();
+    return results.map((result) => createModel(config, result, { hydrate: true, exists: true }));
+};
+const bindUnboundMethods = (model, methods) => {
+    const bound = {};
+    for (const [name, method] of Object.entries(methods)) {
+        bound[name] = (...args) => method(model, ...args);
+    }
+    return bound;
+};
+const extendModel = (model, methods) => {
+    const extended = Object.create(model);
+    for (const [name, method] of Object.entries(methods)) {
+        extended[name] = method;
+    }
+    return extended;
+};
+const isRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const isRelationship = (value) => {
+    if (!isRecord(value))
+        return false;
+    return 'type' in value && 'get' in value;
+};
+const createModelBuilder = (cfg) => {
+    const db = useDatabase(undefined, cfg.connection ?? DEFAULTS.CONNECTION);
+    return QueryBuilder.create(cfg.table, db, buildSoftDeleteOptions(cfg));
+};
+const createHydrator = (cfg, attach) => {
+    return (attributes) => {
+        if (isHydratedModelInstance(attributes)) {
+            return attributes;
+        }
+        const model = createModel(cfg, attributes, { hydrate: true, exists: true });
+        return attach(model);
+    };
+};
+const createRelationBootstrapContext = (cfg, relationName) => ({
+    modelTable: cfg.table,
+    relationName,
+});
+const logRelationBootstrapProbe = (debugRelationBootstrap, table, relationName) => {
+    if (debugRelationBootstrap) {
+        Logger.info(`[ORM] Relation bootstrap probing ${table}.${relationName}`);
+    }
+};
+const logRelationBootstrapResolved = (debugRelationBootstrap, table, relationName) => {
+    if (debugRelationBootstrap) {
+        Logger.info(`[ORM] Relation bootstrap resolved relationship ${table}.${relationName}`);
+    }
+};
+const logRelationBootstrapIgnored = (debugRelationBootstrap, table, relationName) => {
+    if (debugRelationBootstrap) {
+        Logger.info(`[ORM] Relation bootstrap ignored non-relationship ${table}.${relationName}`);
+    }
+};
+const logRelationBootstrapThrown = (debugRelationBootstrap, table, relationName, error) => {
+    if (debugRelationBootstrap) {
+        Logger.warn(`[ORM] Relation bootstrap probe threw for ${table}.${relationName}`, error);
+    }
+};
+const processRelationProbe = (cfg, relationName, fn, debugRelationBootstrap) => {
+    const relationContext = createRelationBootstrapContext(cfg, relationName);
+    try {
+        logRelationBootstrapProbe(debugRelationBootstrap, cfg.table, relationName);
+        const result = RelationBootstrapDiagnostics.withContext(relationContext, () => fn());
+        if (!isRelationship(result)) {
+            logRelationBootstrapIgnored(debugRelationBootstrap, cfg.table, relationName);
+            return { kind: 'ignored' };
+        }
+        logRelationBootstrapResolved(debugRelationBootstrap, cfg.table, relationName);
+        return { kind: 'relationship', relation: result };
+    }
+    catch (error) {
+        if (RelationBootstrapDiagnostics.isDatabaseRegistrationFailure(error)) {
+            return {
+                kind: 'failure',
+                failure: RelationBootstrapDiagnostics.createFailure(relationContext, error),
+            };
+        }
+        logRelationBootstrapThrown(debugRelationBootstrap, cfg.table, relationName, error);
+        return { kind: 'ignored' };
+    }
+};
+const createRelationMapping = (cfg, resolveMethods) => {
+    const dummyModel = createModel(cfg);
+    const methods = resolveMethods(dummyModel);
+    const debugRelationBootstrap = RelationBootstrapDiagnostics.isDebugEnabled();
+    const relationMapping = {};
+    const relationBootstrapFailures = [];
+    for (const [name, fn] of Object.entries(methods)) {
+        const outcome = processRelationProbe(cfg, name, fn, debugRelationBootstrap);
+        if (outcome.kind === 'relationship') {
+            relationMapping[name] = outcome.relation;
+            continue;
+        }
+        if (outcome.kind === 'failure') {
+            relationBootstrapFailures.push(outcome.failure);
+        }
+    }
+    if (relationBootstrapFailures.length > 0) {
+        Logger.warn(RelationBootstrapDiagnostics.formatFailureSummary(relationBootstrapFailures));
+    }
+    return relationMapping;
+};
+const hydrateRows = (raw, hydrateModel) => {
+    if (!Array.isArray(raw))
+        return null;
+    const rows = raw.filter((element) => isRecord(element));
+    return rows.map((element) => hydrateModel(element));
+};
+const loadEagerRelations = async (eagerBuilder, models) => {
+    const eagerLoads = typeof eagerBuilder.getEagerLoads === 'function' ? eagerBuilder.getEagerLoads() : undefined;
+    const eagerLoadConstraints = typeof eagerBuilder.getEagerLoadConstraints === 'function'
+        ? eagerBuilder.getEagerLoadConstraints()
+        : undefined;
+    if (!Array.isArray(eagerLoads) ||
+        eagerLoads.length === 0 ||
+        typeof eagerBuilder.load !== 'function' ||
+        models.length === 0) {
+        return;
+    }
+    await Promise.all(eagerLoads.map(async (relation) => {
+        const constraint = eagerLoadConstraints?.[relation];
+        await eagerBuilder.load?.(models, relation, constraint);
+    }));
+};
+const loadEagerCounts = async (eagerBuilder, models) => {
+    const eagerLoadCounts = typeof eagerBuilder.getEagerLoadCounts === 'function'
+        ? eagerBuilder.getEagerLoadCounts()
+        : undefined;
+    if (!Array.isArray(eagerLoadCounts) ||
+        eagerLoadCounts.length === 0 ||
+        typeof eagerBuilder.loadCount !== 'function' ||
+        models.length === 0) {
+        return;
+    }
+    await Promise.all(eagerLoadCounts.map(async (relation) => eagerBuilder.loadCount?.(models, relation)));
+};
+const hydrateAndLoadRelations = async (raw, eagerBuilder, hydrateModel) => {
+    const models = hydrateRows(raw, hydrateModel);
+    if (!models)
+        return raw;
+    await loadEagerRelations(eagerBuilder, models);
+    await loadEagerCounts(eagerBuilder, models);
+    return models;
+};
+const hydrateOneAndLoadRelations = async (raw, eagerBuilder, hydrateModel) => {
+    if (!isRecord(raw))
+        return raw;
+    const model = hydrateModel(raw);
+    await loadEagerRelations(eagerBuilder, [model]);
+    await loadEagerCounts(eagerBuilder, [model]);
+    return model;
+};
+const wrapBuilderGetForEagerLoading = (builder, hydrateModel) => {
+    const eagerBuilder = builder;
+    if (typeof eagerBuilder.first === 'function') {
+        const originalFirst = eagerBuilder.first.bind(builder);
+        eagerBuilder.first = async () => {
+            const raw = await originalFirst();
+            return hydrateOneAndLoadRelations(raw, eagerBuilder, hydrateModel);
+        };
+    }
+    if (typeof eagerBuilder.firstOrFail === 'function') {
+        const originalFirstOrFail = eagerBuilder.firstOrFail.bind(builder);
+        eagerBuilder.firstOrFail = async (message) => {
+            const raw = await originalFirstOrFail(message);
+            return hydrateOneAndLoadRelations(raw, eagerBuilder, hydrateModel);
+        };
+    }
+    const originalGet = eagerBuilder.get.bind(builder);
+    eagerBuilder.get = async () => {
+        const raw = await originalGet();
+        return hydrateAndLoadRelations(raw, eagerBuilder, hydrateModel);
+    };
+    if (typeof eagerBuilder.paginate === 'function') {
+        const originalPaginate = eagerBuilder.paginate.bind(builder);
+        eagerBuilder.paginate = async (page, perPage, options) => {
+            const result = await originalPaginate(page, perPage, options);
+            if (!Array.isArray(result.items))
+                return result;
+            const models = await hydrateAndLoadRelations(result.items, eagerBuilder, hydrateModel);
+            if (!Array.isArray(models))
+                return result;
+            return {
+                ...result,
+                items: models,
+            };
+        };
+    }
+};
+const createQueryBuilderMethods = (cfg, hydrateModel) => {
+    const wrappedBuilder = () => {
+        const builder = createModelBuilder(cfg);
+        wrapBuilderGetForEagerLoading(builder, hydrateModel);
+        return builder;
+    };
+    return {
+        query: () => wrappedBuilder(),
+        paginate: async (page, perPage, options) => wrappedBuilder().paginate(page, perPage, options),
+        where: (column, operator, value) => wrappedBuilder().where(column, operator, value),
+        andWhere: (column, operator, value) => wrappedBuilder().andWhere(column, operator, value),
+        orWhere: (column, operator, value) => wrappedBuilder().orWhere(column, operator, value),
+        whereGroup: (callback) => wrappedBuilder().whereGroup(callback),
+        orWhereGroup: (callback) => wrappedBuilder().orWhereGroup(callback),
+        whereNormalized: (column, value, options) => wrappedBuilder().whereNormalized(column, value, options),
+        orWhereNormalized: (column, value, options) => wrappedBuilder().orWhereNormalized(column, value, options),
+        whereNull: (column) => wrappedBuilder().whereNull(column),
+        whereNotNull: (column) => wrappedBuilder().whereNotNull(column),
+        whereIn: (column, values) => wrappedBuilder().whereIn(column, values),
+        whereNotIn: (column, values) => wrappedBuilder().whereNotIn(column, values),
+        whereMatch: (column, matchQuery) => wrappedBuilder().whereMatch(column, matchQuery),
+        whereNotMatch: (column, matchQuery) => wrappedBuilder().whereNotMatch(column, matchQuery),
+        whereColumn: (left, operator, right) => wrappedBuilder().whereColumn(left, operator, right),
+        whereExists: (callback) => wrappedBuilder().whereExists(callback),
+        whereNotExists: (callback) => wrappedBuilder().whereNotExists(callback),
+        from: (table) => wrappedBuilder().from(table),
+        select: (...columns) => wrappedBuilder().select(...columns),
+        selectAs: (column, alias) => wrappedBuilder().selectAs(column, alias),
+        max: (column, alias) => wrappedBuilder().max(column, alias),
+        join: (table, on) => wrappedBuilder().join(table, on),
+        leftJoin: (table, on) => wrappedBuilder().leftJoin(table, on),
+        groupBy: (...columns) => wrappedBuilder().groupBy(...columns),
+        latestPer: (partitionBy, options) => wrappedBuilder().latestPer(partitionBy, options),
+        orderBy: (column, direction) => wrappedBuilder().orderBy(column, direction),
+        inRandomOrder: () => wrappedBuilder().inRandomOrder(),
+        limit: (count) => wrappedBuilder().limit(count),
+        offset: (count) => wrappedBuilder().offset(count),
+        withTrashed: () => wrappedBuilder().withTrashed(),
+        onlyTrashed: () => wrappedBuilder().onlyTrashed(),
+        withoutTrashed: () => wrappedBuilder().withoutTrashed(),
+        scope: (name, ...args) => {
+            const fn = cfg.scopes?.[name];
+            if (typeof fn !== 'function') {
+                throw ErrorFactory.createConfigError(`Unknown query scope: ${name}`);
+            }
+            const builder = createModelBuilder(cfg);
+            return fn(builder, ...args);
+        },
+        with: (relations) => {
+            const builder = wrappedBuilder();
+            if (Array.isArray(relations)) {
+                relations.forEach((r) => builder.with(r));
+                return builder;
+            }
+            return builder.with(relations);
+        },
+        getTable: () => cfg.table,
+    };
+};
+const createDefinedModelInternal = (cfg, methodsOrPlan, attach, resolveMethods) => {
+    const relationMapping = createRelationMapping(cfg, resolveMethods);
+    const hydrateModel = createHydrator(cfg, attach);
+    const makeModel = (attributes = {}) => attach(createModel(cfg, attributes));
+    return {
+        create: async (attributes = {}) => {
+            const model = makeModel(attributes);
+            await model.save();
+            return model;
+        },
+        make: (attributes = {}) => makeModel(attributes),
+        new: (attributes = {}) => makeModel(attributes),
+        hydrate: (attributes) => hydrateModel(attributes),
+        find: async (id) => {
+            const model = await find(cfg, id);
+            return model === null ? null : attach(model);
+        },
+        all: async () => {
+            const models = await all(cfg);
+            return models.map((m) => attach(m));
+        },
+        raw: async () => {
+            const builder = createModelBuilder(cfg);
+            return builder.get();
+        },
+        ...createQueryBuilderMethods(cfg, hydrateModel),
+        db: (connection) => createDefinedModelInternal({ ...cfg, connection }, methodsOrPlan, attach, resolveMethods),
+        hydrateWithRelations(attributes, related) {
+            const model = hydrateModel(attributes);
+            for (const [name, data] of Object.entries(related)) {
+                const rel = relationMapping[name];
+                if (rel === undefined)
+                    continue;
+                const relatedStatic = rel.related;
+                const hydrate = relatedStatic.hydrate;
+                if (typeof hydrate !== 'function')
+                    continue;
+                if (Array.isArray(data)) {
+                    const relatedModels = data.filter((element) => isRecord(element)).map((d) => hydrate(d));
+                    model.setRelation(name, relatedModels);
+                    continue;
+                }
+                if (data !== null && data !== undefined && isRecord(data)) {
+                    const relatedModel = hydrate(data);
+                    model.setRelation(name, relatedModel);
+                }
+            }
+            return model;
+        },
+    };
+};
+export function define(config, methodsOrPlan) {
+    const normalizedConfig = normalizeModelConfig(config);
+    const plan = typeof methodsOrPlan === 'function' ? methodsOrPlan : undefined;
+    const unboundMethods = typeof methodsOrPlan === 'function' ? undefined : methodsOrPlan;
+    const resolveMethods = (model) => {
+        return plan ? plan(model) : bindUnboundMethods(model, unboundMethods ?? {});
+    };
+    const attach = (model) => {
+        const methods = resolveMethods(model);
+        return extendModel(model, methods);
+    };
+    return createDefinedModelInternal(normalizedConfig, methodsOrPlan, attach, resolveMethods);
+}
+/**
+ * Insert a single or multiple records into the database
+ * Returns insert metadata including ID and affected rows
+ */
+const insert = async (config, values) => {
+    const db = useDatabase(undefined, config.connection ?? DEFAULTS.CONNECTION);
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
+    return builder.insert(values);
+};
+/**
+ * Batch insert multiple records (alias for insert with array)
+ */
+const bulkInsert = async (config, records) => {
+    return insert(config, records);
+};
+/**
+ * Model namespace - sealed namespace object grouping all model operations
+ * Frozen to prevent accidental mutation
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export const Model = Object.freeze({
+    create: createPersistedModel,
+    make: createModel,
+    new: createModel,
+    query,
+    find,
+    all,
+    insert,
+    bulkInsert,
+    define,
+    primaryKey: ModelPrimaryKey,
+});