import type { AllowIterable, RequiredBy } from '@sequelize/utils'; import type { WhereOptions } from '../abstract-dialect/where-sql-builder-types.js'; import type { AttributeNames, Attributes, BulkCreateOptions, CreateOptions, CreationAttributes, Filterable, FindAttributeOptions, FindOptions, InstanceDestroyOptions, InstanceUpdateOptions, Model, ModelOptions, ModelStatic, Transactionable } from '../model'; import type { Association, AssociationOptions, AssociationScope, ForeignKeyOptions, Key, MultiAssociationAccessors, MultiAssociationOptions, NormalizedAssociationOptions } from './base'; import { MultiAssociation } from './base'; import type { BelongsToAssociation } from './belongs-to.js'; import { HasManyAssociation } from './has-many.js'; import { HasOneAssociation } from './has-one.js'; import type { MaybeForwardedModelStatic } from './helpers'; /** * Many-to-many association with a join/through table. * See {@link Model.belongsToMany} * * When the join table has additional attributes, these can be passed in the options object: * * ```js * UserProject = sequelize.define('user_project', { * role: DataTypes.STRING * }); * User.belongsToMany(Project, { through: UserProject }); * Project.belongsToMany(User, { through: UserProject }); * // through is required! * * user.addProject(project, { through: { role: 'manager' }}); * ``` * * All methods allow you to pass either a persisted instance, its primary key, or a mixture: * * ```js * const project = await Project.create({ id: 11 }); * await user.addProjects([project, 12]); * ``` * * If you want to set several target instances, but with different attributes you have to set the attributes on the instance, using a property with the name of the through model: * * ```js * p1.UserProjects = { * started: true * } * user.setProjects([p1, p2], { through: { started: false }}) // The default value is false, but p1 overrides that. * ``` * * Similarly, when fetching through a join table with custom attributes, these attributes will be available as an object with the name of the through model. * ```js * const projects = await user.getProjects(); * const p1 = projects[0]; * p1.UserProjects.started // Is this project started yet? * ``` * * In the API reference below, add the name of the association to the method, e.g. for `User.belongsToMany(Project)` the getter will be `user.getProjects()`. */ export declare class BelongsToManyAssociation = AttributeNames, TargetKey extends AttributeNames = AttributeNames> extends MultiAssociation> { #private; readonly accessors: MultiAssociationAccessors; readonly _sharedKeys: Array> | undefined; get foreignKey(): string; get foreignKeys(): Array>; /** * The name of the Foreign Key attribute, located on the through table, that points to the Target model. * * Not to be confused with {@link BelongsToManyAssociation#foreignKey}, which points to the Source model instead. */ get otherKey(): string; /** * The names of the Foreign Key attributes, located on the through table, that points to the Target model. * */ get otherKeys(): Array>; /** * @deprecated use {@link BelongsToManyAssociation#foreignKey} */ get identifier(): string; /** * The corresponding column name of {@link BelongsToManyAssociation#foreignKey} */ get identifierField(): string; /** * The corresponding column names of {@link BelongsToManyAssociation#foreignKeys} */ get identifierFields(): string[]; /** * The corresponding column name of {@link BelongsToManyAssociation#otherKey} */ get foreignIdentifierField(): string; /** * The corresponding column names of {@link BelongsToManyAssociation#otherKeys} */ get foreignIdentifierFields(): string[]; /** * The name of the Attribute that the {@link foreignKey} fk (located on the Through Model) will reference on the Source model. */ get sourceKey(): SourceKey; /** * The names of the Attributes that the {@link foreignKeys} fk (located on the Through Model) will reference on the Source model. */ get sourceKeys(): SourceKey[]; /** * The name of the Column that the {@link foreignKey} fk (located on the Through Table) will reference on the Source model. */ get sourceKeyField(): string; get sourceKeyFields(): string[]; /** * The name of the Attribute that the {@link otherKey} fk (located on the Through Model) will reference on the Target model. */ get targetKey(): TargetKey; /** * The names of the Attributes that the {@link otherKey} fk (located on the Through Model) will reference on the Target model. */ get targetKeys(): TargetKey[]; /** * The name of the Column that the {@link otherKey} fk (located on the Through Table) will reference on the Target model. */ get targetKeyField(): string; /** * The names of the Columns that the {@link otherKey} fk (located on the Through Table) will reference on the Target model. */ get targetKeyFields(): string[]; /** * The corresponding association this entity is paired with. */ pairedWith: BelongsToManyAssociation; readonly fromSourceToThrough: HasManyAssociation; readonly fromSourceToThroughOne: HasOneAssociation; get fromThroughToSource(): BelongsToAssociation; get fromTargetToThrough(): HasManyAssociation; get fromTargetToThroughOne(): HasOneAssociation; get fromThroughToTarget(): BelongsToAssociation; get through(): NormalizedThroughOptions; get throughModel(): ModelStatic; constructor(secret: symbol, source: ModelStatic, target: ModelStatic, options: NormalizedBelongsToManyOptions, pair?: BelongsToManyAssociation, parent?: Association); static associate, TargetKey extends AttributeNames>(secret: symbol, source: ModelStatic, target: ModelStatic, options: BelongsToManyOptions, pair?: BelongsToManyAssociation, parent?: Association): BelongsToManyAssociation; /** * Get everything currently associated with this, using an optional where clause. * * See {@link Model} for a full explanation of options * * @param instance instance * @param options find options */ get(instance: SourceModel, options?: BelongsToManyGetAssociationsMixinOptions): Promise; /** * Count everything currently associated with this, using an optional where clause. * * @param instance instance * @param options find options */ count(instance: SourceModel, options?: BelongsToManyCountAssociationsMixinOptions): Promise; /** * Check if one or more instance(s) are associated with this. If a list of instances is passed, the function returns true if _all_ instances are associated * * @param sourceInstance source instance to check for an association with * @param targetInstancesOrPks Can be an array of instances or their primary keys * @param options Options passed to getAssociations */ has(sourceInstance: SourceModel, targetInstancesOrPks: AllowIterable>, options?: BelongsToManyHasAssociationMixinOptions): Promise; /** * Set the associated models by passing an array of instances or their primary keys. * Everything that it not in the passed array will be un-associated. * * @param sourceInstance source instance to associate new instances with * @param newInstancesOrPrimaryKeys A single instance or primary key, or a mixed array of persisted instances or primary keys * @param options Options passed to `through.findAll`, `bulkCreate`, `update` and `destroy` */ set(sourceInstance: SourceModel, newInstancesOrPrimaryKeys: AllowIterable>, options?: BelongsToManySetAssociationsMixinOptions): Promise; /** * Associate one or several rows with source instance. It will not un-associate any already associated instance * that may be missing from `newInstances`. * * @param sourceInstance source instance to associate new instances with * @param newInstancesOrPrimaryKeys A single instance or primary key, or a mixed array of persisted instances or primary keys * @param options Options passed to `through.findAll`, `bulkCreate` and `update` */ add(sourceInstance: SourceModel, newInstancesOrPrimaryKeys: AllowIterable>, options?: BelongsToManyAddAssociationsMixinOptions): Promise; /** * Un-associate one or more instance(s). * * @param sourceInstance instance to un associate instances with * @param targetInstanceOrPks Can be an Instance or its primary key, or a mixed array of instances and primary keys * @param options Options passed to `through.destroy` */ remove(sourceInstance: SourceModel, targetInstanceOrPks: AllowIterable>, options?: BelongsToManyRemoveAssociationMixinOptions): Promise; /** * Create a new instance of the associated model and associate it with this. * * @param sourceInstance source instance * @param values values for target model * @param options Options passed to create and add */ create(sourceInstance: SourceModel, values?: CreationAttributes, options?: BelongsToManyCreateAssociationMixinOptions | BelongsToManyCreateAssociationMixinOptions['fields']): Promise; } /** * Used for the through table in n:m associations. * * Used in {@link BelongsToManyOptions.through} */ export interface ThroughOptions { /** * The model used to join both sides of the N:M association. * Can be a string if you want the model to be generated by sequelize. */ model: MaybeForwardedModelStatic | string; /** * See {@link ModelOptions.timestamps} */ timestamps?: ModelOptions['timestamps']; /** * See {@link ModelOptions.paranoid} */ paranoid?: ModelOptions['paranoid']; /** * A key/value set that will be used for association create and find defaults on the through model. * (Remember to add the attributes to the through model) */ scope?: AssociationScope; /** * If true a unique constraint will be added on the foreign key pair. * If set to a string, the generated unique key will use the string as its name. * If set to false, no unique constraint will be added. * Useful if you want to turn this off and create your own unique constraint when using scopes. * * This option only works if the model already has a Primary Key, * as the unique constraint will not be added if the foreign keys are already part of the composite primary key. * * @default true */ unique?: boolean | string; } /** * Attributes for the join table */ export interface JoinTableAttributes { [attribute: string]: unknown; } type NormalizedBelongsToManyOptions = Omit, 'throughAssociations'>, 'through' | 'as' | 'hooks' | 'foreignKey' | 'inverse'> & { through: NormalizedThroughOptions; inverse?: Exclude['inverse'], string>; } & Pick, 'as' | 'name' | 'hooks' | 'foreignKey'>; type NormalizedThroughOptions = Omit, 'model'> & { model: ModelStatic; }; /** * Options provided when associating models with belongsToMany relationship. * * Used by {@link Model.belongsToMany}. */ export interface BelongsToManyOptions extends MultiAssociationOptions> { /** * The name of the inverse association, or an object for further association setup. */ inverse?: string | undefined | { as?: AssociationOptions['as']; scope?: MultiAssociationOptions['scope']; foreignKeyConstraints?: AssociationOptions['foreignKeyConstraints']; }; /** * Should "ON UPDATE", "ON DELETE" and "REFERENCES" constraints be enabled on the foreign key? * * This only affects the foreign key that points to the source model. * to control the one that points to the target model, set the "foreignKeyConstraints" option in {@link BelongsToManyOptions.inverse}. */ foreignKeyConstraints?: boolean; /** * The name of the table that is used to join source and target in n:m associations. Can also be a * Sequelize model if you want to define the junction table yourself and add extra attributes to it. */ through: MaybeForwardedModelStatic | string | ThroughOptions; /** * Configures the name of the associations that will be defined between the source model and the through model, * as well as between the target model and the through model. */ throughAssociations?: { /** * The name of the HasMany association going from the Source model to the Through model. * * By default, the association will be the name of the BelongsToMany association * + the name of the inverse BelongsToMany association. */ fromSource?: string | undefined; /** * The name of the BelongsTo association going from the Through model to the Source model. * * By default, the association name will be the name of the inverse BelongsToMany association, singularized. */ toSource?: string | undefined; /** * The name of the HasMany association going from the Target model to the Through model. * * By default, the association will be the name of the Inverse BelongsToMany association * + the name of the BelongsToMany association. */ fromTarget?: string | undefined; /** * The name of the BelongsTo association going from the Through model to the Target model. * * By default, the association name will be the name of the parent BelongsToMany association, singularized. */ toTarget?: string | undefined; }; /** * The name of the foreign key attribute in the through model (representing the target model) or an object representing * the type definition for the other column (see `Sequelize.define` for syntax). When using an object, you * can add a `name` property to set the name of the colum. Defaults to the name of target + primary key of * target */ otherKey?: AttributeNames | ForeignKeyOptions>; /** * The name of the attribute to use as the key for the association in the source table. * Defaults to the primary key attribute of the source model */ sourceKey?: SourceKey; /** * The name of the attribute to use as the key for the association in the target table. * Defaults to the primary key attribute of the target model */ targetKey?: TargetKey; } /** * The options for the getAssociations mixin of the belongsToMany association. * * @see BelongsToManyGetAssociationsMixin */ export interface BelongsToManyGetAssociationsMixinOptions extends FindOptions> { /** * A list of the attributes from the join table that you want to select. */ joinTableAttributes?: FindAttributeOptions>; /** * Apply a scope on the related model, or remove its default scope by passing false. */ scope?: string | boolean; /** * Apply a schema on the related model */ schema?: string; schemaDelimiter?: string; through?: { where?: WhereOptions; paranoid?: boolean; }; } /** * The getAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare getRoles: BelongsToManyGetAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyGetAssociationsMixin = (options?: BelongsToManyGetAssociationsMixinOptions) => Promise; /** * The options for the setAssociations mixin of the belongsToMany association. * * @see BelongsToManySetAssociationsMixin */ export interface BelongsToManySetAssociationsMixinOptions extends FindOptions>, BulkCreateOptions>, InstanceUpdateOptions>, InstanceDestroyOptions { /** * Additional attributes for the join table. */ through?: JoinTableAttributes; } /** * The setAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare setRoles: BelongsToManySetAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManySetAssociationsMixin = (newAssociations?: Iterable | null, options?: BelongsToManySetAssociationsMixinOptions) => Promise; /** * The options for the addAssociations mixin of the belongsToMany association. * * @see BelongsToManyAddAssociationsMixin */ export interface BelongsToManyAddAssociationsMixinOptions extends FindOptions>, BulkCreateOptions>, InstanceUpdateOptions>, InstanceDestroyOptions { through?: JoinTableAttributes; } /** * The addAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare addRoles: BelongsToManyAddAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyAddAssociationsMixin = (newAssociations?: Iterable, options?: BelongsToManyAddAssociationsMixinOptions) => Promise; /** * The options for the addAssociation mixin of the belongsToMany association. * * @see BelongsToManyAddAssociationMixin */ export interface BelongsToManyAddAssociationMixinOptions extends FindOptions>, BulkCreateOptions>, InstanceUpdateOptions>, InstanceDestroyOptions { through?: JoinTableAttributes; } /** * The addAssociation mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare addRole: BelongsToManyAddAssociationMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyAddAssociationMixin = (newAssociation?: T | TModelPrimaryKey, options?: BelongsToManyAddAssociationMixinOptions) => Promise; /** * The options for the createAssociation mixin of the belongsToMany association. * * @see BelongsToManyCreateAssociationMixin */ export interface BelongsToManyCreateAssociationMixinOptions extends CreateOptions> { through?: JoinTableAttributes; } /** * The createAssociation mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare createRole: BelongsToManyCreateAssociationMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyCreateAssociationMixin = (values?: CreationAttributes, options?: BelongsToManyCreateAssociationMixinOptions) => Promise; /** * The options for the removeAssociation mixin of the belongsToMany association. * * @see BelongsToManyRemoveAssociationMixin */ export interface BelongsToManyRemoveAssociationMixinOptions extends InstanceDestroyOptions { } /** * The removeAssociation mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare removeRole: BelongsToManyRemoveAssociationMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyRemoveAssociationMixin = (oldAssociated?: TModel | TModelPrimaryKey, options?: BelongsToManyRemoveAssociationMixinOptions) => Promise; /** * The options for the removeAssociations mixin of the belongsToMany association. * * @see BelongsToManyRemoveAssociationsMixin */ export interface BelongsToManyRemoveAssociationsMixinOptions extends InstanceDestroyOptions, InstanceDestroyOptions { } /** * The removeAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare removeRoles: BelongsToManyRemoveAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyRemoveAssociationsMixin = (associationsToRemove?: Iterable, options?: BelongsToManyRemoveAssociationsMixinOptions) => Promise; /** * The options for the hasAssociation mixin of the belongsToMany association. * * @see BelongsToManyHasAssociationMixin */ export interface BelongsToManyHasAssociationMixinOptions extends BelongsToManyGetAssociationsMixinOptions { } /** * The hasAssociation mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare hasRole: BelongsToManyHasAssociationMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyHasAssociationMixin = (target: TModel | TModelPrimaryKey, options?: BelongsToManyHasAssociationMixinOptions) => Promise; /** * The options for the hasAssociations mixin of the belongsToMany association. * * @see BelongsToManyHasAssociationsMixin */ export interface BelongsToManyHasAssociationsMixinOptions extends BelongsToManyGetAssociationsMixinOptions { } /** * The removeAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare hasRoles: BelongsToManyHasAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyHasAssociationsMixin = (targets: Iterable, options?: BelongsToManyHasAssociationsMixinOptions) => Promise; /** * The options for the countAssociations mixin of the belongsToMany association. * * @see BelongsToManyCountAssociationsMixin */ export interface BelongsToManyCountAssociationsMixinOptions extends Transactionable, Filterable> { /** * Apply a scope on the related model, or remove its default scope by passing false. */ scope?: string | boolean; } /** * The countAssociations mixin applied to models with belongsToMany. * An example of usage is as follows: * * ```typescript * class User extends Model, InferCreationAttributes> { * declare countRoles: Sequelize.BelongsToManyCountAssociationsMixin; * } * * User.belongsToMany(Role, { through: UserRole }); * ``` * * @see Model.belongsToMany */ export type BelongsToManyCountAssociationsMixin = (options?: BelongsToManyCountAssociationsMixinOptions) => Promise; export {}; //# sourceMappingURL=belongs-to-many.d.ts.map