ts-prorm-orm 1.1.0 → 1.2.1

package/dist/prorm.js

@@ -60,7 +60,13 @@ const hana_1 = require("./dialects/hana");
 const spanner_1 = require("./dialects/spanner");
 const connection_pool_1 = require("./connection-pool");
 const models_1 = require("./models");
+const eager_load_1 = require("./models/eager-load");
 const decorators_1 = require("./models/decorators");
+const view_1 = require("./decorators/view");
+const view_2 = require("./decorators/view");
+const trigger_1 = require("./decorators/trigger");
+const procedure_1 = require("./decorators/procedure");
+const external_fields_1 = require("./external-fields");
 const logging_1 = require("./logging");
 const utils_1 = require("./errors/utils");
 const validator_1 = require("./validators/validator");
@@ -455,6 +461,67 @@ function resolveModelPrimaryKeyAttr(m) {
     }
     return 'id';
 }
+/**
+ * Derive a model's table name from its name and options.
+ *
+ * This is the single definition of that rule. It previously existed in six
+ * places, two of which (`syncCreate` and the table-name resolver) omitted the
+ * pluralization entirely and returned the bare model name - so `define('User')`
+ * followed by a plain `sync()` looked for a table called `User`, never found the
+ * `users` table that `define()` had already created, and created a second empty
+ * table beside it on every call. `syncForce`/`syncAlter` used the correct form,
+ * which is why the bug was invisible to anyone testing with `{ force: true }`.
+ */
+function deriveTableName(modelName, options) {
+    if (options?.tableName)
+        return options.tableName;
+    return options?.freezeTableName ? modelName : (0, utils_2.pluralize)(modelName.toLowerCase());
+}
+/**
+ * Resolve the column type a synthesized foreign key should use so that it
+ * matches the column it references.
+ *
+ * A foreign key column must be type-compatible with its referenced key. This
+ * used to be hardcoded to INTEGER, which meant any model with a UUID or STRING
+ * primary key produced a child column that Postgres rejects outright at CREATE
+ * TABLE (`foreign key constraint cannot be implemented`) and SQLite accepts
+ * while silently coercing the stored values.
+ *
+ * Auto-increment types are mapped to their referenceable equivalent - a column
+ * pointing at a SERIAL key is an INTEGER, not another SERIAL.
+ */
+function resolveForeignKeyColumnType(refModel, refField) {
+    const attrs = refModel?.rawAttributes || refModel?.attributes;
+    const attr = attrs?.[refField];
+    // Unwrap the several shapes an attribute can take: `{ type: X }`, a DataType
+    // instance, or a bare factory function.
+    let type = attr && typeof attr === 'object' && 'type' in attr ? attr.type : attr;
+    if (typeof type === 'function') {
+        try {
+            const built = type();
+            if (built && typeof built === 'object')
+                type = built;
+        }
+        catch {
+            type = undefined;
+        }
+    }
+    const key = String(type?.key ?? type?.toString?.() ?? type ?? '').toUpperCase();
+    if (!key || key === 'UNDEFINED') {
+        return 'INTEGER';
+    }
+    // A reference to an auto-incrementing key is a plain integer of matching width.
+    if (key.startsWith('BIGSERIAL'))
+        return 'BIGINT';
+    if (key.startsWith('SMALLSERIAL'))
+        return 'SMALLINT';
+    if (key.startsWith('SERIAL'))
+        return 'INTEGER';
+    if (attr?.autoIncrement && key.startsWith('INTEGER'))
+        return 'INTEGER';
+    // Otherwise mirror the referenced column's own type (UUID, STRING(n), BIGINT, ...).
+    return (type ?? 'INTEGER');
+}
 // Tracks (via Node's AsyncLocalStorage, which correctly follows a logical
 // call chain across `await`s regardless of how concurrent operations
 // interleave) whether the currently-executing code is running inside an
@@ -556,6 +623,20 @@ class Prorm extends events_1.EventEmitter {
         this._rootTransactionQueue = Promise.resolve();
         this.modelDefinitions = new Map();
         this.associations = new Map();
+        /**
+         * Decorator-declared associations waiting for their target model to be
+         * registered. See `_flushPendingAssociations()`.
+         */
+        this._pendingAssociations = [];
+        /** Model classes registered via `addModel`, consulted for @View/@Trigger DDL. */
+        this._decoratedClasses = [];
+        /** Classes registered via `registerProcedures`, for @Procedure/@SqlFunction DDL. */
+        this._procedureClasses = [];
+        /**
+         * Object/key-value stores backing @ExternalField properties. Public so the
+         * instance accessors built in `_wrapInstance` can resolve them.
+         */
+        this.externalStores = new external_fields_1.ExternalStoreRegistry();
         // Tracks the fire-and-forget auto-create-table promises kicked off by
         // `define()` (see below). `sync()` awaits these before doing its own
         // drop/create pass so that a `define()` call followed synchronously by
@@ -1401,7 +1482,7 @@ class Prorm extends events_1.EventEmitter {
             }
             throw new Error(`Model '${modelName}' not found`);
         }
-        const tableName = modelDef.options.tableName || modelName;
+        const tableName = deriveTableName(modelName, modelDef.options);
         const schema = modelDef.options.schema;
         const schemaDelimiter = modelDef.options.schemaDelimiter || '.';
         return schema ? `${schema}${schemaDelimiter}${tableName}` : tableName;
