ts-prorm-orm 1.1.0

package/dist/models/associations.js

@@ -0,0 +1,852 @@
+"use strict";
+/**
+ * Association classes for the ORM
+ * Supports hasOne, hasMany, belongsTo, and belongsToMany relationships
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BelongsToManyAssociation = exports.BelongsToAssociation = exports.HasManyAssociation = exports.HasOneAssociation = void 0;
+exports.createAssociationMixins = createAssociationMixins;
+exports.processNestedIncludes = processNestedIncludes;
+// Helper to lower-case the first character of a model name so inferred foreign
+// key column names follow the lowerCamelCase convention used everywhere else
+// in this codebase (e.g. `userId`, not `UserId`). Every test that pre-defines
+// a foreign key column and relies on an association's default inference
+// (rather than passing an explicit `foreignKey` option) uses lowerCamelCase,
+// and downstream lookups (e.g. eager-load default-key resolution in
+// prorm.ts) already lowercase the first character - the association classes
+// below were the one place still producing PascalCase defaults, so the
+// inferred key never matched the actual (lowerCamelCase) column, silently
+// breaking foreign-key constraint enforcement and default-association CRUD
+// helpers (e.g. `createPost`) whenever no explicit `foreignKey` was given.
+function lowerFirst(name) {
+    if (!name)
+        return name;
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
+// Helper to extract foreign key name(s) from various formats
+// Supports composite foreign keys: foreignKey: ['field1', 'field2']
+function extractForeignKeyName(foreignKey, defaultKey) {
+    if (!foreignKey) {
+        return defaultKey;
+    }
+    // Handle array format for composite foreign keys
+    if (Array.isArray(foreignKey)) {
+        return foreignKey;
+    }
+    if (typeof foreignKey === 'string') {
+        return foreignKey;
+    }
+    // Handle object form: { name: 'profile_id' } or { allowNull: false }
+    return foreignKey.name || defaultKey;
+}
+/**
+ * Check if foreign key is a composite key (array)
+ */
+function isCompositeForeignKey(foreignKey) {
+    return Array.isArray(foreignKey) && foreignKey.length > 1;
+}
+/**
+ * Format foreign key for SQL (handles both single and composite).
+ * Always returns a parenthesized column list ready to embed directly after
+ * `FOREIGN KEY` / table name in a constraint clause, e.g. `(id)` or `(a, b)`.
+ */
+function formatForeignKeyForSql(foreignKey) {
+    if (Array.isArray(foreignKey)) {
+        return `(${foreignKey.join(', ')})`;
+    }
+    return `(${foreignKey})`;
+}
+// Helper to extract allowNull from foreignKey options
+function extractAllowNull(foreignKey, defaultValue = true) {
+    if (!foreignKey || typeof foreignKey === 'string') {
+        return defaultValue;
+    }
+    return foreignKey.allowNull ?? defaultValue;
+}
+// Base Association class
+class BaseAssociation {
+    constructor(source, target, options = {}) {
+        this.source = source;
+        this.target = target;
+        // Handle string, array, and object forms of foreignKey
+        // e.g., 'profile_id' or ['order_id', 'product_id'] or { name: 'profile_id', allowNull: false }
+        this.foreignKey = extractForeignKeyName(options.foreignKey, this.inferForeignKey());
+        this.as = options.as || this.target.name.toLowerCase();
+        this.options = options;
+        this.type = this.getType();
+    }
+    /**
+     * Get the association config for queries
+     */
+    getAssociationConfig() {
+        return {
+            model: this.target,
+            as: this.as,
+            foreignKey: this.foreignKey,
+            targetKey: this.options.targetKey,
+            sourceKey: this.options.sourceKey,
+            constraints: this.options.constraints,
+            onDelete: this.options.onDelete,
+            onUpdate: this.options.onUpdate,
+        };
+    }
+}
+/**
+ * Flatten nested includes to a flat array with path information
+ */
+class HasOneAssociation extends BaseAssociation {
+    constructor(source, target, options = {}) {
+        super(source, target, options);
+    }
+    inferForeignKey() {
+        // Default foreign key is target model name + Id (e.g., userId)
+        return `${lowerFirst(this.target.name)}Id`;
+    }
+    getType() {
+        return 'hasOne';
+    }
+    /**
+     * Get the foreign key constraint SQL
+     */
+    getConstraintSql(tableName) {
+        const targetKey = this.options.targetKey || 'id';
+        // Handle composite foreign keys (string | string[])
+        const fk = formatForeignKeyForSql(this.foreignKey);
+        const tk = formatForeignKeyForSql(targetKey);
+        let sql = `FOREIGN KEY ${fk} REFERENCES ${tableName}${tk}`;
+        if (this.options.onDelete) {
+            sql += ` ON DELETE ${this.options.onDelete}`;
+        }
+        if (this.options.onUpdate) {
+            sql += ` ON UPDATE ${this.options.onUpdate}`;
+        }
+        return sql;
+    }
+}
+exports.HasOneAssociation = HasOneAssociation;
+// HasMany Association - one-to-many where source has many targets
+class HasManyAssociation extends BaseAssociation {
+    constructor(source, target, options = {}) {
+        super(source, target, options);
+        // Override to use plural form for hasMany
+        if (!options.as) {
+            this.as = this.target.name.toLowerCase() + 's';
+        }
+    }
+    inferForeignKey() {
+        return `${lowerFirst(this.source.name)}Id`;
+    }
+    getType() {
+        return 'hasMany';
+    }
+    /**
+     * Get the foreign key constraint SQL
+     */
+    getConstraintSql(tableName) {
+        const targetKey = this.options.targetKey || 'id';
+        const fk = formatForeignKeyForSql(this.foreignKey);
+        const tk = formatForeignKeyForSql(targetKey);
+        let sql = `FOREIGN KEY ${fk} REFERENCES ${tableName}${tk}`;
+        if (this.options.onDelete) {
+            sql += ` ON DELETE ${this.options.onDelete}`;
+        }
+        if (this.options.onUpdate) {
+            sql += ` ON UPDATE ${this.options.onUpdate}`;
+        }
+        return sql;
+    }
+}
+exports.HasManyAssociation = HasManyAssociation;
+// BelongsTo Association - one-to-one where source belongs to target
+class BelongsToAssociation extends BaseAssociation {
+    constructor(source, target, options = {}) {
+        super(source, target, options);
+    }
+    inferForeignKey() {
+        // Default foreign key is target model name + Id (e.g., userId)
+        return `${lowerFirst(this.target.name)}Id`;
+    }
+    getType() {
+        return 'belongsTo';
+    }
+    /**
+     * Get the foreign key constraint SQL with onDelete and onUpdate support
+     */
+    getConstraintSql(tableName) {
+        const targetKey = this.options.targetKey || 'id';
+        const fk = formatForeignKeyForSql(this.foreignKey);
+        const tk = formatForeignKeyForSql(targetKey);
+        let sql = `FOREIGN KEY ${fk} REFERENCES ${tableName}${tk}`;
+        if (this.options.onDelete) {
+            sql += ` ON DELETE ${this.options.onDelete}`;
+        }
+        if (this.options.onUpdate) {
+            sql += ` ON UPDATE ${this.options.onUpdate}`;
+        }
+        return sql;
+    }
+    /**
+     * Get the full foreignKey options including allowNull from object form
+     */
+    getForeignKeyOptions() {
+        const fk = this.options.foreignKey;
+        if (!fk || typeof fk === 'string') {
+            return undefined;
+        }
+        return fk;
+    }
+}
+exports.BelongsToAssociation = BelongsToAssociation;
+// BelongsToMany Association - many-to-many through a junction table
+class BelongsToManyAssociation extends BaseAssociation {
+    constructor(source, target, options = {}) {
+        super(source, target, options);
+        this.throughModel = null;
+        // Override to use plural form for belongsToMany
+        if (!options.as) {
+            this.as = this.target.name.toLowerCase() + 's';
+        }
+        // Determine the through table/model
+        if (typeof options.through === 'string') {
+            this.through = options.through;
+        }
+        else if (options.through && typeof options.through === 'object') {
+            // `options.through` is typed as `string | ThroughOptions`, but at runtime callers may
+            // also pass a full ModelStatic directly (e.g. `through: UserProject`). Treat it as an
+            // untyped record here so we can duck-type which shape we actually received, then cast
+            // to the appropriate typed value for each branch below (avoids invalid casts to
+            // ModelStatic<any> from a non-overlapping ThroughOptions type).
+            const throughVal = options.through;
+            // Check if through is a model directly (not an options object)
+            if (throughVal.name && throughVal.rawAttributes) {
+                // It's a model
+                this.through = throughVal.tableName || `${source.name}${target.name}`;
+                this.throughModel = throughVal;
+            }
+            else {
+                // It's an options object (ThroughOptions)
+                const throughOptions = throughVal;
+                this.through =
+                    typeof throughOptions.model === 'string'
+                        ? throughOptions.model
+                        : throughOptions.model?.tableName ||
+                            `${source.name}${target.name}`;
+                this.throughModel = throughOptions.model || null;
+            }
+        }
+        else if (options.through) {
+            // Handle case where through is passed directly as a model
+            this.through = options.through.tableName || `${source.name}${target.name}`;
+            this.throughModel = options.through;
+        }
+        else {
+            // Default through table name
+            this.through = `${source.name}${target.name}`;
+        }
+        // Other key in the junction table. Supports both string ('roleId') and object
+        // ({ name: 'roleId', allowNull: false }) forms, same as top-level foreignKey.
+        const throughOtherKey = options.through && typeof options.through === 'object'
+            ? options.through.otherKey
+            : undefined;
+        // throughOtherKey can only be string | AssociationForeignKeyOptions (no composite array form),
+        // so the result of extractForeignKeyName is always a plain string here.
+        this._otherKey = extractForeignKeyName(throughOtherKey, `${lowerFirst(target.name)}Id`);
+    }
+    inferForeignKey() {
+        return `${lowerFirst(this.source.name)}Id`;
+    }
+    getType() {
+        return 'belongsToMany';
+    }
+    getThrough() {
+        return this.through;
+    }
+    getOtherKey() {
+        return this._otherKey;
+    }
+    setThroughModel(model) {
+        this.throughModel = model;
+    }
+    getThroughModel() {
+        return this.throughModel;
+    }
+}
+exports.BelongsToManyAssociation = BelongsToManyAssociation;
+// Factory function to create association mixin methods
+function createAssociationMixins(source, sourceModelName, instancePrototype) {
+    // Use provided instance prototype, or fall back to source.prototype, or source itself
+    const prototypeTarget = instancePrototype || source.prototype || source;
+    return {
+        hasOne: (target, options = {}) => {
+            const association = new HasOneAssociation(source, target, options);
+            // Add to source associations
+            source.associations[association.as] = association;
+            // Get the prototype target - use source.prototype if it exists, otherwise use source
+            // Add the getter to the source model
+            prototypeTarget[`get${capitalize(association.as)}`] = function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.findOne({
+                    where: { [association.foreignKey]: pk },
+                    ...options,
+                });
+            };
+            // Add the setter - supports instance, null, or foreign key value
+            prototypeTarget[`set${capitalize(association.as)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                // Handle different value types
+                if (value === null) {
+                    // Remove association by setting foreign key to null
+                    await target.update({ [association.foreignKey]: null }, { where: { [association.options.targetKey || 'id']: pk }, ...options });
+                }
+                else if (typeof value === 'object' &&
+                    value !== null &&
+                    value[association.options.targetKey || 'id'] !== undefined) {
+                    // It's an instance - set the foreign key to its primary key
+                    const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                    await target.update({ [association.foreignKey]: pk }, { where: { [association.options.targetKey || 'id']: targetPk }, ...options });
+                }
+                else {
+                    // It's a raw foreign key value (number/string)
+                    await target.update({ [association.foreignKey]: value }, { where: { [association.options.targetKey || 'id']: pk }, ...options });
+                }
+            };
+            // Add the create method - creates and associates in one step
+            prototypeTarget[`create${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.create({ ...values, [association.foreignKey]: pk }, options);
+            };
+            // Add the has method - check if associated record exists
+            prototypeTarget[`has${capitalize(association.as)}`] = async function (options) {
+                const pk = getPrimaryKeyValue(this);
+                const count = await target.count({
+                    where: { [association.foreignKey]: pk },
+                    ...options,
+                });
+                return count > 0;
+            };
+            // Add the count method - count associated records (will be 0 or 1 for hasOne)
+            prototypeTarget[`count${capitalize(association.as)}`] = async function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.count({ where: { [association.foreignKey]: pk }, ...options });
+            };
+            return association;
+        },
+        hasMany: (target, options = {}) => {
+            const association = new HasManyAssociation(source, target, options);
+            // Add to source associations
+            source.associations[association.as] = association;
+            // Get the prototype target - use source.prototype if it exists, otherwise use source
+            // Add the getter
+            prototypeTarget[`get${capitalize(association.as)}`] = function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.findAll({
+                    where: { [association.foreignKey]: pk },
+                    ...options,
+                });
+            };
+            // Add the setter
+            prototypeTarget[`set${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                // Remove existing and add new
+                await target.destroy({ where: { [association.foreignKey]: pk }, ...options });
+                for (const value of values) {
+                    await target.create({ ...value, [association.foreignKey]: pk }, options);
+                }
+            };
+            // Add the add method
+            prototypeTarget[`add${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        await target.update({ [association.foreignKey]: pk }, { where: { [association.options.targetKey || 'id']: value }, ...options });
+                    }
+                }
+                else {
+                    await target.update({ [association.foreignKey]: pk }, { where: { [association.options.targetKey || 'id']: values }, ...options });
+                }
+            };
+            // Add the create method
+            prototypeTarget[`create${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.create({ ...values, [association.foreignKey]: pk }, options);
+            };
+            // Add the remove method
+            prototypeTarget[`remove${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        await target.update({ [association.foreignKey]: null }, { where: { [association.options.targetKey || 'id']: value }, ...options });
+                    }
+                }
+                else {
+                    await target.update({ [association.foreignKey]: null }, { where: { [association.options.targetKey || 'id']: values }, ...options });
+                }
+            };
+            // Add the count method
+            prototypeTarget[`count${capitalize(association.as)}`] = async function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.count({ where: { [association.foreignKey]: pk }, ...options });
+            };
+            // Add the has method - check if instance has associated record(s)
+            prototypeTarget[`has${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (values === undefined) {
+                    // Check if any associated record exists
+                    const count = await target.count({
+                        where: { [association.foreignKey]: pk },
+                        ...options,
+                    });
+                    return count > 0;
+                }
+                // Check if specific value(s) are associated
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        const exists = await target.findOne({
+                            where: {
+                                [association.options.targetKey || 'id']: targetPk,
+                                [association.foreignKey]: pk,
+                            },
+                            ...options,
+                        });
+                        if (!exists)
+                            return false;
+                    }
+                    return true;
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values;
+                    const exists = await target.findOne({
+                        where: {
+                            [association.options.targetKey || 'id']: targetPk,
+                            [association.foreignKey]: pk,
+                        },
+                        ...options,
+                    });
+                    return exists !== null;
+                }
+            };
+            // Add singular alias for add (e.g., addRole for addRoles)
+            const singularAs = association.as.replace(/s$/, '').replace(/ies$/, 'y');
+            prototypeTarget[`add${capitalize(singularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                await target.update({ [association.foreignKey]: pk }, { where: { [association.options.targetKey || 'id']: targetPk }, ...options });
+            };
+            // Add singular alias for remove (e.g., removeRole for removeRoles)
+            prototypeTarget[`remove${capitalize(singularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                await target.update({ [association.foreignKey]: null }, { where: { [association.options.targetKey || 'id']: targetPk }, ...options });
+            };
+            // Add singular alias for has (e.g., hasRole for hasRoles)
+            prototypeTarget[`has${capitalize(singularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value;
+                const exists = await target.findOne({
+                    where: {
+                        [association.options.targetKey || 'id']: targetPk,
+                        [association.foreignKey]: pk,
+                    },
+                    ...options,
+                });
+                return exists !== null;
+            };
+            // Add singular alias for create (e.g., createRole for createRoles)
+            prototypeTarget[`create${capitalize(singularAs)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.create({ ...values, [association.foreignKey]: pk }, options);
+            };
+            return association;
+        },
+        belongsTo: (target, options = {}) => {
+            const association = new BelongsToAssociation(source, target, options);
+            // Add to source associations
+            source.associations[association.as] = association;
+            // Get the prototype target - use source.prototype if it exists, otherwise use source
+            // Add the getter
+            prototypeTarget[`get${capitalize(association.as)}`] = function (options) {
+                const fkValue = this.getDataValue(association.foreignKey);
+                return target.findOne({
+                    where: { [association.options.targetKey || 'id']: fkValue },
+                    ...options,
+                });
+            };
+            // Add the setter
+            prototypeTarget[`set${capitalize(association.as)}`] = async function (value, options) {
+                const pk = value ? value[association.options.targetKey || 'id'] || value.id : null;
+                this.setDataValue(association.foreignKey, pk);
+                if (options?.save !== false) {
+                    await this.save(options);
+                }
+            };
+            // Add the create method
+            prototypeTarget[`create${capitalize(association.as)}`] = async function (values, options) {
+                const created = await target.create(values, options);
+                this.setDataValue(association.foreignKey, created[association.options.targetKey || 'id']);
+                if (options?.save !== false) {
+                    await this.save(options);
+                }
+                return created;
+            };
+            // Add the count method - count associated records (will be 0 or 1 for belongsTo)
+            prototypeTarget[`count${capitalize(association.as)}`] = async function (options) {
+                const fkValue = this.getDataValue(association.foreignKey);
+                if (fkValue === null || fkValue === undefined) {
+                    return 0;
+                }
+                return target.count({
+                    where: { [association.options.targetKey || 'id']: fkValue },
+                    ...options,
+                });
+            };
+            // Add the has method - check if has associated record
+            prototypeTarget[`has${capitalize(association.as)}`] = async function (options) {
+                const fkValue = this.getDataValue(association.foreignKey);
+                if (fkValue === null || fkValue === undefined) {
+                    return false;
+                }
+                const count = await target.count({
+                    where: { [association.options.targetKey || 'id']: fkValue },
+                    ...options,
+                });
+                return count > 0;
+            };
+            return association;
+        },
+        belongsToMany: (target, options = {}) => {
+            const association = new BelongsToManyAssociation(source, target, options);
+            // Add to source associations
+            source.associations[association.as] = association;
+            // Create the through model if needed (use user-provided model if available)
+            let throughModel = association.getThroughModel();
+            if (!throughModel) {
+                throughModel = createThroughModel(source, target, association);
+                association.setThroughModel(throughModel);
+            }
+            // Get the prototype target - use source.prototype if it exists, otherwise use source
+            // Add the getter
+            prototypeTarget[`get${capitalize(association.as)}`] = function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return target.findAll({
+                    include: [
+                        {
+                            model: throughModel,
+                            where: { [association.foreignKey]: pk },
+                            as: association.getThrough(),
+                        },
+                    ],
+                    ...options,
+                });
+            };
+            // Add the setter
+            prototypeTarget[`set${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                // Remove existing associations
+                await throughModel.destroy({
+                    where: { [association.foreignKey]: pk },
+                    ...options,
+                });
+                // Add new associations
+                for (const value of values) {
+                    const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                    await throughModel.create({
+                        [association.foreignKey]: pk,
+                        [association.getOtherKey()]: targetPk,
+                    }, options);
+                }
+            };
+            // Add the add method
+            prototypeTarget[`add${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        await throughModel.findOrCreate({
+                            where: {
+                                [association.foreignKey]: pk,
+                                [association.getOtherKey()]: targetPk,
+                            },
+                            ...options,
+                        });
+                    }
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values.id;
+                    await throughModel.findOrCreate({
+                        where: {
+                            [association.foreignKey]: pk,
+                            [association.getOtherKey()]: targetPk,
+                        },
+                        ...options,
+                    });
+                }
+            };
+            // Add the remove method
+            prototypeTarget[`remove${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        await throughModel.destroy({
+                            where: {
+                                [association.foreignKey]: pk,
+                                [association.getOtherKey()]: targetPk,
+                            },
+                            ...options,
+                        });
+                    }
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values.id;
+                    await throughModel.destroy({
+                        where: {
+                            [association.foreignKey]: pk,
+                            [association.getOtherKey()]: targetPk,
+                        },
+                        ...options,
+                    });
+                }
+            };
+            // Add the create method
+            prototypeTarget[`create${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                const created = await target.create(values, options);
+                await throughModel.create({
+                    [association.foreignKey]: pk,
+                    [association.getOtherKey()]: created[association.options.targetKey || 'id'],
+                }, options);
+                return created;
+            };
+            // Add the count method
+            prototypeTarget[`count${capitalize(association.as)}`] = async function (options) {
+                const pk = getPrimaryKeyValue(this);
+                return throughModel.count({
+                    where: { [association.foreignKey]: pk },
+                    ...options,
+                });
+            };
+            // Add the has method - check if instance has associated record(s) through junction table
+            prototypeTarget[`has${capitalize(association.as)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (values === undefined) {
+                    // Check if any associated record exists
+                    const count = await throughModel.count({
+                        where: { [association.foreignKey]: pk },
+                        ...options,
+                    });
+                    return count > 0;
+                }
+                // Check if specific value(s) are associated
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        const exists = await throughModel.findOne({
+                            where: { [association.foreignKey]: pk, [association.getOtherKey()]: targetPk },
+                            ...options,
+                        });
+                        if (!exists)
+                            return false;
+                    }
+                    return true;
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values;
+                    const exists = await throughModel.findOne({
+                        where: { [association.foreignKey]: pk, [association.getOtherKey()]: targetPk },
+                        ...options,
+                    });
+                    return exists !== null;
+                }
+            };
+            // Add singular alias for add (e.g., addRole for addRoles)
+            const btmSingularAs = association.as.replace(/s$/, '').replace(/ies$/, 'y');
+            prototypeTarget[`add${capitalize(btmSingularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                await throughModel.findOrCreate({
+                    where: {
+                        [association.foreignKey]: pk,
+                        [association.getOtherKey()]: targetPk,
+                    },
+                    ...options,
+                });
+            };
+            // Add singular alias for remove (e.g., removeRole for removeRoles)
+            prototypeTarget[`remove${capitalize(btmSingularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                await throughModel.destroy({
+                    where: {
+                        [association.foreignKey]: pk,
+                        [association.getOtherKey()]: targetPk,
+                    },
+                    ...options,
+                });
+            };
+            // Add singular alias for has (e.g., hasRole for hasRoles)
+            prototypeTarget[`has${capitalize(btmSingularAs)}`] = async function (value, options) {
+                const pk = getPrimaryKeyValue(this);
+                const targetPk = value[association.options.targetKey || 'id'] || value;
+                const exists = await throughModel.findOne({
+                    where: { [association.foreignKey]: pk, [association.getOtherKey()]: targetPk },
+                    ...options,
+                });
+                return exists !== null;
+            };
+            // Add singular alias for create (e.g., createRole for createRoles)
+            prototypeTarget[`create${capitalize(btmSingularAs)}`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                const created = await target.create(values, options);
+                await throughModel.create({
+                    [association.foreignKey]: pk,
+                    [association.getOtherKey()]: created[association.options.targetKey || 'id'],
+                }, options);
+                return created;
+            };
+            // Add the addModel method - alias for add (adds associated records)
+            prototypeTarget[`add${capitalize(association.as)}Model`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        await throughModel.findOrCreate({
+                            where: {
+                                [association.foreignKey]: pk,
+                                [association.getOtherKey()]: targetPk,
+                            },
+                            ...options,
+                        });
+                    }
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values.id;
+                    await throughModel.findOrCreate({
+                        where: {
+                            [association.foreignKey]: pk,
+                            [association.getOtherKey()]: targetPk,
+                        },
+                        ...options,
+                    });
+                }
+            };
+            // Add the removeModel method - alias for remove (removes associated records)
+            prototypeTarget[`remove${capitalize(association.as)}Model`] = async function (values, options) {
+                const pk = getPrimaryKeyValue(this);
+                if (Array.isArray(values)) {
+                    for (const value of values) {
+                        const targetPk = value[association.options.targetKey || 'id'] || value.id;
+                        await throughModel.destroy({
+                            where: {
+                                [association.foreignKey]: pk,
+                                [association.getOtherKey()]: targetPk,
+                            },
+                            ...options,
+                        });
+                    }
+                }
+                else {
+                    const targetPk = values[association.options.targetKey || 'id'] || values.id;
+                    await throughModel.destroy({
+                        where: {
+                            [association.foreignKey]: pk,
+                            [association.getOtherKey()]: targetPk,
+                        },
+                        ...options,
+                    });
+                }
+            };
+            return association;
+        },
+    };
+}
+// Helper to create a through model for belongsToMany
+function createThroughModel(source, target, association) {
+    const throughName = `${source.name}${target.name}`;
+    return {
+        name: throughName,
+        tableName: association.getThrough(),
+        rawAttributes: {
+            [association.foreignKey]: {
+                type: 'INTEGER',
+                allowNull: false,
+                references: { model: source.name, key: 'id' },
+            },
+            [association.getOtherKey()]: {
+                type: 'INTEGER',
+                allowNull: false,
+                references: { model: target.name, key: 'id' },
+            },
+        },
+        associations: {},
+    };
+}
+// Helper to get primary key value from an instance
+function getPrimaryKeyValue(instance) {
+    // Prefer the model's declared primary key attribute (models can define a custom
+    // primary key, e.g. `sku`, not just `id`). Falls back to name-guessing below for
+    // instances that don't expose their model's rawAttributes.
+    const rawAttributes = instance?.model?.rawAttributes || instance?.constructor?.rawAttributes;
+    if (rawAttributes) {
+        for (const [attrName, attr] of Object.entries(rawAttributes)) {
+            if (attr?.primaryKey) {
+                if (instance.getDataValue && instance.getDataValue(attrName) !== undefined) {
+                    return instance.getDataValue(attrName);
+                }
+                if (instance[attrName] !== undefined) {
+                    return instance[attrName];
+                }
+            }
+        }
+    }
+    // Try common primary key names
+    for (const key of ['id', 'Id', 'ID', 'uuid', 'UUID']) {
+        if (instance.getDataValue && instance.getDataValue(key) !== undefined) {
+            return instance.getDataValue(key);
+        }
+        if (instance[key] !== undefined) {
+            return instance[key];
+        }
+    }
+    return instance.id;
+}
+// Helper to capitalize first letter
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+// ==================== Polymorphic Associations ====================
+/**
+ * Options for polymorphic associations
+ */
+function processNestedIncludes(includes, parentModel = null, parentAlias = '') {
+    const result = [];
+    function processInclude(inc, parent, path, level) {
+        const model = inc.model;
+        const tableName = model?.tableName || model?.name || '';
+        const alias = inc.as || tableName;
+        const fullPath = path ? `${path}->${alias}` : alias;
+        result.push({
+            include: inc,
+            parentAlias: parent,
+            path: fullPath,
+            nestedLevel: level,
+        });
+        // Process nested includes
+        if (inc.include && Array.isArray(inc.include)) {
+            for (const nested of inc.include) {
+                processInclude(nested, fullPath, fullPath, level + 1);
+            }
+        }
+    }
+    for (const inc of includes) {
+        processInclude(inc, parentAlias, '', 0);
+    }
+    return result;
+}
+exports.default = {
+    HasOneAssociation,
+    HasManyAssociation,
+    BelongsToAssociation,
+    BelongsToManyAssociation,
+    createAssociationMixins,
+};