sequelize-typescript

Decorators and some other features for sequelize (v6).

Installation

Model Definition

@Table API

@Column API

Usage

Configuration

globs

Model-path resolving

Model association

One-to-many

Many-to-many

One-to-one

@ForeignKey, @BelongsTo, @HasMany, @HasOne, @BelongsToMany API

Generated getter and setter

Multiple relations of same models

Indexes

@Index API

createIndexDecorator() API

Repository mode

How to enable repository mode?

How to use repository mode?

How to use associations with repository mode?

Limitations of repository mode

Model validation

Scopes

Hooks

Why () => Model?

Recommendations and limitations

Installation

this assumes usage of sequelize@6

sequelize-typescript* requires sequelize

additional typings as documented here and reflect-metadata

``` shell
npm install --save-dev @types/node @types/validator
npm install sequelize reflect-metadata sequelize-typescript
```

Your tsconfig.json needs the following flags:

``` json
"target": "es6", // or a more recent ecmascript version
"experimentalDecorators": true,
"emitDecoratorMetadata": true
```

Sequelize Options

SequelizeConfig renamed to SequelizeOptions

modelPaths property renamed to models

Scopes Options

The @Scopes and @DefaultScope decorators now take lambda's as options

``` ts
@DefaultScope(() => ({...}))
@Scopes(() => ({...}))
```

instead of deprecated way:

``` ts
@DefaultScope({...})
@Scopes({...}))
```

Model definition

``` ts
import { Table, Column, Model, HasMany } from 'sequelize-typescript';
@Table
class Person extends Model {
@Column
name: string;
@Column
birthday: Date;
@HasMany(() => Hobby)
hobbies: Hobby[];
}
```

Less strict

``` ts
import { Table, Model } from 'sequelize-typescript';
@Table
class Person extends Model {}
```

More strict

``` ts
import { Optional } from 'sequelize';
import { Table, Model } from 'sequelize-typescript';
interface PersonAttributes {
id: number;
name: string;
}
interface PersonCreationAttributes extends Optional<PersonAttributes, 'id'> {}
@Table
class Person extends Model<PersonAttributes, PersonCreationAttributes> {}
```

The model needs to extend the Model class and has to be annotated with the @Table decorator. All properties that should appear as a column in the database require the @Column annotation.

See more advanced example here.

@Table

The @Table annotation can be used without passing any parameters. To specify some more define options, use an object literal (all define options from sequelize are valid):

``` ts
@Table({
timestamps: true,
...
})
class Person extends Model {}
```

Table API

Decorator	Description
:---	:---
@Table	sets options.tableName=<CLASS_NAME> and options.modelName=<CLASS_NAME> automatically
@Table(options: DefineOptions)	sets define options (also sets options.tableName=<CLASS_NAME> and options.modelName=<CLASS_NAME> if not already defined by define options)

Primary key

A primary key (id ) will be inherited from base class Model. This primary key is by default an INTEGER and has autoIncrement=true (This behaviour is a native sequelize thing). The id can easily be overridden by marking another attribute as primary key. So either set @Column({primaryKey: true}) or use @PrimaryKey together with @Column.

@CreatedAt, @UpdatedAt, @DeletedAt

Annotations to define custom and type safe createdAt, updatedAt and deletedAt attributes:

``` ts
@CreatedAt
creationDate: Date;
@UpdatedAt
updatedOn: Date;
@DeletedAt
deletionDate: Date;
```

Decorator	Description
:---	:---
@CreatedAt	sets timestamps=true and createdAt='creationDate'
@UpdatedAt	sets timestamps=true and updatedAt='updatedOn'
@DeletedAt	sets timestamps=true, paranoid=true and deletedAt='deletionDate'

@Column

The @Column annotation can be used without passing any parameters. But therefore it is necessary that the js type can be inferred automatically (see Type inference for details).

``` ts
@Column
name: string;
```

If the type cannot or should not be inferred, use:

``` ts
import {DataType} from 'sequelize-typescript';
@Column(DataType.TEXT)
name: string;
```

Or for a more detailed column description, use an object literal (all attribute options from sequelize are valid):

``` ts
@Column({
type: DataType.FLOAT,
comment: 'Some value',
...
})
value: number;
```

Column API

Decorator	Description
:---	:---
@Column	tries to infer dataType from js type
@Column(dataType: DataType)	sets dataType explicitly
@Column(options: AttributeOptions)	sets attribute options

Shortcuts

