sequelize-typescript 中文文档

安装

npm install sequelize
npm install @types/bluebird @types/node @types/validator
npm install reflect-metadata

npm install sequelize-typescript

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

⚠️ sequelize@4

npm install sequelize-typescript@0.6

升级到sequelize-typescript@1

破坏性更新

官方 TypeScript 支持

Sequelize 选项

作用域 选项

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

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

Repository 模式

模型定义

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

@Table

@Table({
 timestamps: true,
 ...
})
class Person extends Model<Person> {}

Table API

主键

@CreatedAt, @UpdatedAt, @DeletedAt

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

@Column

 @Column
 name: string;

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

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

Column API

事半功倍

类型推断

访问器

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

使用

配置

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],
});

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

globs 匹配

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

模型路径解析

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

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();
 },
});

//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<User> {
 @Column
 nickname: string;
}

user.model UserN -> false
user.model NUser -> false
user.model User -> true (User 会作为模型被添加)

export default class User extends Model<User> {}

build 和 create

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

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

find 和 update

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

模型关联

一对多

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

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

多对多

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

安全的跨表实例访问

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

一对一

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

同一模型的多种关联

@Table
class Book extends Model<Book> {
 @ForeignKey(() => Person)
 @Column
 authorId: number;
 @BelongsTo(() => Person)
 author: Person;
 @ForeignKey(() => Person)
 @Column
 proofreaderId: number;
 @BelongsTo(() => Person)
 proofreader: Person;
}
@Table
class Person extends Model<Person> {
 @HasMany(() => Book)
 writtenBooks: Book[];
 @HasMany(() => Book)
 proofedBooks: Book[];
}

 // in class "Books":
 @BelongsTo(() => Person, 'authorId')
 author: Person;
 @BelongsTo(() => Person, 'proofreaderId')
 proofreader: Person;
 // in class "Person":
 @HasMany(() => Book, 'authorId')
 writtenBooks: Book[];
 @HasMany(() => Book, 'proofreaderId')
 proofedBooks: Book[];

安全的使用自动生成函数

@Table
class ModelA extends Model<ModelA> {
 @HasMany(() => ModelB)
 bs: ModelB[];
}
@Table
class ModelB extends Model<ModelB> {
 @BelongsTo(() => ModelA)
 a: ModelA;
}

const modelA = new ModelA();
modelA.$set('bs', [ /* instance */]).then( /* ... */);
modelA.$add('b', /* instance */).then( /* ... */);
modelA.$get('bs').then( /* ... */);
modelA.$count('bs').then( /* ... */);
modelA.$has('bs').then( /* ... */);
modelA.$remove('bs', /* instance */ ).then( /* ... */);
modelA.$create('bs', /* value */ ).then( /* ... */);

索引

@Index

@Table
class Person extends Model<Person> {
 @Index // 用默认名称定义一个索引
 @Column
 name: string;
 @Index // 定义另一个索引
 @Column
 birthday: Date;
}

@Table
class Person extends Model<Person> {
 @Index('my-index') // 给 name 和 birthday 定义多列索引
 @Column
 name: string;
 @Index('my-index') // 把 birthday 字段添加到 my-index 索引
 @Column
 birthday: Date;
 @Index({
 // index options
 name: 'job-index',
 parser: 'my-parser',
 type: 'UNIQUE',
 unique: true,
 where: { isEmployee: true },
 concurrently: true,
 using: 'BTREE',
 operator: 'text_pattern_ops',
 prefix: 'test-',
 // index field options
 length: 10,
 order: 'ASC',
 collate: 'NOCASE',
 })
 @Column
 jobTitle: string;
 @Column
 isEmployee: boolean;
}

Index API

createIndexDecorator()

