typeorm-scoped
Description
✅ This lib supports Scopes for both Active Record pattern (working with Entitiies), and Data Mapper pattern (
working with Repositories).
It's very easy to use this lib. You can define scopes and default scopes for entities.
Installation
yarn add typeorm-scoped
# or
npm install typeorm-scoped --saveInitialization (Global Setup for Project)
Before usage you need to patch TypeORM before calling any database method.
import {patchSelectQueryBuilder} from 'typeorm-scope'
...
patchSelectQueryBuilder() // <-- call this function
...
const app = new Koa() // or const app = express() ...In NestJS you can call this function in main.ts, in bootstrap() function before creating app.
import {patchSelectQueryBuilder} from 'typeorm-scoped'
...
async function bootstrap() {
patchSelectQueryBuilder() // <-- call
...
const app = await NestFactory.create(AppModule, {...})
...Default Scopes
you can define a default scope(scopes) for an entity adding the @DefaultScopes({ ... }) decorator before
the @Entity().
import {Entity, PrimaryGeneratedColumn, Column, BaseEntity} from "typeorm"
import {Scopes, DefaultScopes} from "typeorm-scoped"
@DefaultScopes<User>({
existed: (qb, alias) => qb.andWhere(`${alias}.deletedAt IS NULL`),
...
})
@Entity()
export class User extends BaseEntity {
@PrimaryGeneratedColumn()
id: number
@Column()
name: string
@Column({nullable: true})
deletedAt?: Date
}Querying
DefaultScopes will work automatically and there shouldn't be any changes in your services or repositories. You can use
the EntityManager or any Repository or CustomRepository and the default scopes will automatically be added to
the resulting query. It will also work with queries created using the QueryBuilder. For example, the following snippet
User.find({where: {name: "John"}})
// or
userRepository.find({where: {name: "John"}})
// or with createQueryBuilder() ...will produce an SQL query like
SELECT "User"."id" AS "User_id", "User"."name" AS "User_name"
FROM "user" "User"
WHERE "User"."name" = ? AND "User"."deletedAt" IS NULL
-- PARAMETERS: ["John"]Custom Scopes
To define a scope(scopes) for an entity you need to add the @Scopes({ ... }) decorator before the @Entity().
import {Entity, PrimaryGeneratedColumn, Column} from "typeorm"
import {Scopes, DefaultScopes} from "typeorm-scoped"
import {ScopeEntity} from "./scope.entity";
@Scopes<User>({
females: (qb, alias) => qb.andWhere(`${alias}.gender = :g`, {g: "Female"}),
adultUsers: (qb, alias) => qb.andWhere(`${alias}.age > :adultAge`, {adultAge: 17}),
...
})
// You can also use @Scopes(...) and @DefaultScopes(...) together !
@Entity()
export class User extends ScopeEntity {
@PrimaryGeneratedColumn()
id: number
@Column()
name: string
@Column()
age: number
@Column()
gender: string // or GenderEnum -> "Male", "Female", ...
@Column({nullable: true})
deletedAt?: Date
}Active Record Pattern
If you use Active Record pattern, you need to extend from ScopeEntity:
@Scopes<User>({
...
})
@Entity()
export class User extends ScopeEntity { // <-- our ScopeEntity already extends from BaseEntity
...
}Data Mapper (Repository) Pattern
If you use Data Mapper(Repository) pattern, then for custom scopes you should use Custom Repositories, which should
be extends from ScopeRepository:
Typeorm version 2.x
@EntityRepository(User)
export class UserRepository extends ScopeRepository<User> { // <-- our ScopeRepository already extends from Repository<Entity>
...
}Typeorm version 3.x
// @Injectable() // <-- If you use NestJS
export class UserRepository extends ScopeRepository<User> {
constructor(private dataSource: DataSource) {
super(User, dataSource.createEntityManager());
}
}For NestJS
⚠ Important! In NestJS you will add @Injectable() on your custom repository UserRepository (for
version 3.x).
And then add it in your UserModule (if typeorm v2.x -> add into TypeOrmModule.forFeature function, if typeorm v3.x,
add into providers).
After that use it in services:
constructor(
...
private
readonly
userRepository: UserRepository
)
{
}Querying
You will use custom scopes like this:
userRepository.scoped("females", "adultUsers").find({where: {name: "John"}})
// or
User.scoped("females", "adultUsers").find({where: {name: "John"}})
// or with createQueryBuilder() ...will produce an SQL query like
SELECT "User"."id" AS "User_id", "User"."name" AS "User_name", "User"."age" AS "User_age", "User"."gender" AS "User_gender"
FROM "user" "User"
WHERE "User"."gender" = ? AND "User"."age" > ? AND "User"."name" = ?
-- PARAMETERS: ["Female", 17, "John"]Disabling Default Scopes
You are able to disable default scopes by calling a method unscoped.
// if you dont send parametrs to unscoped method, it unscoped all default scopes !!!
userRepository.unscoped().find({where: {name: "John"}})
// or unscope only specific default scopes
userRepository.unscoped("existed").find({where: {name: "John"}})
// or
User.unscoped().find({where: {name: "John"}})
...
// or with createQueryBuilder() ...
...You can also continue with scoped() method, like this:
userRepository.unscoped("existed").scoped("females").find({where: {name: "John"}})