If you're in love with decorators: sequelize-typescriptprovides some more of them. The following decorators can be used together with the @Column annotation to make some attribute options easier available:

Decorator	Description	Options
:---	:---	:---
@AllowNull(allowNull?: boolean)	sets attribute.allowNull (default is true)
@AutoIncrement	sets attribute.autoIncrement=true
@Unique(options? UniqueOptions)	sets attribute.unique=true	UniqueOptions
@Default(value: any)	sets attribute.defaultValue to specified value
@PrimaryKey	sets attribute.primaryKey=true
@Comment(value: string)	sets attribute.comment to specified string
Validate annotations	see Model validation

Type inference

The following types can be automatically inferred from javascript type. Others have to be defined explicitly.

Design type	Sequelize data type
:---	:---
string	STRING
boolean	BOOLEAN
number	INTEGER
bigint	BIGINT
Date	DATE
Buffer	BLOB

Accessors

Get/set accessors do work as well

``` ts
@Table
class Person extends Model {
@Column
get name(): string {
return 'My name is ' + this.getDataValue('name');
}
set name(value: string) {
this.setDataValue('name', value);
}
}
```

Usage

Except for minor variations sequelize-typescriptwill work like pure sequelize. (See sequelize docs )

Configuration

To make the defined models available, you have to configure a Sequelize instance from sequelize-typescript (!).

``` ts
import { Sequelize } from 'sequelize-typescript';
const sequelize = new Sequelize({
database: 'some_db',
dialect: 'sqlite',
username: 'root',
password: '',
storage: ':memory:',
models: [__dirname + '/models'], // or [Player, Team],
});
```

Before you can use your models you have to tell sequelize where they can be found. So either set models in the sequelize config or add the required models later on by calling sequelize.addModels([Person]) or sequelize.addModels([__dirname + '/models']) :

``` ts
sequelize.addModels([Person]);
sequelize.addModels(['path/to/models']);
```

globs

``` ts
import {Sequelize} from 'sequelize-typescript';
const sequelize = new Sequelize({
...
models: [__dirname + '/**/*.model.ts']
});
// or
sequelize.addModels([__dirname + '/**/*.model.ts']);
```

Model-path resolving

A model is matched to a file by its filename. E.g.

``` ts
// File User.ts matches the following exported model.
export class User extends Model {}
```

This is done by comparison of the filename against all exported members. The matching can be customized by specifying the modelMatch function in the configuration object.

For example, if your models are named user.model.ts, and your class is called User, you can match these two by using the following function:

``` ts
import {Sequelize} from 'sequelize-typescript';
const sequelize = new Sequelize({
models: [__dirname + '/models/**/*.model.ts']
modelMatch: (filename, member) => {
return filename.substring(0, filename.indexOf('.model')) === member.toLowerCase();
},
});
```

For each file that matches the *.model.ts pattern, the modelMatch function will be called with its exported members. E.g. for the following file

``` ts
//user.model.ts
import {Table, Column, Model} from 'sequelize-typescript';
export const UserN = 'Not a model';
export const NUser = 'Not a model';
@Table
export class User extends Model {
@Column
nickname: string;
}
```

The modelMatch function will be called three times with the following arguments.

``` sh
user.model UserN -> false
user.model NUser -> false
user.model User -> true (User will be added as model)
```

Another way to match model to file is to make your model the default export.

``` ts
export default class User extends Model {}
```

⚠️When using paths to add models, keep in mind that they will be loaded during runtime. This means that the path may differ from development time to execution time. For instance, using .ts extension within paths will only work together with ts-node.

Build and create

Instantiation and inserts can be achieved in the good old sequelize way

``` ts
const person = Person.build({ name: 'bob', age: 99 });
person.save();
Person.create({ name: 'bob', age: 99 });
```

but sequelize-typescriptalso makes it possible to create instances with new :

``` ts
const person = new Person({ name: 'bob', age: 99 });
person.save();
```

Find and update

Finding and updating entries does also work like using native sequelize. So see sequelize docs for more details.

``` ts
Person.findOne().then((person) => {
person.age = 100;
return person.save();
});
Person.update(
{
name: 'bobby',
},
{ where: { id: 1 } }
).then(() => {});
```

Model association

Relations can be described directly in the model by the @HasMany, @HasOne, @BelongsTo, @BelongsToMany and @ForeignKey annotations.

One-to-many