@@ -1549,7 +1630,7 @@ class Prorm extends events_1.EventEmitter {
         // Store the model definition
         this.modelDefinitions.set(modelName, { attributes, options });
         // Determine table name and schema
-        const tableName = options.tableName || (options.freezeTableName ? modelName : (0, utils_2.pluralize)(modelName.toLowerCase()));
+        const tableName = deriveTableName(modelName, options);
         const schema = options.schema;
         const schemaDelimiter = options.schemaDelimiter || '.';
         // Build the full table name with schema (e.g., "schema.tableName" or "database.table")
@@ -1871,6 +1952,14 @@ class Prorm extends events_1.EventEmitter {
                         'save',
                         'destroy',
                         'isNewRecord',
+                        // Bookkeeping properties, not columns. These are enumerable own
+                        // properties of the instance, so without them here the sweep below
+                        // put them in the UPDATE and every
+                        // `instance.field = x; await instance.save()` failed with
+                        // "no such column: _previousDataValues". Any future underscore-
+                        // prefixed internal is excluded by the check in the loop too.
+                        '_previousDataValues',
+                        '_changed',
                     ]);
                     if (pk !== undefined) {
                         const saveVals = {};
@@ -1878,6 +1967,8 @@ class Prorm extends events_1.EventEmitter {
                         for (const k of Object.keys(rowInstance)) {
                             if (reserved.has(k))
                                 continue;
+                            if (k.startsWith('_'))
+                                continue; // internal bookkeeping, not a column
                             if (typeof rowInstance[k] === 'function')
                                 continue;
                             if (k !== 'id') {
@@ -1885,8 +1976,11 @@ class Prorm extends events_1.EventEmitter {
                                 dataValues[k] = rowInstance[k];
                             }
                         }
-                        // Also include current dataValues (minus id, minus virtual fields)
+                        // Also include current dataValues (minus id, minus virtual fields,
+                        // minus @ExternalField payloads which live in a store, not a column)
                         for (const [k, v] of Object.entries(dataValues)) {
+                            if (rowInstance.__externalFields?.has(k))
+                                continue;
                             if (k !== 'id' && !reserved.has(k)) {
                                 const attr = attributes[k];
                                 if (attr) {
@@ -2162,7 +2256,10 @@ class Prorm extends events_1.EventEmitter {
                 const sourceMatch = assoc.source === modelRef || assoc.source?.name === modelName;
                 if (!sourceMatch)
                     continue;
-                const assocAlias = assoc.options?.as || assoc.target?.name || '';
+                // Prefer the association's resolved alias, which is what the
+                // eager-loader attaches results under, so `user.getPosts()` and
+                // `include: [Post]` agree on the name.
+                const assocAlias = assoc.as || assoc.options?.as || assoc.target?.name || '';
                 const singularAlias = assocAlias.endsWith('s') ? assocAlias.slice(0, -1) : assocAlias;
                 const pluralAlias = assocAlias.endsWith('s') ? assocAlias : assocAlias + 's';
                 const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
@@ -2172,7 +2269,13 @@ class Prorm extends events_1.EventEmitter {
                         const { where: optWhere, ...rest } = opts || {};
                         return assoc.target.findAll({
                             ...rest,
-                            where: { [fk]: dataValues.id, ...(optWhere || {}) },
+                            // An association `scope` applies every time the association is
+                            // traversed; a caller-supplied where can narrow it further.
+                            where: {
+                                ...(assoc.options?.scope || {}),
+                                [fk]: dataValues.id,
+                                ...(optWhere || {}),
+                            },
                         });
                     };
                     rowInstance[`add${capitalize(singularAlias)}`] = async (instance) => {
@@ -2239,16 +2342,56 @@ class Prorm extends events_1.EventEmitter {
                         rowInstance[fk] = targetId;
                         await modelRef.update({ [fk]: targetId }, { where: { id: dataValues.id } });
                     };
+                    // create/has/count were missing here while the equivalent mixins in
+                    // models/associations.ts defined them, so which helpers existed on an
+                    // instance depended on how the model had been defined.
+                    rowInstance[`create${capitalize(assocAlias)}`] = async (values, options) => {
+                        const created = await assoc.target.create(values, options);
+                        const targetId = created?.id ?? created;
+                        dataValues[fk] = targetId;
+                        rowInstance[fk] = targetId;
+                        await modelRef.update({ [fk]: targetId }, { where: { id: dataValues.id } });
+                        return created;
+                    };
+                    rowInstance[`has${capitalize(assocAlias)}`] = async () => {
+                        const fkVal = dataValues[fk];
+                        if (fkVal === null || fkVal === undefined)
+                            return false;
+                        return (await assoc.target.count({ where: { id: fkVal } })) > 0;
+                    };
+                    rowInstance[`count${capitalize(assocAlias)}`] = async () => {
+                        const fkVal = dataValues[fk];
+                        if (fkVal === null || fkVal === undefined)
+                            return 0;
+                        return assoc.target.count({ where: { id: fkVal } });
+                    };
                 }
                 else if (assoc.type === 'hasOne') {
                     const fk = assoc.foreignKey;
                     rowInstance[`get${capitalize(assocAlias)}`] = async (opts) => {
-                        return assoc.target.findOne({ where: { [fk]: dataValues.id }, ...(opts || {}) });
+                        const { where: optWhere, ...rest } = opts || {};
+                        return assoc.target.findOne({
+                            ...rest,
+                            where: {
+                                ...(assoc.options?.scope || {}),
+                                [fk]: dataValues.id,
+                                ...(optWhere || {}),
+                            },
+                        });
                     };
                     rowInstance[`set${capitalize(assocAlias)}`] = async (instance) => {
                         const targetId = instance?.id ?? instance;
                         await assoc.target.update({ [fk]: dataValues.id }, { where: { id: targetId } });
                     };
+                    rowInstance[`create${capitalize(assocAlias)}`] = async (values, options) => {
+                        return assoc.target.create({ ...values, [fk]: dataValues.id }, options);
+                    };
+                    rowInstance[`has${capitalize(assocAlias)}`] = async () => {
+                        return (await assoc.target.count({ where: { [fk]: dataValues.id } })) > 0;
+                    };
+                    rowInstance[`count${capitalize(assocAlias)}`] = async () => {
+                        return assoc.target.count({ where: { [fk]: dataValues.id } });
+                    };
                 }
                 else if (assoc.type === 'belongsToMany') {
                     const fk = assoc.options?.foreignKey || assoc.foreignKey;
@@ -2375,12 +2518,24 @@ class Prorm extends events_1.EventEmitter {
                             return true;
                         }
                     }
+                    // @ExternalField payloads are not columns - route the assignment to
+                    // the field's own accessor (which records it for the next save) and
+                    // keep it out of dataValues, which save() sweeps into the UPDATE.
+                    if (target.__externalFields?.has(prop)) {
+                        target[prop] = value;
+                        return true;
+                    }
                     // Regular field
                     dataValues[prop] = value;
                     target[prop] = value;
                     return true;
                 },
             });
+            // Attach @ExternalField accessors. These are defined on the underlying
+            // rowInstance (not the proxy) as non-enumerable properties, so save()'s
+            // sweep over the instance's own keys never tries to persist a payload
+            // into a column that doesn't exist - only the key column is written.
+            (0, external_fields_1.attachExternalFields)(rowInstance, dataValues, modelName, fullTableName, self.externalStores);
             return proxyInstance;
         };
         const model = {
@@ -2713,6 +2868,32 @@ class Prorm extends events_1.EventEmitter {
                         [deletedAt]: { $isNull: true },
                     };
                 }
+                // Apply INNER-JOIN semantics for filtering includes.
+                //
+                // `include: [{ model: Post, required: true }]` and an include carrying
+                // its own `where` are documented to restrict the parent rows. That was
+                // never implemented - `required` was read by no live code path, so these
+                // queries returned every parent regardless. Resolve the matching parent
+                // keys first and constrain the main query with them, so the restriction
+                // is applied before LIMIT/OFFSET rather than after.
+                if (findOptions.include && findOptions.include.length > 0) {
+                    for (const rawInclude of findOptions.include) {
+                        const filter = await (0, eager_load_1.resolveRequiredIncludeFilter)(self.eagerLoadContext(), model, modelName, rawInclude);
+                        if (!filter)
+                            continue;
+                        if (filter.values.length === 0) {
+                            // No parent can satisfy a required include with no matches.
+                            return [];
+                        }
+                        const existing = where?.[filter.parentAttr];
+                        where = {
+                            ...where,
+                            [filter.parentAttr]: existing
+                                ? { $and: [existing, { $in: filter.values }] }
+                                : { $in: filter.values },
+                        };
+                    }
+                }
                 // Translate attributes.exclude to explicit list (SQLite doesn't support "* EXCEPT(...)")
                 let resolvedAttributes = findOptions.attributes;
                 if (resolvedAttributes &&
@@ -2791,232 +2972,12 @@ class Prorm extends events_1.EventEmitter {
                 const wrappedRows = result.rows.map((row) => {
                     return _wrapInstance(row, modelRef, modelHooksRef);
                 });
-                // Handle includes (associations) by doing separate queries and attaching results.
-                // This recurses into nested `include` entries so `include: [{ model: A, include: [{ model: B }] }]`
-                // eager-loads grandchild-level data as well (fetched rows for A become the new "parent" rows for B).
-                const loadIncludesRecursive = async (parentRows, parentModel, parentModelName, includeList) => {
-                    for (const rawIncludeOpt of includeList) {
-                        // Support both the object form (`{ model: Post, as: 'posts' }`) and
-                        // the bare-model shorthand (`Post`) used throughout the test suite
-                        // and docs (e.g. `findAll({ include: [Post] })`). A bare model has
-                        // no `.model` property of its own but does carry `.rawAttributes`/
-                        // `.tableName`, so detect that shape and wrap it before use -
-                        // otherwise `includeModel` was always undefined for the shorthand
-                        // form and the include was silently skipped.
-                        const includeOpt = rawIncludeOpt && !rawIncludeOpt.model && rawIncludeOpt.rawAttributes
-                            ? { model: rawIncludeOpt }
-                            : rawIncludeOpt;
-                        const includeModel = includeOpt.model;
-                        if (!includeModel)
-                            continue;
-                        // Find the association definition to get the foreign key (and, for
-                        // belongsToMany, the junction table info).
-                        let foreignKey;
-                        let associationType;
-                        let assocOtherKey;
-                        let assocThrough;
-                        let assocThroughModel;
-                        let assocAs;
-                        for (const [, assoc] of self.associations.entries()) {
-                            const sourceMatch = assoc.source === parentModel || assoc.source?.name === parentModelName;
-                            const targetMatch = assoc.target === includeModel || assoc.target?.name === includeModel.name;
-                            const aliasMatch = !includeOpt.as || assoc.options?.as === includeOpt.as;
-                            if (sourceMatch && targetMatch && aliasMatch) {
-                                foreignKey = assoc.foreignKey;
-                                associationType = assoc.type;
-                                assocOtherKey = assoc.otherKey;
-                                assocThrough = assoc.through;
-                                assocThroughModel = assoc.throughModel;
-                                assocAs = assoc.as;
-                                break;
-                            }
-                            // Also check reverse (belongsTo) - check alias match too
-                            const revSourceMatch = assoc.source === includeModel || assoc.source?.name === includeModel.name;
-                            const revTargetMatch = assoc.target === parentModel || assoc.target?.name === parentModelName;
-                            const revAliasMatch = !includeOpt.as || assoc.options?.as === includeOpt.as;
-                            if (revSourceMatch && revTargetMatch && revAliasMatch) {
-                                foreignKey = assoc.foreignKey;
-                                associationType = assoc.type;
-                                assocOtherKey = assoc.otherKey;
-                                assocThrough = assoc.through;
-                                assocThroughModel = assoc.throughModel;
-                                assocAs = assoc.as;
-                                break;
-                            }
-                        }
-                        // Prefer the association's own default alias (e.g. `user` for a
-                        // singular belongsTo/hasOne, `posts` for a plural hasMany) over
-                        // the raw table name - using the table name here meant an
-                        // unaliased `include: [User]` populated `row.users` instead of
-                        // the expected `row.user`, silently breaking any include that
-                        // didn't pass an explicit `as`.
-                        const includeAlias = includeOpt.as || assocAs || includeModel.tableName || includeModel.name;
-                        // Resolve the actual primary-key attribute for each side of the association
-                        // (instead of assuming 'id'), since custom primary keys may differ per model.
-                        const sourcePkAttr = resolveModelPrimaryKeyAttr(parentModel);
-                        const targetPkAttr = resolveModelPrimaryKeyAttr(includeModel);
-                        // Get primary keys from parent rows
-                        const mainPks = parentRows
-                            .map((r) => r[sourcePkAttr])
-                            .filter((v) => v !== undefined && v !== null);
-                        if (mainPks.length === 0)
-                            continue;
-                        // For hasMany/hasOne: foreignKey is on target table pointing to source's pk
-                        // For belongsTo: foreignKey is on source table pointing to target's pk
-                        // For belongsToMany: foreignKey is on the junction table pointing to source's pk
-                        if (!foreignKey) {
-                            // Try to infer foreign key from model name
-                            foreignKey = `${parentModelName.charAt(0).toLowerCase() + parentModelName.slice(1)}Id`;
-                        }
-                        let fetchedRows = [];
-                        try {
-                            const includeWhere = { ...includeOpt.where };
-                            if (associationType === 'belongsTo') {
-                                // foreignKey is on this model, not the target
-                                // The association goes: this.foreignKey references target's pk
-                                const fkValues = parentRows
-                                    .map((r) => r[foreignKey])
-                                    .filter((v) => v !== undefined && v !== null);
-                                if (fkValues.length === 0) {
-                                    for (const row of parentRows) {
-                                        row[includeAlias] = null;
-                                        if (row.dataValues)
-                                            row.dataValues[includeAlias] = null;
-                                    }
-                                    continue;
-                                }
-                                const targetRows = await includeModel.findAll({
-                                    where: { ...includeWhere, [targetPkAttr]: { $in: fkValues } },
-                                    ...(includeOpt.attributes ? { attributes: includeOpt.attributes } : {}),
-                                });
-                                fetchedRows = targetRows;
-                                const targetMap = new Map();
-                                for (const tr of targetRows) {
-                                    targetMap.set(tr[targetPkAttr], tr);
-                                }
-                                for (const row of parentRows) {
-                                    const fkVal = row[foreignKey];
-                                    const associated = fkVal !== undefined && fkVal !== null ? targetMap.get(fkVal) || null : null;
-                                    row[includeAlias] = associated;
-                                    if (row.dataValues)
-                                        row.dataValues[includeAlias] = associated;
-                                }
-                            }
-                            else if (associationType === 'belongsToMany') {
-                                // Many-to-many: the foreign key linking to the source lives on the junction
-                                // (through) table, not on the target table directly. Mirrors the logic used by
-                                // the row-instance `get<Alias>()` methods: find the through model, query junction
-                                // rows matching the parent rows' PKs, then query target rows by the resulting ids.
-                                let throughModel = assocThroughModel;
-                                if (!throughModel && assocThrough) {
-                                    for (const m of Object.values(self.models)) {
-                                        if (m.tableName === assocThrough ||
-                                            m.name === assocThrough) {
-                                            throughModel = m;
-                                            break;
-                                        }
-                                    }
-                                }
-                                if (!throughModel || typeof throughModel.findAll !== 'function') {
-                                    throw new Error(`Cannot resolve through model for belongsToMany include "${includeAlias}"`);
-                                }
-                                const otherKey = assocOtherKey || `${includeModel.name}Id`;
-                                const junctionRows = await throughModel.findAll({
-                                    where: { [foreignKey]: { $in: mainPks } },
-                                });
-                                const targetIdsBySource = new Map();
-                                const allTargetIds = [];
-                                for (const jr of junctionRows) {
-                                    const srcVal = jr[foreignKey];
-                                    const tgtVal = jr[otherKey];
-                                    if (tgtVal === undefined || tgtVal === null)
-                                        continue;
-                                    if (!targetIdsBySource.has(srcVal))
-                                        targetIdsBySource.set(srcVal, []);
-                                    targetIdsBySource.get(srcVal).push(tgtVal);
-                                    allTargetIds.push(tgtVal);
-                                }
-                                if (allTargetIds.length === 0) {
-                                    for (const row of parentRows) {
-                                        row[includeAlias] = [];
-                                        if (row.dataValues)
-                                            row.dataValues[includeAlias] = [];
-                                    }
-                                    continue;
-                                }
-                                const targetRows = await includeModel.findAll({
-                                    where: { ...includeWhere, [targetPkAttr]: { $in: allTargetIds } },
-                                    ...(includeOpt.attributes ? { attributes: includeOpt.attributes } : {}),
-                                    ...(includeOpt.order ? { order: includeOpt.order } : {}),
-                                });
-                                fetchedRows = targetRows;
-                                const targetMap = new Map();
-                                for (const tr of targetRows) {
-                                    targetMap.set(tr[targetPkAttr], tr);
-                                }
-                                for (const row of parentRows) {
-                                    const srcPk = row[sourcePkAttr];
-                                    const targetIds = targetIdsBySource.get(srcPk) || [];
-                                    const associated = targetIds
-                                        .map((tid) => targetMap.get(tid))
-                                        .filter((v) => v !== undefined);
-                                    row[includeAlias] = associated;
-                                    if (row.dataValues)
-                                        row.dataValues[includeAlias] = associated;
-                                }
-                            }
-                            else {
-                                // hasMany/hasOne: foreignKey is on target table
-                                if (includeOpt.where)
-                                    Object.assign(includeWhere, includeOpt.where);
-                                includeWhere[foreignKey] = { $in: mainPks };
-                                const assocRows = await includeModel.findAll({
-                                    where: includeWhere,
-                                    ...(includeOpt.attributes ? { attributes: includeOpt.attributes } : {}),
-                                    ...(includeOpt.order ? { order: includeOpt.order } : {}),
-                                });
-                                fetchedRows = assocRows;
-                                // Group by foreignKey value
-                                const groupedRows = new Map();
-                                for (const ar of assocRows) {
-                                    const fkVal = ar[foreignKey];
-                                    if (!groupedRows.has(fkVal))
-                                        groupedRows.set(fkVal, []);
-                                    groupedRows.get(fkVal).push(ar);
-                                }
-                                // Attach to parent rows
-                                for (const row of parentRows) {
-                                    const pk = row[sourcePkAttr];
-                                    const associated = groupedRows.get(pk) || [];
-                                    // For hasOne, use the first result or null
-                                    const attachValue = associationType === 'hasOne' ? associated[0] || null : associated;
-                                    row[includeAlias] = attachValue;
-                                    if (row.dataValues)
-                                        row.dataValues[includeAlias] = attachValue;
-                                }
-                            }
-                            // Recurse into nested includes, treating the just-fetched rows as the new
-                            // "parent" rows for the next level down.
-                            const nestedIncludes = includeOpt.include;
-                            if (nestedIncludes && nestedIncludes.length > 0 && fetchedRows.length > 0) {
-                                await loadIncludesRecursive(fetchedRows, includeModel, includeModel.name, nestedIncludes);
-                            }
-                        }
-                        catch {
-                            // If include query fails, set empty
-                            for (const row of parentRows) {
-                                if (row[includeAlias] === undefined) {
-                                    row[includeAlias] =
-                                        associationType === 'hasMany' || associationType === 'belongsToMany' ? [] : null;
-                                    if (row.dataValues)
-                                        row.dataValues[includeAlias] = row[includeAlias];
-                                }
-                            }
-                        }
-                    }
-                };
+                // Eager-load associations. The implementation is shared with the
+                // class-based Model API (see models/eager-load.ts) - it used to be
+                // duplicated here and in models/model.ts, and the two copies had
+                // drifted apart in how they handled belongsTo and belongsToMany.
                 if (findOptions.include && findOptions.include.length > 0) {
-                    await loadIncludesRecursive(wrappedRows, model, modelName, findOptions.include);
+                    await (0, eager_load_1.loadIncludes)(self.eagerLoadContext(), wrappedRows, model, modelName, findOptions.include);
                 }
                 return wrappedRows;
             },
@@ -3025,13 +2986,12 @@ class Prorm extends events_1.EventEmitter {
              */
             async findAndCountAll(findOptions = {}) {
                 const rows = await this.findAll(findOptions);
-                // Count all matching rows without limit/offset
-                const countOptions = {
-                    where: findOptions.where,
-                    paranoid: findOptions.paranoid,
-                };
-                const allRows = await this.findAll(countOptions);
-                const count = allRows.length;
+                // Count with an aggregate rather than by re-running the full query
+                // without a limit and measuring the array. `limit`/`offset` are dropped
+                // (the count describes the whole matching set), everything else that
+                // narrows the set - including filtering includes - is preserved.
+                const { limit: _limit, offset: _offset, ...countable } = this._mergeScopes(findOptions);
+                const count = await self._countRows(model, modelName, countable);
                 return { rows, count };
             },
             /**
@@ -3056,11 +3016,45 @@ class Prorm extends events_1.EventEmitter {
                 if (existing) {
                     return [existing, false];
                 }
-                const createValues = { ...findOptions.defaults, ...findOptions.where };
-                const created = await this.create(createValues, {
-                    transaction: findOptions.transaction,
-                });
-                return [created, true];
+                // Only equality conditions from `where` describe a row that can be
+                // created. Operator objects (`{ email: { $like: 'a%' } }`) used to be
+                // spread into the INSERT verbatim, which tried to store the operator
+                // object itself as the column value.
+                const equalityFromWhere = {};
+                for (const [key, value] of Object.entries((findOptions.where || {}))) {
+                    if (key.startsWith('$'))
+                        continue; // $and / $or / $not - not a column
+                    const isOperatorObject = value !== null &&
+                        typeof value === 'object' &&
+                        !(value instanceof Date) &&
+                        !Array.isArray(value) &&
+                        Object.keys(value).some((k) => k.startsWith('$'));
+                    if (!isOperatorObject)
+                        equalityFromWhere[key] = value;
+                }
+                const createValues = {
+                    ...findOptions.defaults,
+                    ...equalityFromWhere,
+                };
+                try {
+                    const created = await this.create(createValues, {
+                        transaction: findOptions.transaction,
+                    });
+                    return [created, true];
+                }
+                catch (error) {
+                    // The find and the create are two statements, so a concurrent caller
+                    // can insert between them. When the database rejects our insert on a
+                    // unique/primary key, the row we wanted now exists - return it rather
+                    // than surfacing a constraint error from an idempotent-looking call.
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (!/unique|duplicate|constraint/i.test(message))
+                        throw error;
+                    const raced = await this.findOne(findOptions);
+                    if (raced)
+                        return [raced, false];
+                    throw error;
+                }
             },
             /**
              * Find a record or build (但不保存) it if not found
@@ -3158,6 +3152,18 @@ class Prorm extends events_1.EventEmitter {
                 const validationErrors = [];
                 for (const [attrName, attr] of Object.entries(attributes)) {
                     const val = hookInstance[attrName];
+                    // An auto-increment key is assigned by the database on insert, so it
+                    // is legitimately absent here. Requiring it would make every
+                    // `@PrimaryKey @AutoIncrement` column reject its own INSERT.
+                    if ((val === undefined || val === null) && attr.autoIncrement)
+                        continue;
+                    // A column with a default (including a DB-side default) is likewise
+                    // allowed to be absent - the database supplies the value.
+                    if ((val === undefined || val === null) &&
+                        attr.defaultValue !== undefined &&
+                        attr.allowNull === false) {
+                        continue;
+                    }
                     // Check allowNull regardless of validate option
                     if ((val === undefined || val === null) && attr.allowNull === false) {
                         validationErrors.push({
@@ -3576,9 +3582,18 @@ class Prorm extends events_1.EventEmitter {
             /**
              * Count records
              */
+            /**
+             * Count matching rows with a real aggregate query.
+             *
+             * This used to delegate to `findAndCountAll`, which fetched every
+             * matching row (including eager-loading its associations) and returned
+             * `rows.length` - so counting a large table transferred the whole table,
+             * and `distinct`, `col` and `group` were silently discarded.
+             */
             async count(countOptions = {}) {
-                const result = await this.findAndCountAll(countOptions);
-                return result.count;
+                // Apply defaultScope / named scopes exactly as findAll does, so
+                // `User.scope('admin').count()` counts the scoped set.
+                return self._countRows(model, modelName, this._mergeScopes(countOptions));
             },
             /**
              * Truncate table
@@ -4208,31 +4223,28 @@ class Prorm extends events_1.EventEmitter {
         };
         // Call define to register the model
         const registeredModel = this.define(modelName, attributes, options);
-        // Apply associations declared via @HasOne/@HasMany/@BelongsTo/@BelongsToMany decorators
+        // Queue associations declared via @HasOne/@HasMany/@BelongsTo/@BelongsToMany.
+        //
+        // These are NOT bound immediately. `@BelongsTo(() => User)` uses a thunk so
+        // the reference survives a circular import, but binding used to happen right
+        // here - so if `Post` was added before `User`, the association bound against
+        // a class that had never been through `define()`: no `tableName`, no
+        // `rawAttributes`, and `createTableFromModel` then silently skipped the
+        // REFERENCES clause. Whether foreign keys were created depended on the order
+        // the model files happened to be imported in. Queue instead, and flush every
+        // association whose target is registered after each `addModel`.
         const assocMeta = (0, decorators_1.getAssociationMetadata)(modelName);
         if (assocMeta) {
             for (const assoc of assocMeta) {
-                const targetModel = assoc.target();
-                const assocOptions = {
-                    as: assoc.as,
-                    foreignKey: assoc.foreignKey,
-                    onDelete: assoc.onDelete,
-                    onUpdate: assoc.onUpdate,
-                    hooks: assoc.hooks,
-                };
-                if (assoc.type === 'hasOne' || assoc.type === 'hasMany') {
-                    assocOptions.sourceKey = assoc.sourceKey;
-                }
-                if (assoc.type === 'belongsTo') {
-                    assocOptions.targetKey = assoc.targetKey;
-                }
-                if (assoc.type === 'belongsToMany') {
-                    assocOptions.through = assoc.through;
-                    assocOptions.otherKey = assoc.otherKey;
-                }
-                registeredModel[assoc.type](targetModel, assocOptions);
+                this._pendingAssociations.push({ sourceName: modelName, source: registeredModel, assoc });
             }
         }
+        this._flushPendingAssociations();
+        // Remember the class so sync() can apply its @View / @MaterializedView /
+        // @Trigger annotations.
+        if (!this._decoratedClasses.includes(modelClass)) {
+            this._decoratedClasses.push(modelClass);
+        }
         // Replay any scopes queued on the class via addScope() before it was
         // registered (associations are replayed elsewhere; scopes were not).
         const pendingScopes = modelClass._pendingScopes;
@@ -4247,7 +4259,7 @@ class Prorm extends events_1.EventEmitter {
         Object.setPrototypeOf(modelClass, registeredModelObj);
         // Also ensure the original class has the right rawAttributes, tableName, and options
         modelClass.rawAttributes = attributes;
-        modelClass.tableName = options.tableName || (options.freezeTableName ? modelName : (0, utils_2.pluralize)(modelName.toLowerCase()));
+        modelClass.tableName = deriveTableName(modelName, options);
         modelClass.options = options;
         // Set the prorm reference
         modelClass.prorm = this;
@@ -4327,6 +4339,9 @@ class Prorm extends events_1.EventEmitter {
                 comment: attr?.comment,
             };
         }
+        // Composite foreign keys can't be expressed as an inline column REFERENCES,
+        // so they accumulate here and are merged into the table-level constraints below.
+        const synthesizedFkConstraints = [];
         // Wire up foreign-key constraints implied by hasOne/hasMany/belongsTo
         // associations declared on this or other models. Associations only add
         // runtime getter/setter/create helpers (see models/associations.ts) - they
@@ -4344,45 +4359,99 @@ class Prorm extends events_1.EventEmitter {
             for (const assoc of this.associations.values()) {
                 const assocAny = assoc;
                 const fk = assocAny.foreignKey;
-                if (typeof fk !== 'string')
-                    continue; // skip composite/array foreign keys
+                if (!fk)
+                    continue;
                 const sourceName = assocAny.source?.name;
                 const targetName = assocAny.target?.name;
+                // Which side of the association owns the foreign key column decides
+                // both the table it references and which option names the referenced key.
+                let refModel;
+                let refKeyOption;
                 if (assocAny.type === 'belongsTo' && sourceName === modelName) {
                     // FK column lives on this (source) table, referencing the target's table
-                    const refTable = assocAny.target?.tableName;
-                    if (refTable && !columns[fk]?.references) {
-                        columns[fk] = {
-                            ...(columns[fk] || { type: 'INTEGER', allowNull: true }),
-                            references: {
-                                table: refTable,
-                                field: assocAny.options?.targetKey || 'id',
-                                onDelete: assocAny.options?.onDelete,
-                                onUpdate: assocAny.options?.onUpdate,
-                            },
-                        };
-                    }
+                    refModel = assocAny.target;
+                    refKeyOption = assocAny.options?.targetKey;
                 }
                 else if ((assocAny.type === 'hasMany' || assocAny.type === 'hasOne') &&
                     targetName === modelName) {
                     // FK column lives on this (target) table, referencing the source's table
-                    const refTable = assocAny.source?.tableName;
-                    if (refTable && !columns[fk]?.references) {
-                        columns[fk] = {
-                            ...(columns[fk] || { type: 'INTEGER', allowNull: true }),
+                    refModel = assocAny.source;
+                    refKeyOption = assocAny.options?.sourceKey;
+                }
+                else {
+                    continue;
+                }
+                const refTable = refModel?.tableName;
+                if (!refTable)
+                    continue;
+                // Composite foreign keys (`foreignKey: ['orgId', 'userId']`) are a
+                // supported option shape and were previously dropped outright here, so
+                // they produced neither a column nor a constraint. Normalize both forms
+                // to arrays and pair each local column with its referenced key.
+                const fkCols = Array.isArray(fk) ? fk : [fk];
+                const refKeys = Array.isArray(refKeyOption)
+                    ? refKeyOption
+                    : refKeyOption
+                        ? [refKeyOption]
+                        : fkCols.length === 1
+                            ? [resolveModelPrimaryKeyAttr(refModel)]
+                            : [];
+                if (refKeys.length !== fkCols.length) {
+                    throw new errors_1.AssociationError(`${assocAny.type} association between ${sourceName} and ${targetName} declares ` +
+                        `${fkCols.length} foreign key column(s) (${fkCols.join(', ')}) but ` +
+                        `${refKeys.length} referenced key(s)` +
+                        (refKeys.length ? ` (${refKeys.join(', ')})` : '') +
+                        `. Pass a matching ${assocAny.type === 'belongsTo' ? 'targetKey' : 'sourceKey'} array.`, { association: assocAny.as });
+                }
+                // Synthesize any missing column with a type that actually matches the
+                // key it references, rather than assuming INTEGER.
+                fkCols.forEach((col, i) => {
+                    if (!columns[col]) {
+                        columns[col] = {
+                            type: resolveForeignKeyColumnType(refModel, refKeys[i]),
+                            allowNull: true,
+                        };
+                    }
+                });
+                if (fkCols.length === 1) {
+                    // Single-column keys stay as an inline column-level REFERENCES.
+                    if (!columns[fkCols[0]].references) {
+                        columns[fkCols[0]] = {
+                            ...columns[fkCols[0]],
                             references: {
                                 table: refTable,
-                                field: assocAny.options?.sourceKey || 'id',
+                                field: refKeys[0],
                                 onDelete: assocAny.options?.onDelete,
                                 onUpdate: assocAny.options?.onUpdate,
                             },
                         };
                     }
                 }
+                else {
+                    // A composite key can only be expressed as a table-level constraint.
+                    const constraintName = `fk_${tableName}_${fkCols.join('_')}`;
+                    synthesizedFkConstraints.push({
+                        name: constraintName,
+                        type: 'FOREIGN KEY',
+                        fields: fkCols,
+                        references: {
+                            table: refTable,
+                            field: refKeys,
+                            onDelete: assocAny.options?.onDelete,
+                            onUpdate: assocAny.options?.onUpdate,
+                        },
+                    });
+                }
             }
         }
-        // Add auto-id column if no primary key is defined in attributes
-        if (!Object.values(columns).some((col) => col.primaryKey) && !columns['id']) {
+        // Add auto-id column if no primary key is defined in attributes.
+        // A composite primary key can only be declared as a table-level constraint,
+        // so that counts as "has a primary key" too - otherwise an `id` column was
+        // injected alongside it and the table came out with two primary keys.
+        const hasTablePrimaryKey = (options.constraints || []).some((c) => c?.type === 'PRIMARY KEY');
+        if (!Object.values(columns).some((col) => col.primaryKey) &&
+            !columns['id'] &&
+            !hasTablePrimaryKey) {
             const withId = {
                 id: {
                     type: 'INTEGER',
@@ -4444,6 +4513,10 @@ class Prorm extends events_1.EventEmitter {
                 : undefined,
             check: c.check,
         }));
+        const allTableConstraints = [
+            ...(tableConstraints || []),
+            ...synthesizedFkConstraints,
+        ];
         await this.dialect.createTable(tableName, columns, {
             ifNotExists: true,
             engine: options.engine,
@@ -4454,7 +4527,7 @@ class Prorm extends events_1.EventEmitter {
             initialAutoIncrement: options.initialAutoIncrement,
             uniqueKeys: options.uniqueKeys,
             indexes: tableIndexes,
-            constraints: tableConstraints,
+            constraints: allTableConstraints,
         });
     }
     /**
@@ -5986,6 +6059,15 @@ $$ LANGUAGE plpgsql;`;
             this.pendingTableCreates = [];
             await Promise.all(pending);
         }
+        // Bind any decorator associations whose target became available after the
+        // source model was added, then surface the ones that never resolved rather
+        // than creating tables with silently missing foreign keys.
+        this._flushPendingAssociations();
+        const unresolved = this._unresolvedAssociationTargets();
+        if (unresolved.length > 0) {
+            throw new errors_1.AssociationError(`Cannot sync: ${unresolved.length} association(s) reference a model that was never ` +
+                `registered (${unresolved.join('; ')}). Pass every model to addModel()/define().`);
+        }
         const { force = false, alter = false, match, logging = false, hooks = true, indexes = true, constraints = true, } = options;
         // Default options
         const syncOptions = {
@@ -6033,6 +6115,9 @@ $$ LANGUAGE plpgsql;`;
                 // Default mode: create missing tables only
                 await this.syncCreate();
             }
+            // Apply annotation-declared DDL (@View / @MaterializedView / @Trigger /
+            // @Procedure) now that the tables they depend on exist.
+            await this.syncSchemaObjects();
             // Run afterSync hook if enabled
             if (hooks) {
                 // Run global afterSync hooks
@@ -6055,6 +6140,342 @@ $$ LANGUAGE plpgsql;`;
         }
         return this;
     }
+    /**
+     * Register a class carrying `@Procedure` / `@SqlFunction` annotations so that
+     * `sync()` creates them.
+     *
+     * Procedures are declared on plain classes rather than models, so there is no
+     * other point at which the ORM would learn about them.
+     */
+    /**
+     * Register an object or key-value store for use by `@ExternalField`.
+     *
+     * Accepts any of the shipped stores (S3, MinIO, R2, GCS, Azure Blob, Redis,
+     * ...) directly - the differing method names are normalized internally - or
+     * any object implementing `ExternalStoreAdapter`.
+     *
+     * ```typescript
+     * const s3 = new S3Store({ region: 'us-east-1' });
+     * await s3.connect();
+     * prorm.registerStore('assets', s3, { defaultBucket: 'avatars' });
+     * ```
+     */
+    registerStore(name, store, options = {}) {
+        this.externalStores.register(name, store, options);
+        return this;
+    }
+    registerProcedures(procedureClass) {
+        if (!this._procedureClasses.includes(procedureClass)) {
+            this._procedureClasses.push(procedureClass);
+        }
+        return this;
+    }
+    /**
+     * Apply the DDL declared by annotations: `@View`, `@MaterializedView`,
+     * `@Trigger` on model classes, and `@Procedure` / `@SqlFunction` on classes
+     * passed to `registerProcedures()`.
+     *
+     * These registries previously generated correct SQL that nothing executed -
+     * `ViewRegistry`, `getTriggers` and `ProcedureRegistry` were referenced only
+     * from inside `src/decorators/`, so annotating a class produced a string the
+     * user still had to fetch and hand to `prorm.query()` themselves.
+     */
+    async syncSchemaObjects() {
+        if (!this.dialect)
+            return;
+        const dialectName = this.dialect.name;
+        for (const modelClass of this._decoratedClasses) {
+            // Views / materialized views
+            try {
+                if ((0, view_1.getViewOptions)(modelClass)) {
+                    await this.query(view_1.ViewRegistry.getSQL(modelClass, dialectName));
+                    this.logger.info(`Created view for ${modelClass.name}`);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to create view for ${modelClass.name}`, { error });
+                throw error;
+            }
+            try {
+                if ((0, view_2.getMaterializedViewOptions)(modelClass)) {
+                    await this.query(view_2.MaterializedViewRegistry.getSQL(modelClass, dialectName));
+                    this.logger.info(`Created materialized view for ${modelClass.name}`);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to create materialized view for ${modelClass.name}`, { error });
+                throw error;
+            }
+            // Triggers
+            const triggers = (0, trigger_1.getTriggers)(modelClass);
+            if (triggers.length > 0) {
+                const tableName = modelClass.tableName || deriveTableName(modelClass.name, undefined);
+                for (const trigger of triggers) {
+                    try {
+                        const sql = (0, trigger_1.buildCreateTriggerSQL)(tableName, trigger, dialectName);
+                        // The postgres builder returns the function and the trigger joined
+                        // by ';\n\n'; most drivers reject multi-statement strings.
+                        for (const stmt of sql.split(/;\s*\n\s*\n/)) {
+                            const trimmed = stmt.trim().replace(/;$/, '');
+                            if (trimmed)
+                                await this.query(trimmed);
+                        }
+                        this.logger.info(`Created trigger ${trigger.name} on ${tableName}`);
+                    }
+                    catch (error) {
+                        this.logger.error(`Failed to create trigger ${trigger.name}`, { error });
+                        throw error;
+                    }
+                }
+            }
+        }
+        // Stored procedures and SQL functions
+        for (const procClass of this._procedureClasses) {
+            for (const meta of procedure_1.ProcedureRegistry.getAll(procClass)) {
+                try {
+                    const sql = procedure_1.ProcedureRegistry.getSQL(procClass, meta.methodKey);
+                    await this.query(sql);
+                    this.logger.info(`Created ${meta.kind ?? 'procedure'} ${meta.options?.name ?? meta.methodKey}`);
+                }
+                catch (error) {
+                    this.logger.error(`Failed to create procedure ${meta.methodKey}`, { error });
+                    throw error;
+                }
+            }
+        }
+    }
+    /**
+     * Bind every queued decorator association whose target model is registered.
+     *
+     * Called after each `addModel()`, and again by `sync()` so that a model graph
+     * registered in any order ends up fully wired before tables are created.
+     * Associations whose target is still unregistered stay queued.
+     */
+    _flushPendingAssociations() {
+        if (this._pendingAssociations.length === 0)
+            return;
+        const stillPending = [];
+        for (const entry of this._pendingAssociations) {
+            const { source, assoc } = entry;
+            let targetModel;
+            try {
+                targetModel = assoc.target();
+            }
+            catch {
+                // The thunk can still throw while a circular import is mid-flight.
+                stillPending.push(entry);
+                continue;
+            }
+            const targetName = targetModel?.name;
+            const registeredTarget = targetName ? this._models.get(targetName) : undefined;
+            if (!registeredTarget) {
+                stillPending.push(entry);
+                continue;
+            }
+            const assocOptions = {
+                as: assoc.as,
+                foreignKey: assoc.foreignKey,
+                onDelete: assoc.onDelete,
+                onUpdate: assoc.onUpdate,
+                hooks: assoc.hooks,
+            };
+            if (assoc.type === 'hasOne' || assoc.type === 'hasMany') {
+                assocOptions.sourceKey = assoc.sourceKey;
+            }
+            if (assoc.type === 'belongsTo') {
+                assocOptions.targetKey = assoc.targetKey;
+            }
+            if (assoc.type === 'belongsToMany') {
+                assocOptions.through = assoc.through;
+                assocOptions.otherKey = assoc.otherKey;
+            }
+            source[assoc.type](registeredTarget, assocOptions);
+        }
+        this._pendingAssociations = stillPending;
+    }
+    /**
+     * Names of models referenced by a decorator association that were never
+     * registered, so callers can report them rather than silently skipping.
+     */
+    _unresolvedAssociationTargets() {
+        const names = new Set();
+        for (const { sourceName, assoc } of this._pendingAssociations) {
+            let targetName = 'unknown';
+            try {
+                targetName = assoc.target()?.name ?? 'unknown';
+            }
+            catch {
+                /* keep 'unknown' */
+            }
+            names.add(`${sourceName}.${assoc.as ?? assoc.type} -> ${targetName}`);
+        }
+        return Array.from(names);
+    }
+    /**
+     * Issue a real `SELECT COUNT(...)` for a model.
+     *
+     * Honors `where`, paranoid filtering, filtering (`required`) includes,
+     * `distinct`/`col` and `group`:
+     *  - `col` picks the counted expression (`COUNT("col")`)
+     *  - `distinct: true` counts distinct values of `col`, or of the primary key
+     *  - `group` returns the number of groups
+     */
+    async _countRows(model, modelName, options = {}) {
+        if (!this.dialect) {
+            throw new Error('Database not connected');
+        }
+        const dialect = this.dialect;
+        const opts = options;
+        const modelOptions = model.options;
+        const isParanoid = modelOptions?.paranoid === true;
+        const deletedAt = modelOptions?.deletedAt || 'deletedAt';
+        let where = options.where;
+        if (isParanoid && options.paranoid !== false && model.rawAttributes?.[deletedAt]) {
+            where = { ...where, [deletedAt]: { $isNull: true } };
+        }
+        // Filtering includes restrict the counted set exactly as they restrict findAll.
+        if (options.include && options.include.length > 0) {
+            for (const rawInclude of options.include) {
+                const filter = await (0, eager_load_1.resolveRequiredIncludeFilter)(this.eagerLoadContext(), model, modelName, rawInclude);
+                if (!filter)
+                    continue;
+                if (filter.values.length === 0)
+                    return 0;
+                const existing = where?.[filter.parentAttr];
+                where = {
+                    ...where,
+                    [filter.parentAttr]: existing
+                        ? { $and: [existing, { $in: filter.values }] }
+                        : { $in: filter.values },
+                };
+            }
+        }
+        const pkAttr = resolveModelPrimaryKeyAttr(model);
+        const countCol = opts.col;
+        const distinct = opts.distinct === true;
+        let countExpr;
+        if (distinct) {
+            countExpr = `COUNT(DISTINCT ${dialect.escapeId(countCol || pkAttr)})`;
+        }
+        else if (countCol) {
+            countExpr = `COUNT(${dialect.escapeId(countCol)})`;
+        }
+        else {
+            countExpr = 'COUNT(*)';
+        }
+        const tableName = model.tableName;
+        const qualified = model.schema
+            ? `${dialect.escapeId(model.schema)}.${dialect.escapeId(tableName)}`
+            : dialect.escapeId(tableName);
+        const groupFields = opts.group
+            ? (Array.isArray(opts.group) ? opts.group : [opts.group]).map((g) => typeof g === 'string' ? g : String(g))
+            : undefined;
+        let sql = `SELECT ${countExpr} AS ${dialect.escapeId('count')} FROM ${qualified}`;
+        let values = [];
+        if (where && Object.keys(where).length > 0) {
+            const built = dialect.buildWhereClause(where);
+            sql += ` WHERE ${built.sql}`;
+            values = built.values;
+        }
+        if (groupFields?.length) {
+            sql += ` GROUP BY ${groupFields.map((g) => dialect.escapeId(g)).join(', ')}`;
+        }
+        const finalSql = dialect.replaceReplacements(sql, values);
+        const result = await dialect.query(finalSql);
+        const rows = result.rows || [];
+        // With GROUP BY the aggregate returns one row per group; the count is the
+        // number of groups, matching how callers use `count({ group })`.
+        if (groupFields?.length)
+            return rows.length;
+        if (!rows.length)
+            return 0;
+        const raw = rows[0].count ?? rows[0].COUNT ?? Object.values(rows[0])[0];
+        return Number(raw) || 0;
+    }
+    /**
+     * The view of this instance that the shared eager-loader needs.
+     */
+    eagerLoadContext() {
+        return {
+            // Materialize to an array: the loader scans this once per include and
+            // again for every nested level, and a Map iterator would be exhausted
+            // after the first scan (leaving later includes with no associations to
+            // match against).
+            associations: Array.from(this.associations.values()),
+            models: this._models,
+        };
+    }
+    /**
+     * Order models so that every table is created after the tables it references.
+     *
+     * Table creation used to follow `modelDefinitions` insertion order, i.e. the
+     * order the user happened to call `define()` in, while `createTableFromModel`
+     * simultaneously emitted REFERENCES clauses. On any dialect that validates
+     * foreign keys at creation time, defining `Post` before `User` failed. The
+     * ordering is derived from the association graph so declaration order stops
+     * mattering.
+     *
+     * Cycles (two models referencing each other) can't be resolved by ordering
+     * alone; those models are emitted last in declaration order, which is the same
+     * behaviour as before for that case.
+     */
+    orderModelsByDependency() {
+        const entries = Array.from(this.modelDefinitions.entries());
+        const byName = new Map(entries.map(([name]) => [name, true]));
+        // dependsOn: model -> set of model names whose tables must exist first.
+        const dependsOn = new Map();
+        for (const [name] of entries)
+            dependsOn.set(name, new Set());
+        for (const assoc of this.associations.values()) {
+            const a = assoc;
+            const sourceName = a.source?.name;
+            const targetName = a.target?.name;
+            if (!sourceName || !targetName || sourceName === targetName)
+                continue;
+            if (!byName.has(sourceName) || !byName.has(targetName))
+                continue;
+            if (a.type === 'belongsTo') {
+                // FK lives on the source, pointing at the target: target first.
+                dependsOn.get(sourceName).add(targetName);
+            }
+            else if (a.type === 'hasMany' || a.type === 'hasOne') {
+                // FK lives on the target, pointing at the source: source first.
+                dependsOn.get(targetName).add(sourceName);
+            }
+        }
+        const ordered = [];
+        const emitted = new Set();
+        const defs = new Map(entries);
+        // Repeatedly emit every model whose dependencies are already satisfied,
+        // preserving declaration order within each pass for stable output.
+        let progress = true;
+        while (progress) {
+            progress = false;
+            for (const [name] of entries) {
+                if (emitted.has(name))
+                    continue;
+                const deps = dependsOn.get(name);
+                let ready = true;
+                for (const dep of deps) {
+                    if (!emitted.has(dep)) {
+                        ready = false;
+                        break;
+                    }
+                }
+                if (ready) {
+                    ordered.push([name, defs.get(name)]);
+                    emitted.add(name);
+                    progress = true;
+                }
+            }
+        }
+        // Anything left is part of a dependency cycle - emit in declaration order.
+        for (const [name, def] of entries) {
+            if (!emitted.has(name))
+                ordered.push([name, def]);
+        }
+        return ordered;
+    }
     /**
      * Default sync mode - creates missing tables only (safe)
      */
@@ -6062,16 +6483,14 @@ $$ LANGUAGE plpgsql;`;
         if (!this.dialect) {
             throw new Error('Database not connected');
         }
-        // Get all registered models and their definitions
-        for (const [modelName, modelDef] of this.modelDefinitions) {
-            const tableName = modelDef.options.tableName || modelName;
+        // Read the existing table list once rather than once per model.
+        const tables = new Set(await this.dialect.showTables());
+        for (const [modelName, modelDef] of this.orderModelsByDependency()) {
+            const tableName = deriveTableName(modelName, modelDef.options);
             try {
-                // Check if table exists
-                const tables = await this.dialect.showTables();
-                const tableExists = tables.includes(tableName);
-                if (!tableExists) {
-                    // Create the table
+                if (!tables.has(tableName)) {
                     await this.createTableFromModel(tableName, modelDef.attributes, modelDef.options, modelName);
+                    tables.add(tableName);
                     this.logger.info(`Created table: ${tableName}`);
                 }
                 else {
@@ -6103,9 +6522,9 @@ $$ LANGUAGE plpgsql;`;
                 this.logger.warn(`Failed to drop table ${tableName}`, { error });
             }
         }
-        // Now create all tables fresh
-        for (const [modelName, modelDef] of this.modelDefinitions) {
-            const tableName = modelDef.options.tableName || (modelDef.options.freezeTableName ? modelName : (0, utils_2.pluralize)(modelName.toLowerCase()));
+        // Now create all tables fresh, parents before children.
+        for (const [modelName, modelDef] of this.orderModelsByDependency()) {
+            const tableName = deriveTableName(modelName, modelDef.options);
             try {
                 await this.createTableFromModel(tableName, modelDef.attributes, modelDef.options, modelName);
                 this.logger.info(`Created table: ${tableName}`);
@@ -6126,9 +6545,9 @@ $$ LANGUAGE plpgsql;`;
         }
         // Get all tables in the database
         const existingTables = await this.dialect.showTables();
-        // Process each model
-        for (const [modelName, modelDef] of this.modelDefinitions) {
-            const tableName = modelDef.options.tableName || (modelDef.options.freezeTableName ? modelName : (0, utils_2.pluralize)(modelName.toLowerCase()));
+        // Process each model, parents before children.
+        for (const [modelName, modelDef] of this.orderModelsByDependency()) {
+            const tableName = deriveTableName(modelName, modelDef.options);
             const modelAttributes = modelDef.attributes;
             const modelOptions = modelDef.options;
             try {