Class BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>

Many-to-many association with a join/through table. See belongsToMany

When the join table has additional attributes, these can be passed in the options object:

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:

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:

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.

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().

Type Parameters

Hierarchy

  • MultiAssociation<SourceModel, TargetModel, string, TargetKey, NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>>
    • BelongsToMany

Constructors

constructor

Properties

#private accessors fromSourceToThrough fromSourceToThroughOne isAliased isSelfAssociation options pairedWith parentAssociation source target

Accessors

as associationType foreignIdentifierField foreignKey fromTargetToThrough fromTargetToThroughOne fromThroughToSource fromThroughToTarget identifier identifierField isMultiAssociation isSingleAssociation name otherKey rootAssociation scope sourceKey sourceKeyField targetKey targetKeyField through throughModel isMultiAssociation

Methods

add count create get has remove set toInstanceArray associate

Constructors

constructor

  • Type Parameters

    • SourceModel extends Model<any, any, SourceModel> = Model<any, any>

    • TargetModel extends Model<any, any, TargetModel> = Model<any, any>

    • ThroughModel extends Model<any, any, ThroughModel> = Model<any, any>

    • SourceKey extends string = any

    • TargetKey extends string = any

    Parameters

    Returns BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>

Properties

Private #private

#private: any

Readonly accessors

accessors: MultiAssociationAccessors

Readonly fromSourceToThrough

fromSourceToThrough: HasMany<SourceModel, ThroughModel, SourceKey, any, any>

Readonly fromSourceToThroughOne

fromSourceToThroughOne: HasOne<SourceModel, ThroughModel, SourceKey, any, any>

isAliased

isAliased: boolean

isSelfAssociation

isSelfAssociation: boolean

Readonly options

options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>

pairedWith

pairedWith: BelongsToMany<TargetModel, SourceModel, ThroughModel, TargetKey, SourceKey>

The corresponding association this entity is paired with.

Readonly parentAssociation

parentAssociation: null | Association<Model<any, any>, Model<any, any>, string, NormalizedAssociationOptions<string>>

A reference to the association that created this one.

source

source: ModelStatic<SourceModel>

target

target: ModelStatic<TargetModel>

Accessors

as

  • get as(): string

  • The identifier of the relation on the source model.

    Returns string

associationType

  • get associationType(): string

  • The type of the association. One of HasMany, BelongsTo, HasOne, BelongsToMany

    Returns string

foreignIdentifierField

  • get foreignIdentifierField(): string

  • The corresponding column name of otherKey

    Returns string

foreignKey

  • get foreignKey(): string

  • Returns string

fromTargetToThrough

  • get fromTargetToThrough(): HasMany<TargetModel, ThroughModel, TargetKey, any, any>

  • Returns HasMany<TargetModel, ThroughModel, TargetKey, any, any>

fromTargetToThroughOne

  • get fromTargetToThroughOne(): HasOne<TargetModel, ThroughModel, TargetKey, any, any>

  • Returns HasOne<TargetModel, ThroughModel, TargetKey, any, any>

fromThroughToSource

  • get fromThroughToSource(): BelongsTo<ThroughModel, SourceModel, any, SourceKey>

  • Returns BelongsTo<ThroughModel, SourceModel, any, SourceKey>

fromThroughToTarget

  • get fromThroughToTarget(): BelongsTo<ThroughModel, TargetModel, any, TargetKey>

  • Returns BelongsTo<ThroughModel, TargetModel, any, TargetKey>

identifier

  • get identifier(): string

  • Deprecated

    use foreignKey

    Returns string

identifierField

  • get identifierField(): string

  • The corresponding column name of foreignKey

    Returns string

isMultiAssociation

  • get isMultiAssociation(): boolean

  • Returns boolean

isSingleAssociation

  • get isSingleAssociation(): boolean

  • Deprecated

    negate isMultiAssociation instead

    Returns boolean