``` ts
@Table
class Player extends Model {
@Column
name: string;
@Column
num: number;
@ForeignKey(() => Team)
@Column
teamId: number;
@BelongsTo(() => Team)
team: Team;
}
@Table
class Team extends Model {
@Column
name: string;
@HasMany(() => Player)
players: Player[];
}
```

That's all, sequelize-typescriptdoes everything else for you. So when retrieving a team by find

``` ts
Team.findOne({ include: [Player] }).then((team) => {
team.players.forEach((player) => console.log(`Player ${player.name}`));
});
```

the players will also be resolved (when passing include: Player to the find options)

Many-to-many

``` ts
@Table
class Book extends Model {
@BelongsToMany(() => Author, () => BookAuthor)
authors: Author[];
}
@Table
class Author extends Model {
@BelongsToMany(() => Book, () => BookAuthor)
books: Book[];
}
@Table
class BookAuthor extends Model {
@ForeignKey(() => Book)
@Column
bookId: number;
@ForeignKey(() => Author)
@Column
authorId: number;
}
```

Type safe through-table instance access

To access the through-table instance (instanceOf BookAuthor in the upper example) type safely, the type need to be set up manually. For Author model it can be achieved like so:

``` ts
@BelongsToMany(() => Book, () => BookAuthor)
books: Array<Book & {BookAuthor: BookAuthor}>;
```

One-to-one

For one-to-one use @HasOne(...) (foreign key for the relation exists on the other model) and @BelongsTo(...) (foreign key for the relation exists on this model)

@ForeignKey, @BelongsTo, @HasMany, @HasOne, @BelongsToMany API

Decorator	Description
:---	:---
@ForeignKey(relatedModelGetter: () => typeof Model)	marks property as foreignKey for related class
@BelongsTo(relatedModelGetter: () => typeof Model)	sets SourceModel.belongsTo(RelatedModel, ...) while as is key of annotated property and foreignKey is resolved from source class
@BelongsTo(relatedModelGetter: () => typeof Model, foreignKey: string)	sets SourceModel.belongsTo(RelatedModel, ...) while as is key of annotated property and foreignKey is explicitly specified value
@BelongsTo(relatedModelGetter: () => typeof Model, options: AssociationOptionsBelongsTo)	sets SourceModel.belongsTo(RelatedModel, ...) while as is key of annotated property and options are additional association options
@HasMany(relatedModelGetter: () => typeof Model)	sets SourceModel.hasMany(RelatedModel, ...) while as is key of annotated property and foreignKey is resolved from target related class
@HasMany(relatedModelGetter: () => typeof Model, foreignKey: string)	sets SourceModel.hasMany(RelatedModel, ...) while as is key of annotated property and foreignKey is explicitly specified value
@HasMany(relatedModelGetter: () => typeof Model, options: AssociationOptionsHasMany)	sets SourceModel.hasMany(RelatedModel, ...) while as is key of annotated property and options are additional association options
@HasOne(relatedModelGetter: () => typeof Model)	sets SourceModel.hasOne(RelatedModel, ...) while as is key of annotated property and foreignKey is resolved from target related class
@HasOne(relatedModelGetter: () => typeof Model, foreignKey: string)	sets SourceModel.hasOne(RelatedModel, ...) while as is key of annotated property and foreignKey is explicitly specified value
@HasOne(relatedModelGetter: () => typeof Model, options: AssociationOptionsHasOne)	sets SourceModel.hasOne(RelatedModel, ...) while as is key of annotated property and options are additional association options
@BelongsToMany(relatedModelGetter: () => typeof Model, through: (() => typeof Model))	sets SourceModel.belongsToMany(RelatedModel, {through: ThroughModel, ...}) while as is key of annotated property and foreignKey/otherKey is resolved from through class
@BelongsToMany(relatedModelGetter: () => typeof Model, through: (() => typeof Model), foreignKey: string)	sets SourceModel.belongsToMany(RelatedModel, {through: ThroughModel, ...}) while as is key of annotated property, foreignKey is explicitly specified value and otherKey is resolved from through class
@BelongsToMany(relatedModelGetter: () => typeof Model, through: (() => typeof Model), foreignKey: string, otherKey: string)	sets SourceModel.belongsToMany(RelatedModel, {through: ThroughModel, ...}) while as is key of annotated property and foreignKey/otherKey are explicitly specified values
@BelongsToMany(relatedModelGetter: () => typeof Model, through: string, foreignKey: string, otherKey: string)	sets SourceModel.belongsToMany(RelatedModel, {through: throughString, ...}) while as is key of annotated property and foreignKey/otherKey are explici