ts-prorm-orm 1.1.0 → 1.2.1

package/dist/models/eager-load.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * Shared eager-loading (`include`) implementation.
+ *
+ * There used to be two separate implementations of this: one inside
+ * `Prorm.define()`'s `findAll` closure (used by models created with
+ * `prorm.define(...)`) and one in `models/model.ts` (`processNestedIncludes`,
+ * used by the class-based `Model` API). Both were live, and they had drifted:
+ * the model.ts copy treated `belongsTo` exactly like `hasMany` - querying the
+ * target table for a foreign key that actually lives on the parent - and
+ * skipped `belongsToMany` entirely with a bare `continue`. Which of the two
+ * bugs you hit depended on which API you had used to define the model.
+ *
+ * Both paths now call `loadIncludes()` below.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePrimaryKeyAttr = resolvePrimaryKeyAttr;
+exports.resolveIncludeAssociation = resolveIncludeAssociation;
+exports.includeFiltersParents = includeFiltersParents;
+exports.resolveRequiredIncludeFilter = resolveRequiredIncludeFilter;
+exports.loadIncludes = loadIncludes;
+const errors_1 = require("../errors");
+/** Resolve a model's primary key attribute name, defaulting to `id`. */
+function resolvePrimaryKeyAttr(m) {
+    const attrs = m?.rawAttributes || m?.attributes;
+    if (attrs) {
+        for (const [attrName, attr] of Object.entries(attrs)) {
+            if (attr?.primaryKey)
+                return attrName;
+        }
+    }
+    return 'id';
+}
+/**
+ * Read a field from a row that may be a plain object or a model instance.
+ */
+function readField(row, field) {
+    if (row == null)
+        return undefined;
+    if (typeof row.getDataValue === 'function') {
+        const v = row.getDataValue(field);
+        if (v !== undefined)
+            return v;
+    }
+    if (row.dataValues && field in row.dataValues)
+        return row.dataValues[field];
+    return row[field];
+}
+/**
+ * Attach a loaded association to a row, keeping the instance's `dataValues`
+ * in sync so both `row.posts` and `row.getDataValue('posts')` see it.
+ */
+function attachField(row, field, value) {
+    row[field] = value;
+    if (row?.dataValues)
+        row.dataValues[field] = value;
+    if (typeof row?.setDataValue === 'function') {
+        try {
+            row.setDataValue(field, value);
+        }
+        catch {
+            /* instances with a frozen attribute set still get the plain property above */
+        }
+    }
+}
+function lowerFirst(name) {
+    return name ? name.charAt(0).toLowerCase() + name.slice(1) : name;
+}
+/**
+ * Normalize the two accepted include shapes: `{ model: Post, as: 'posts' }`
+ * and the bare-model shorthand `Post`.
+ */
+function normalizeInclude(rawIncludeOpt) {
+    return rawIncludeOpt && !rawIncludeOpt.model && rawIncludeOpt.rawAttributes
+        ? { model: rawIncludeOpt }
+        : rawIncludeOpt;
+}
+/**
+ * Find the association backing one `include` entry.
+ *
+ * Matching is deliberately strict about aliases. The previous implementation
+ * scanned for any association linking the two models and took the first hit,
+ * with a second pass that also matched the *reverse* direction - so with both
+ * `Post.belongsTo(User, { as: 'author' })` and
+ * `Post.belongsTo(User, { as: 'editor' })` declared, an unaliased
+ * `include: [User]` silently bound to whichever was registered first, and could
+ * bind to an association pointing the other way and then apply the wrong
+ * foreign-key logic to it.
+ */
+function resolveIncludeAssociation(ctx, parentModel, parentModelName, includeOpt) {
+    const includeModel = includeOpt.model;
+    const wantedAlias = includeOpt.as;
+    const matches = [];
+    for (const assoc of ctx.associations) {
+        const sourceMatch = assoc.source === parentModel || assoc.source?.name === parentModelName;
+        if (!sourceMatch)
+            continue;
+        const targetMatch = assoc.target === includeModel || assoc.target?.name === includeModel?.name;
+        if (!targetMatch)
+            continue;
+        matches.push(assoc);
+    }
+    if (wantedAlias) {
+        // Compare against the association's effective alias - `assoc.as` - which is
+        // what the result is attached under. The old code compared `options.as`,
+        // which is undefined whenever the alias was derived rather than passed.
+        const byAlias = matches.filter((a) => (a.as ?? a.options?.as) === wantedAlias);
+        if (byAlias.length === 1)
+            return byAlias[0];
+        if (byAlias.length === 0) {
+            const available = matches.map((a) => a.as).filter(Boolean);
+            throw new errors_1.AssociationError(`${parentModelName} has no association to ${includeModel?.name} aliased '${wantedAlias}'` +
+                (available.length ? `. Available: ${available.join(', ')}` : ''), { association: wantedAlias });
+        }
+        return byAlias[0];
+    }
+    if (matches.length === 0) {
+        throw new errors_1.AssociationError(`${parentModelName} has no association to ${includeModel?.name}. ` +
+            `Declare one with ${parentModelName}.hasMany(${includeModel?.name}) / .belongsTo(...) ` +
+            `before including it.`, { association: includeModel?.name });
+    }
+    if (matches.length > 1) {
+        const aliases = matches.map((a) => a.as).filter(Boolean);
+        throw new errors_1.AssociationError(`${parentModelName} has ${matches.length} associations to ${includeModel?.name} ` +
+            `(${aliases.join(', ')}). Disambiguate with \`include: [{ model: ${includeModel?.name}, ` +
+            `as: '${aliases[0]}' }]\`.`, { association: includeModel?.name });
+    }
+    return matches[0];
+}
+/** Resolve a `through` given as a string against the model registry. */
+function resolveThroughModel(ctx, assoc) {
+    if (assoc.throughModel && typeof assoc.throughModel.findAll === 'function') {
+        return assoc.throughModel;
+    }
+    const wanted = assoc.through;
+    if (!wanted)
+        return assoc.throughModel;
+    const all = ctx.models instanceof Map ? Array.from(ctx.models.values()) : Object.values(ctx.models || {});
+    for (const m of all) {
+        if (m?.tableName === wanted || m?.name === wanted)
+            return m;
+    }
+    return assoc.throughModel;
+}
+/**
+ * An include filters its parents when it is `required`, and `required` defaults
+ * to true whenever the include carries its own `where` - the same rule Sequelize
+ * uses, and the one the docs describe as INNER JOIN semantics.
+ */
+function includeFiltersParents(includeOpt) {
+    if (includeOpt.required === true)
+        return true;
+    if (includeOpt.required === false)
+        return false;
+    return includeOpt.where !== undefined && includeOpt.where !== null;
+}
+/**
+ * Collect the parent-key values that satisfy a filtering (`required`) include.
+ *
+ * This is what gives `required: true` and `include.where` their INNER JOIN
+ * *semantics*: the set of parent keys with a matching child is resolved first,
+ * and the caller adds it to the main query's WHERE so that LIMIT/OFFSET apply
+ * after filtering rather than before. `include` still does not emit a single
+ * JOINed SELECT - associations are fetched with their own queries - but the
+ * rows a filtering include selects are now correct.
+ *
+ * Returns the list of matching parent key values, plus the parent attribute
+ * those values should be compared against.
+ */
+async function resolveRequiredIncludeFilter(ctx, parentModel, parentModelName, rawIncludeOpt) {
+    const includeOpt = normalizeInclude(rawIncludeOpt);
+    if (!includeOpt?.model || !includeFiltersParents(includeOpt))
+        return null;
+    const assoc = resolveIncludeAssociation(ctx, parentModel, parentModelName, includeOpt);
+    const includeModel = includeOpt.model;
+    const foreignKey = assoc.foreignKey;
+    const sourcePkAttr = resolvePrimaryKeyAttr(parentModel);
+    const targetPkAttr = resolvePrimaryKeyAttr(includeModel);
+    // Nested required includes constrain their own parent first, so that
+    // `include: [{ model: Post, required: true, include: [{ model: Tag, required: true }] }]`
+    // keeps only users whose posts have tags.
+    const nestedWhere = {
+        ...(assoc.options?.scope || {}),
+        ...(includeOpt.where || {}),
+    };
+    for (const nested of includeOpt.include || []) {
+        const nestedFilter = await resolveRequiredIncludeFilter(ctx, includeModel, includeModel.name, nested);
+        if (nestedFilter) {
+            if (nestedFilter.values.length === 0)
+                return { parentAttr: sourcePkAttr, values: [] };
+            nestedWhere[nestedFilter.parentAttr] = { $in: nestedFilter.values };
+        }
+    }
+    if (assoc.type === 'belongsTo') {
+        // Parent holds the FK; keep parents whose referenced target matches.
+        const targetRows = await includeModel.findAll({ where: nestedWhere });
+        const ids = targetRows
+            .map((r) => readField(r, targetPkAttr))
+            .filter((v) => v !== undefined && v !== null);
+        return { parentAttr: foreignKey, values: ids };
+    }
+    if (assoc.type === 'belongsToMany') {
+        const throughModel = resolveThroughModel(ctx, assoc);
+        if (!throughModel || typeof throughModel.findAll !== 'function') {
+            throw new errors_1.AssociationError(`Cannot resolve through model for belongsToMany association '${assoc.as}'`, { association: assoc.as });
+        }
+        const otherKey = assoc.otherKey || `${lowerFirst(includeModel.name)}Id`;
+        const targetRows = await includeModel.findAll({ where: nestedWhere });
+        const targetIds = targetRows
+            .map((r) => readField(r, targetPkAttr))
+            .filter((v) => v !== undefined && v !== null);
+        if (targetIds.length === 0)
+            return { parentAttr: sourcePkAttr, values: [] };
+        const junctionRows = await throughModel.findAll({
+            where: { [otherKey]: { $in: targetIds } },
+        });
+        const parentIds = Array.from(new Set(junctionRows
+            .map((r) => readField(r, foreignKey))
+            .filter((v) => v !== undefined && v !== null)));
+        return { parentAttr: sourcePkAttr, values: parentIds };
+    }
+    // hasOne / hasMany: FK lives on the target, pointing back at the parent.
+    const childRows = await includeModel.findAll({ where: nestedWhere });
+    const parentIds = Array.from(new Set(childRows
+        .map((r) => readField(r, foreignKey))
+        .filter((v) => v !== undefined && v !== null)));
+    return { parentAttr: sourcePkAttr, values: parentIds };
+}
+/**
+ * Eager-load `includeList` onto `parentRows`, recursing into nested includes.
+ *
+ * Failures are raised as `EagerLoadError` rather than swallowed. They used to be
+ * caught and reported as an empty result, which made a typo'd alias, a missing
+ * foreign key column, an unresolvable through model and a genuinely childless
+ * parent all look identical - and hid most of the bugs this module now fixes.
+ */
+async function loadIncludes(ctx, parentRows, parentModel, parentModelName, includeList) {
+    if (!parentRows.length || !includeList?.length)
+        return;
+    for (const rawIncludeOpt of includeList) {
+        const includeOpt = normalizeInclude(rawIncludeOpt);
+        const includeModel = includeOpt?.model;
+        if (!includeModel)
+            continue;
+        // Resolve the association outside the try so that a genuinely bad include
+        // (unknown or ambiguous association) surfaces as an AssociationError with a
+        // fix in the message, rather than being wrapped as a load failure.
+        const assoc = resolveIncludeAssociation(ctx, parentModel, parentModelName, includeOpt);
+        const includeAlias = includeOpt.as || assoc.as || includeModel.tableName || includeModel.name;
+        const associationType = assoc.type;
+        const foreignKey = assoc.foreignKey;
+        const sourcePkAttr = resolvePrimaryKeyAttr(parentModel);
+        const targetPkAttr = resolvePrimaryKeyAttr(includeModel);
+        let fetchedRows = [];
+        try {
+            // An association `scope` is a fixed set of conditions applied every time
+            // the association is traversed. It was accepted by the options type and
+            // documented, but never applied by the loader. The include's own `where`
+            // wins on conflict so a caller can still narrow further.
+            const includeWhere = {
+                ...(assoc.options?.scope || {}),
+                ...(includeOpt.where || {}),
+            };
+            const passThrough = {
+                ...(includeOpt.attributes ? { attributes: includeOpt.attributes } : {}),
+                ...(includeOpt.order ? { order: includeOpt.order } : {}),
+            };
+            if (associationType === 'belongsTo') {
+                // The foreign key is a column on the parent, referencing the target's key.
+                const fkValues = parentRows
+                    .map((r) => readField(r, foreignKey))
+                    .filter((v) => v !== undefined && v !== null);
+                if (fkValues.length === 0) {
+                    for (const row of parentRows)
+                        attachField(row, includeAlias, null);
+                    continue;
+                }
+                const targetRows = await includeModel.findAll({
+                    where: { ...includeWhere, [targetPkAttr]: { $in: fkValues } },
+                    ...passThrough,
+                });
+                fetchedRows = targetRows;
+                const targetMap = new Map();
+                for (const tr of targetRows)
+                    targetMap.set(readField(tr, targetPkAttr), tr);
+                for (const row of parentRows) {
+                    const fkVal = readField(row, foreignKey);
+                    attachField(row, includeAlias, fkVal !== undefined && fkVal !== null ? targetMap.get(fkVal) ?? null : null);
+                }
+            }
+            else if (associationType === 'belongsToMany') {
+                const throughModel = resolveThroughModel(ctx, assoc);
+                if (!throughModel || typeof throughModel.findAll !== 'function') {
+                    throw new Error(`Cannot resolve through model for belongsToMany include '${includeAlias}'`);
+                }
+                const otherKey = assoc.otherKey || `${lowerFirst(includeModel.name)}Id`;
+                const mainPks = parentRows
+                    .map((r) => readField(r, sourcePkAttr))
+                    .filter((v) => v !== undefined && v !== null);
+                if (mainPks.length === 0)
+                    continue;
+                const junctionRows = await throughModel.findAll({
+                    where: { [foreignKey]: { $in: mainPks } },
+                });
+                const targetIdsBySource = new Map();
+                const allTargetIds = [];
+                for (const jr of junctionRows) {
+                    const srcVal = readField(jr, foreignKey);
+                    const tgtVal = readField(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)
+                        attachField(row, includeAlias, []);
+                    continue;
+                }
+                const targetRows = await includeModel.findAll({
+                    where: { ...includeWhere, [targetPkAttr]: { $in: allTargetIds } },
+                    ...passThrough,
+                });
+                fetchedRows = targetRows;
+                const targetMap = new Map();
+                for (const tr of targetRows)
+                    targetMap.set(readField(tr, targetPkAttr), tr);
+                for (const row of parentRows) {
+                    const targetIds = targetIdsBySource.get(readField(row, sourcePkAttr)) || [];
+                    attachField(row, includeAlias, targetIds.map((tid) => targetMap.get(tid)).filter((v) => v !== undefined));
+                }
+            }
+            else {
+                // hasOne / hasMany: the foreign key is a column on the target table.
+                const mainPks = parentRows
+                    .map((r) => readField(r, sourcePkAttr))
+                    .filter((v) => v !== undefined && v !== null);
+                if (mainPks.length === 0)
+                    continue;
+                includeWhere[foreignKey] = { $in: mainPks };
+                const assocRows = await includeModel.findAll({ where: includeWhere, ...passThrough });
+                fetchedRows = assocRows;
+                const groupedRows = new Map();
+                for (const ar of assocRows) {
+                    const fkVal = readField(ar, foreignKey);
+                    if (!groupedRows.has(fkVal))
+                        groupedRows.set(fkVal, []);
+                    groupedRows.get(fkVal).push(ar);
+                }
+                for (const row of parentRows) {
+                    const associated = groupedRows.get(readField(row, sourcePkAttr)) || [];
+                    attachField(row, includeAlias, associationType === 'hasOne' ? associated[0] ?? null : associated);
+                }
+            }
+            // Recurse, treating the rows just fetched as the parents for the next level.
+            const nestedIncludes = includeOpt.include;
+            if (nestedIncludes?.length && fetchedRows.length > 0) {
+                await loadIncludes(ctx, fetchedRows, includeModel, includeModel.name, nestedIncludes);
+            }
+        }
+        catch (error) {
+            if (error instanceof errors_1.EagerLoadError || error instanceof errors_1.AssociationError)
+                throw error;
+            throw new errors_1.EagerLoadError(parentModelName, includeAlias, associationType, error);
+        }
+    }
+}

package/dist/models/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Models module exports
+ */
+export * from './data-types';
+export * from './operators';
+export * from './model';
+export * from './associations';
+export * from './scopes';
+export { ModelManager } from './model-manager';
+export * from './scopes';
+export * from './model-manager';
+export * from './methods';
+export { Model } from './model';