const SomeIndex = createIndexDecorator();
const JobIndex = createIndexDecorator({
 // index options
 name: 'job-index',
 parser: 'my-parser',
 type: 'UNIQUE',
 unique: true,
 where: { isEmployee: true },
 concurrently: true,
 using: 'BTREE',
 operator: 'text_pattern_ops',
 prefix: 'test-',
});
@Table
class Person extends Model<Person> {
 @SomeIndex // Add name to SomeIndex
 @Column
 name: string;
 @SomeIndex // Add birthday to SomeIndex
 @Column
 birthday: Date;
 @JobIndex({
 // index field options
 length: 10,
 order: 'ASC',
 collate: 'NOCASE',
 })
 @Column
 jobTitle: string;
 @Column
 isEmployee: boolean;
}

Repository 模式

如何开启 repository 模式?

const sequelize = new Sequelize({
 repositoryMode: true,
 ...,
});

如何使用 repository 模式?

const userRepository = sequelize.getRepository(User);
const luke = await userRepository.create({name: 'Luke Skywalker'});
const luke = await userRepository.findOne({where: {name: 'luke'}});

如何在 repository 模式下使用关联?

const userRepository = sequelize.getRepository(User);
const addressRepository = sequelize.getRepository(Address);
userRepository.find({include: [addressRepository]});
userRepository.create({name: 'Bear'}, {include: [addressRepository]});

repository 模式的限制

@Scopes(() => ({
 // includes
 withAddress: {
 include: [() => Address],
 },
 // nested scopes
 withAddressIncludingLatLng: {
 include: [() => Address.scope('withLatLng')],
 }
}))
@Table
class User extends Model<User> {}

模型校验

异常处理

Example

const HEX_REGEX = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;
@Table
export class Shoe extends Model<Shoe> {
 @IsUUID(4)
 @PrimaryKey
 @Column
 id: string;
 @Equals('lala')
 @Column
 readonly key: string;
 @Contains('Special')
 @Column
 special: string;
 @Length({min: 3, max: 15})
 @Column
 brand: string;
 @IsUrl
 @Column
 brandUrl: string;
 @Is('HexColor', (value) => {
 if (!HEX_REGEX.test(value)) {
 throw new Error(`"${value}" is not a hex color value.`);
 }
 })
 @Column
 primaryColor: string;
 @Is(function hexColor(value: string): void {
 if (!HEX_REGEX.test(value)) {
 throw new Error(`"${value}" is not a hex color value.`);
 }
 })
 @Column
 secondaryColor: string;
 @Is(HEX_REGEX)
 @Column
 tertiaryColor: string;
 @IsDate
 @IsBefore('2017-02-27')
 @Column
 producedAt: Date;
}

作用域

@DefaultScope 和 @Scopes

@DefaultScope(() => ({
 attributes: ['id', 'primaryColor', 'secondaryColor', 'producedAt']
}))
@Scopes(() => ({
 full: {
 include: [Manufacturer]
 },
 yellow: {
 where: {primaryColor: 'yellow'}
 }
}))
@Table
export class ShoeWithScopes extends Model<ShoeWithScopes> {
 @Column
 readonly secretKey: string;
 @Column
 primaryColor: string;
 @Column
 secondaryColor: string;
 @Column
 producedAt: Date;
 @ForeignKey(() => Manufacturer)
 @Column
 manufacturerId: number;
 @BelongsTo(() => Manufacturer)
 manufacturer: Manufacturer;
}

Hooks 钩子

@Table
export class Person extends Model<Person> {
 @Column
 name: string;
 @BeforeUpdate
 @BeforeCreate
 static makeUpperCase(instance: Person) {
 // this will be called when an instance is created or updated
 instance.name = instance.name.toLocaleUpperCase();
 }
 @BeforeCreate
 static addUnicorn(instance: Person) {
 // this will also be called when an instance is created
 instance.name += ' 🦄';
 }
}

为何使用 () => Model?

风格推荐和限制

每个模型对应一个 Sequelize 实例 (除 repository 模式)

每个文件存放一个模型类

文件压缩

贡献

改进文档