EntityRepository <Entity>
Hierarchy
- EntityRepository<Entity>
- EntityRepository
Index
Constructors
constructor
Type parameters
- Entity: object
Parameters
em: SqlEntityManager<AbstractSqlDriver<AbstractSqlConnection, AbstractSqlPlatform>>
entityName: EntityName<Entity>
Returns SqlEntityRepository<Entity>
Methods
assign
Type parameters
- Ent: object | { [___loadedType]?: Entity } | { [___selectedType]?: Entity }
- Naked: unknown = FromEntityType<Ent>
- Convert: boolean = false
- Data: EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>
Parameters
entity: Ent | Partial<Ent>
data: Data & IsSubset<EntityData<Naked, Convert>, Data>
optionaloptions: AssignOptions<Convert>
Returns MergeSelected<Ent, Naked, keyof Data & string>
canPopulate
Checks whether given property can be populated on the entity.
Parameters
property: string
Returns boolean
count
Returns total number of entities matching your
where
query.Type parameters
- Hint: string = never
Parameters
where: FilterQuery<Entity> = ...
options: CountOptions<Entity, Hint> = {}
Returns Promise<number>
create
Creates new instance of given entity and populates it with given data. The entity constructor will be used unless you provide
{ managed: true }
in theoptions
parameter. The constructor will be given parameters based on the defined constructor of the entity. If the constructor parameter matches a property name, its value will be extracted fromdata
. If no matching property exists, the wholedata
parameter will be passed. This means we can also defineconstructor(data: Partial<T>)
andem.create()
will pass the data into it (unless we have a property nameddata
too).The parameters are strictly checked, you need to provide all required properties. You can use
OptionalProps
symbol to omit some properties from this check without making them optional. Alternatively, usepartial: true
in the options to disable the strict checks for required properties. This option has no effect on runtime.The newly created entity will be automatically marked for persistence via
em.persist
unless you disable this behavior, either locally viapersist: false
option, or globally viapersistOnCreate
ORM config option.Type parameters
- Convert: boolean = false
Parameters
data: RequiredEntityData<Entity, never, Convert>
optionaloptions: CreateOptions<Convert>
Returns Entity
createQueryBuilder
Creates a QueryBuilder instance
Type parameters
- RootAlias: string = never
Parameters
optionalalias: RootAlias
Returns QueryBuilder<Entity, RootAlias, never, never>
find
Finds all entities matching your
where
query. You can pass additional options via theoptions
parameter.Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
where: FilterQuery<Entity>
optionaloptions: FindOptions<Entity, Hint, Fields, Excludes>
Returns Promise<Loaded<Entity, Hint, Fields, Excludes>[]>
findAll
Finds all entities of given type. You can pass additional options via the
options
parameter.Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
optionaloptions: FindAllOptions<Entity, Hint, Fields, Excludes>
Returns Promise<Loaded<Entity, Hint, Fields, Excludes>[]>
findAndCount
Calls
em.find()
andem.count()
with the same arguments (where applicable) and returns the results as tuple where first element is the array of entities, and the second is the count.Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
where: FilterQuery<Entity>
optionaloptions: FindOptions<Entity, Hint, Fields, Excludes>
Returns Promise<[Loaded<Entity, Hint, Fields, Excludes>[], number]>
findByCursor
Calls
em.find()
andem.count()
with the same arguments (where applicable) and returns the results as Cursor object. Supportsbefore
,after
,first
andlast
options while disallowinglimit
andoffset
. ExplicitorderBy
option is required.Use
first
andafter
for forward pagination, orlast
andbefore
for backward pagination.first
andlast
are numbers and serve as an alternative tooffset
, those options are mutually exclusive, use only one at a timebefore
andafter
specify the previous cursor value, it can be one of the:Cursor
instance- opaque string provided by
startCursor/endCursor
properties - POJO/entity instance
const currentCursor = await em.findByCursor(User, {}, {
first: 10,
after: previousCursor, // cursor instance
orderBy: { id: 'desc' },
});
// to fetch next page
const nextCursor = await em.findByCursor(User, {}, {
first: 10,
after: currentCursor.endCursor, // opaque string
orderBy: { id: 'desc' },
});
// to fetch next page
const nextCursor2 = await em.findByCursor(User, {}, {
first: 10,
after: { id: lastSeenId }, // entity-like POJO
orderBy: { id: 'desc' },
});The
Cursor
object provides the following interface:Cursor<User> {
items: [
User { ... },
User { ... },
User { ... },
],
totalCount: 50,
startCursor: 'WzRd',
endCursor: 'WzZd',
hasPrevPage: true,
hasNextPage: true,
}Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
where: FilterQuery<Entity>
options: FindByCursorOptions<Entity, Hint, Fields, Excludes>
Returns Promise<Cursor<Entity, Hint, Fields, Excludes>>
findOne
Finds first entity matching your
where
query.Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
where: FilterQuery<Entity>
optionaloptions: FindOneOptions<Entity, Hint, Fields, Excludes>
Returns Promise<null | Loaded<Entity, Hint, Fields, Excludes>>
findOneOrFail
Finds first entity matching your
where
query. If nothing is found, it will throw an error. You can override the factory for creating this method viaoptions.failHandler
locally or viaConfiguration.findOneOrFailHandler
globally.Type parameters
- Hint: string = never
- Fields: string = *
- Excludes: string = never
Parameters
where: FilterQuery<Entity>
optionaloptions: FindOneOrFailOptions<Entity, Hint, Fields, Excludes>
Returns Promise<Loaded<Entity, Hint, Fields, Excludes>>
getEntityManager
Returns the underlying EntityManager instance
Returns SqlEntityManager<AbstractSqlDriver<AbstractSqlConnection, AbstractSqlPlatform>>
getEntityName
Returns string
getKnex
Returns configured knex instance.
Parameters
optionaltype: ConnectionType
Returns Knex<any, any[]>
getReference
Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
Parameters
id: Entity extends { [PrimaryKeyProp]?: PK } ? PK extends keyof Entity ? ReadonlyPrimary<UnwrapPrimary<Entity[PK]>> : PK extends keyof Entity[] ? ReadonlyPrimary<PrimaryPropToType<Entity, PK>> : PK : Entity extends { _id?: PK } ? string | ReadonlyPrimary<PK> : Entity extends { uuid?: PK } ? ReadonlyPrimary<PK> : Entity extends { id?: PK } ? ReadonlyPrimary<PK> : Entity
options: Omit<GetReferenceOptions, wrapped> & { wrapped: true }
Returns Ref<Entity>
insert
Fires native insert query. Calling this has no side effects on the context (identity map).
Parameters
data: Entity | RequiredEntityData<Entity>
optionaloptions: NativeInsertUpdateOptions<Entity>
Returns Promise<Entity extends { [PrimaryKeyProp]?: PK } ? PK extends keyof Entity ? ReadonlyPrimary<UnwrapPrimary<Entity[PK]>> : PK extends keyof Entity[] ? ReadonlyPrimary<PrimaryPropToType<Entity, PK>> : PK : Entity extends { _id?: PK } ? string | ReadonlyPrimary<PK> : Entity extends { uuid?: PK } ? ReadonlyPrimary<PK> : Entity extends { id?: PK } ? ReadonlyPrimary<PK> : Entity>
insertMany
Fires native insert query. Calling this has no side effects on the context (identity map).
Parameters
data: Entity[] | RequiredEntityData<Entity>[]
optionaloptions: NativeInsertUpdateOptions<Entity>
Returns Promise<(Entity extends { [PrimaryKeyProp]?: PK } ? PK extends keyof Entity ? ReadonlyPrimary<UnwrapPrimary<Entity[PK]>> : PK extends keyof Entity[] ? ReadonlyPrimary<PrimaryPropToType<Entity, PK>> : PK : Entity extends { _id?: PK } ? string | ReadonlyPrimary<PK> : Entity extends { uuid?: PK } ? ReadonlyPrimary<PK> : Entity extends { id?: PK } ? ReadonlyPrimary<PK> : Entity)[]>
map
Maps raw database result to an entity and merges it to this EntityManager.
Parameters
result: EntityDictionary<Entity>
optionaloptions: { schema?: string }
optionalschema: string
Returns Entity
merge
Merges given entity to this EntityManager so it becomes managed. You can force refreshing of existing entities via second parameter. By default it will return already loaded entities without modifying them.
Parameters
data: Entity | EntityData<Entity>
optionaloptions: MergeOptions
Returns Entity
nativeDelete
Fires native delete query. Calling this has no side effects on the context (identity map).
Parameters
where: FilterQuery<Entity>
optionaloptions: DeleteOptions<Entity>
Returns Promise<number>
nativeUpdate
Fires native update query. Calling this has no side effects on the context (identity map).
Parameters
where: FilterQuery<Entity>
data: EntityData<Entity>
optionaloptions: UpdateOptions<Entity>
Returns Promise<number>
populate
Loads specified relations in batch. This will execute one query for each relation, that will populate it on all the specified entities.
Type parameters
- Ent: object | Entity[]
- Hint: string = never
- Naked: unknown = FromEntityType<Entity>
- Fields: string = *
- Excludes: string = never
Parameters
entities: Ent
populate: false | AutoPath<Naked, Hint, ALL, 9>[]
optionaloptions: EntityLoaderOptions<Naked, Fields, Excludes>
Returns Promise<Ent extends object[] ? MergeLoaded<ArrayElement<Ent>, Naked, Hint, Fields, Excludes, false>[] : MergeLoaded<Ent, Naked, Hint, Fields, Excludes, false>>
qb
Shortcut for
createQueryBuilder()
Type parameters
- RootAlias: string = never
Parameters
optionalalias: RootAlias
Returns QueryBuilder<Entity, RootAlias, never, never>
upsert
Creates or updates the entity, based on whether it is already present in the database. This method performs an
insert on conflict merge
query ensuring the database is in sync, returning a managed entity instance. The method accepts eitherentityName
together with the entitydata
, or just entity instance.// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
const author = await em.getRepository(Author).upsert({ email: 'foo@bar.com', age: 33 });The entity data needs to contain either the primary key, or any other unique property. Let's consider the following example, where
Author.email
is a unique property:// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
// select "id" from "author" where "email" = 'foo@bar.com'
const author = await em.getRepository(Author).upsert({ email: 'foo@bar.com', age: 33 });Depending on the driver support, this will either use a returning query, or a separate select query, to fetch the primary key if it's missing from the
data
.If the entity is already present in current context, there won't be any queries - instead, the entity data will be assigned and an explicit
flush
will be required for those changes to be persisted.Type parameters
- Fields: string = any
Parameters
optionalentityOrData: Entity | EntityData<Entity>
optionaloptions: UpsertOptions<Entity, Fields>
Returns Promise<Entity>
upsertMany
Creates or updates the entity, based on whether it is already present in the database. This method performs an
insert on conflict merge
query ensuring the database is in sync, returning a managed entity instance.// insert into "author" ("age", "email") values (33, 'foo@bar.com') on conflict ("email") do update set "age" = 41
const authors = await em.getRepository(Author).upsertMany([{ email: 'foo@bar.com', age: 33 }, ...]);The entity data needs to contain either the primary key, or any other unique property. Let's consider the following example, where
Author.email
is a unique property:// insert into "author" ("age", "email") values (33, 'foo@bar.com'), (666, 'lol@lol.lol') on conflict ("email") do update set "age" = excluded."age"
// select "id" from "author" where "email" = 'foo@bar.com'
const author = await em.getRepository(Author).upsertMany([
{ email: 'foo@bar.com', age: 33 },
{ email: 'lol@lol.lol', age: 666 },
]);Depending on the driver support, this will either use a returning query, or a separate select query, to fetch the primary key if it's missing from the
data
.If the entity is already present in current context, there won't be any queries - instead, the entity data will be assigned and an explicit
flush
will be required for those changes to be persisted.Type parameters
- Fields: string = any
Parameters
optionalentitiesOrData: EntityData<Entity>[] | Entity[]
optionaloptions: UpsertManyOptions<Entity, Fields>
Returns Promise<Entity[]>
Shortcut for
wrap(entity).assign(data, { em })