name

  • get name(): {
        plural: string;
        singular: string;
    }

  • Returns {
        plural: string;
        singular: string;
    }

    • plural: string
    • singular: string

otherKey

  • get otherKey(): string

  • The name of the Foreign Key attribute, located on the through table, that points to the Target model.

    Not to be confused with

    Link

    , which points to the Source model instead.

    Returns string

rootAssociation

scope

  • get scope(): undefined | AssociationScope

  • Returns undefined | AssociationScope

sourceKey

  • get sourceKey(): SourceKey

  • The name of the Attribute that the foreignKey fk (located on the Through Model) will reference on the Source model.

    Returns SourceKey

sourceKeyField

  • get sourceKeyField(): string

  • The name of the Column that the foreignKey fk (located on the Through Table) will reference on the Source model.

    Returns string

targetKey

  • get targetKey(): TargetKey

  • The name of the Attribute that the otherKey fk (located on the Through Model) will reference on the Target model.

    Returns TargetKey

targetKeyField

  • get targetKeyField(): string

  • The name of the Column that the otherKey fk (located on the Through Table) will reference on the Target model.

    Returns string

through

  • get through(): NormalizedThroughOptions<ThroughModel>

  • Returns NormalizedThroughOptions<ThroughModel>

throughModel

  • get throughModel(): ModelStatic<ThroughModel>

  • Returns ModelStatic<ThroughModel>

Static isMultiAssociation

  • get isMultiAssociation(): boolean

  • Returns boolean

Methods

add

  • Associate one or several rows with source instance. It will not un-associate any already associated instance that may be missing from newInstances.

    Parameters

    • sourceInstance: SourceModel

      source instance to associate new instances with

    • newInstancesOrPrimaryKeys: AllowArray<TargetModel | Exclude<TargetModel[TargetKey], any[]>>

      A single instance or primary key, or a mixed array of persisted instances or primary keys

    • Optional options: BelongsToManyAddAssociationsMixinOptions<TargetModel>

      Options passed to through.findAll, bulkCreate and update

    Returns Promise<void>

count

create

get

  • Get everything currently associated with this, using an optional where clause.

    See Model for a full explanation of options

    Parameters

    Returns Promise<TargetModel[]>

has

  • 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

    Parameters

    • sourceInstance: SourceModel

      source instance to check for an association with

    • targetInstancesOrPks: AllowArray<TargetModel | Exclude<TargetModel[TargetKey], any[]>>

      Can be an array of instances or their primary keys

    • Optional options: BelongsToManyHasAssociationMixinOptions<TargetModel>

      Options passed to getAssociations

    Returns Promise<boolean>

remove

  • Un-associate one or more instance(s).

    Parameters

    • sourceInstance: SourceModel

      instance to un associate instances with

    • targetInstanceOrPks: AllowArray<TargetModel | Exclude<TargetModel[TargetKey], any[]>>

      Can be an Instance or its primary key, or a mixed array of instances and primary keys

    • Optional options: BelongsToManyRemoveAssociationMixinOptions

      Options passed to through.destroy

    Returns Promise<void>

set

  • 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.

    Parameters

    • sourceInstance: SourceModel

      source instance to associate new instances with

    • newInstancesOrPrimaryKeys: AllowArray<TargetModel | Exclude<TargetModel[TargetKey], any[]>>

      A single instance or primary key, or a mixed array of persisted instances or primary keys

    • Optional options: BelongsToManySetAssociationsMixinOptions<TargetModel>

      Options passed to through.findAll, bulkCreate, update and destroy

    Returns Promise<void>

Private toInstanceArray

  • Private

    Normalize input

    Returns

    built objects

    Parameters

    • input: AllowArray<TargetModel | Exclude<TargetModel[TargetKey], any[]>>

      it may be array or single obj, instance or primary key

    Returns TargetModel[]

Static associate

Settings

Member Visibility

Theme

Generated using TypeDoc