Skip to main content
Version: Next

EntityRepository <T>

Hierarchy

Index

Constructors

constructor

Methods

aggregate

  • aggregate(pipeline: any[]): Promise<any[]>
  • Shortcut to driver's aggregate method. Available in MongoDriver only.


    Parameters

    • pipeline: any[]

    Returns Promise<any[]>

assign

  • Shortcut for wrap(entity).assign(data, { em })


    Type parameters

    Parameters

    Returns MergeSelected<Ent, Naked, keyof Data & string>

canPopulate

  • canPopulate(property: string): boolean
  • 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

    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 the options 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 from data. If no matching property exists, the whole data parameter will be passed. This means we can also define constructor(data: Partial<T>) and em.create() will pass the data into it (unless we have a property named data 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, use partial: 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 via persist: false option, or globally via persistOnCreate ORM config option.


    Type parameters

    • Convert: boolean = false

    Parameters

    Returns T

find

  • find<Hint, Fields, Excludes>(where: FilterQuery<T>, options?: FindOptions<T, Hint, Fields, Excludes>): Promise<Loaded<T, Hint, Fields, Excludes>[]>
  • Finds all entities matching your where query. You can pass additional options via the options parameter.


    Type parameters

    • Hint: string = never
    • Fields: string = *
    • Excludes: string = never

    Parameters

    Returns Promise<Loaded<T, Hint, Fields, Excludes>[]>

findAll

  • findAll<Hint, Fields, Excludes>(options?: FindAllOptions<T, Hint, Fields, Excludes>): Promise<Loaded<T, Hint, Fields, Excludes>[]>
  • 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

    Returns Promise<Loaded<T, Hint, Fields, Excludes>[]>

findAndCount

  • findAndCount<Hint, Fields, Excludes>(where: FilterQuery<T>, options?: FindOptions<T, Hint, Fields, Excludes>): Promise<[Loaded<T, Hint, Fields, Excludes>[], number]>
  • Calls em.find() and em.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

    Returns Promise<[Loaded<T, Hint, Fields, Excludes>[], number]>

findByCursor

  • Calls em.find() and em.count() with the same arguments (where applicable) and returns the results as Cursor object. Supports before, after, first and last options while disallowing limit and offset. Explicit orderBy option is required.

    Use first and after for forward pagination, or last and before for backward pagination.

    • first and last are numbers and serve as an alternative to offset, those options are mutually exclusive, use only one at a time
    • before and after 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

    Returns Promise<Cursor<T, Hint, Fields, Excludes>>

findOne

  • findOne<Hint, Fields, Excludes>(where: FilterQuery<T>, options?: FindOneOptions<T, Hint, Fields, Excludes>): Promise<null | Loaded<T, Hint, Fields, Excludes>>
  • Finds first entity matching your where query.


    Type parameters

    • Hint: string = never
    • Fields: string = *
    • Excludes: string = never

    Parameters

    Returns Promise<null | Loaded<T, 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 via options.failHandler locally or via Configuration.findOneOrFailHandler globally.


    Type parameters

    • Hint: string = never
    • Fields: string = *
    • Excludes: string = never

    Parameters

    Returns Promise<Loaded<T, Hint, Fields, Excludes>>

getCollection

  • getCollection(): Collection<T>
  • Returns Collection<T>

getEntityManager

getEntityName

  • getEntityName(): string
  • Returns string

getReference

  • getReference(id: T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T, options: Omit<GetReferenceOptions, wrapped> & { wrapped: true }): Ref<T>
  • getReference(id: (T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T) | (T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T)[]): T
  • getReference(id: T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T, options: Omit<GetReferenceOptions, wrapped> & { wrapped: false }): T
  • 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: T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T
    • options: Omit<GetReferenceOptions, wrapped> & { wrapped: true }

    Returns Ref<T>

insert

  • insert(data: T | RequiredEntityData<T>, options?: NativeInsertUpdateOptions<T>): Promise<T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T>
  • Fires native insert query. Calling this has no side effects on the context (identity map).


    Parameters

    Returns Promise<T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T>

insertMany

  • insertMany(data: T[] | RequiredEntityData<T>[], options?: NativeInsertUpdateOptions<T>): Promise<(T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T)[]>
  • Fires native insert query. Calling this has no side effects on the context (identity map).


    Parameters

    Returns Promise<(T extends { [PrimaryKeyProp]?: PK } ? PK extends keyof T ? ReadonlyPrimary<UnwrapPrimary<T[PK]>> : PK extends keyof T[] ? ReadonlyPrimary<PrimaryPropToType<T, PK>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T)[]>

map

  • Maps raw database result to an entity and merges it to this EntityManager.


    Parameters

    • result: EntityDictionary<T>
    • optionaloptions: { schema?: string }
      • optionalschema: string

    Returns T

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

    Returns T

nativeDelete

  • Fires native delete query. Calling this has no side effects on the context (identity map).


    Parameters

    Returns Promise<number>

nativeUpdate

  • Fires native update query. Calling this has no side effects on the context (identity map).


    Parameters

    Returns Promise<number>

populate

  • populate<Ent, Hint, Naked, Fields, Excludes>(entities: Ent, populate: false | AutoPath<Naked, Hint, ALL, 9>[], options?: EntityLoaderOptions<Naked, Fields, Excludes>): Promise<Ent extends object[] ? MergeLoaded<ArrayElement<Ent>, Naked, Hint, Fields, Excludes, false>[] : MergeLoaded<Ent, Naked, Hint, Fields, Excludes, false>>
  • 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 | T[]
    • Hint: string = never
    • Naked: unknown = FromEntityType<T>
    • Fields: string = *
    • Excludes: string = never

    Parameters

    Returns Promise<Ent extends object[] ? MergeLoaded<ArrayElement<Ent>, Naked, Hint, Fields, Excludes, false>[] : MergeLoaded<Ent, Naked, Hint, Fields, Excludes, false>>

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 either entityName together with the entity data, 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

    Returns Promise<T>

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

    Returns Promise<T[]>