typeorm-linq-repository

Wraps TypeORM repository pattern and QueryBuilder using fluent, LINQ-style queries.

What's New

Two new libraries, typeorm-linq-repository-testing and typeorm-linq-repository-testing-nestjs, now make it easier to unit test LinqRepository.

typeorm-linq-repository-testing-nestjs contains a more "complete" example of usage since it has more practical usage in the context of another framework, but typeorm-linq-repository-testing provides the raw components if you need to build something similar for another framework.

Latest Changes

As of version 2.0.0:

Due to breaking changes in TypeORM, namely the removal of getConnectionManager, the constructor for LinqRepository now requires the TypeORM DataSource in addition to the entity model. Likewise, since individually managed DataSource objects replace the ConnectionManager paradigm, RepositoryOptions now no longer contains the connectionName property.

Older Changes

As of version 1.1.3:

A fix was implemented so that if a where with mapped properties was called that was not in the following format (without parentheses):

.where(e => e.relationshipOne.map(r => r.relationshipTwo))

an error would occur.

Now, the following is allowed (with parentheses):

.where((e) => e.relationshipOne.map((r) => r.relationshipTwo))

As of version 1.1.2:

A fix was implemented to make from, inSelected, and notInSelected compatible with entities that do not contain a property named id that is a number.

As of version 1.1.0:

A fix was implemented in which entities not implementing a property named id were not compatible with LinqRepository. To mitigate this, id was removed from the base EntityBase type. In addition:

• RepositoryOptions now allows you to specify the name of the entity's primary key in case it is not id so that create may still be used with the option autoGenerateId enabled and getById may be used. To do so:

new LinqRepository(Entity, {
    primaryKey: e => e.entityId
});

As of version 1.0.1:

A fix/improvement was implemented in which included or thenIncluded relations may now be filtered by later using join or thenJoin along with a where. See the Filtering Included Relations section below.

As of version 1.0.0:

• The update method is now an alias for the new upsert method. This change was made to clarify that typeorm-linq-repository calls TypeORM's save method, which performs upserts on the provided entities. The update method was left in place to avoid breaking changes.

• The ts-simple-nameof dependency was updated to strip assertion operators from parsed property names in order to allow the following:

await fooRepository
    .getAll()
    .where(foo => foo.bar!.baz)
    .equal(value);

which is sometimes necessary when using strict null checks, for instance when a relationship is typed as optional/nullable.

• LinqRepository now exposes a typeormRepository property, which allows you to use the underlying TypeORM Repository if you need to access methods not available via the createQueryBuilder method. The createQueryBuilder method, although now redundant, was left in place to avoid breaking changes.

In version 1.0.0-alpha.23, a bug was fixed in which a call to the where method on a non-joined query with multiple joins in the property selector (i.e. .where(p => p.comments.map(c => c.user.email))) would use the wrong alias and throw an error.

As of version 1.0.0-alpha.22:

• Checking for existence or absence of relations in an array of relations (or existence or absense of relations that meet a certain condition) is now supported!

For example:

const accessiblePosts = await postRepository
    // Get posts where...
    .getAll()
    // Note: Must use groupBy method to check relations.
    .groupBy(p => p.id)
    // ...no tags exist...
    .whereNone(p => p.tags, t => t.id)
    // ...or the post contains the tag being searched for.
    .orAny(p => p.tags, t => t.id, t => t.id)
    .equal(tagId);

Notice the second argument in the whereNone and orAny methods. This argument simply serves as an arbitrary primitive property to COUNT relationships in the HAVING statement(s) resulting from those methods. This was done in order to not restrict entities to have a primary key named id; although that restriction would have conveniently shortened the signature of the method, not all schemas may name primary keys id.

See the Checking Relations section below.

• A bug was fixed in usage of the where method following the include or thenInclude methods. Previously, although the interface claimed that a where method following an include method operated on the query's base type, the query actually continued using the last included property type.

Foreword

This is a work in progress. This project has just recently come out of alpha and should be treated as such. That being said, it has received some massive updates for a wide range of query complexity and is periodically being updated for bug fixes, so I hope it will continue to see lots of use and continue to mature.

typeorm-linq-repository's queries handle simple includes, joins, and join conditions very well and now has the capability to take on more complex queries. The only way it will continue to mature is to have its limits tested see some issues and pull requests come in.

typeorm-linq-repository has been tested with Postgres and MySQL, but since TypeORM manages the ubiquity of queries amongst different database engines, it should work just fine with all database engines. Please feel free to give it a try and provide as much testing as possible for it!

Prerequisites

TypeORM, a code-first relational database ORM for typescript, is the foundation of this project. If you are unfamiliar with TypeORM, I strongly suggest that you check it out.

Installation

To add typeorm-linq-repository and its dependencies to your project using NPM:

npm install --save typeorm typeorm-linq-repository

Linq Repository

LinqRepository is the repository that is constructed to interact with the table represented by the entity used as the type argument for the repository.

LinqRepository takes the TypeORM DataSource containing the connection to the entity's datbase and a class type representing a TypeORM model as its constructor argument.

import { LinqRepository } from "typeorm-linq-repository";
import { dataSource } from "path-to-initialized-data-source";
import { User } from "../../entities/User";

const userRepository: LinqRepository<User> = new LinqRepository(dataSource, User);

Repository Options

To modify default behavior when setting up a repository, use RepositoryOptions.

Repository options include:

• autoGenerateId: A boolean value indicating whether the entity implements a primary key that is auto-generated. Default is true.
• primaryKey: A lambda function providing the entity's primary key property if it is not named id.

new LinqRepository(dataSource, Entity, {
    // This entity has a primary key that is not auto-generated.
    autoGenerateId: false,
    // This entity has a primary key whose name is not "id".
    primaryKey: e => e.entityId
});

Or as a repository extending LinqRepository:

import { DataSource } from "typeorm";
import { LinqRepository } from "typeorm-linq-repository";
import { Entity } from "../entities/Entity";

export class EntityRepository extends LinqRepository<Entity> {
    public constructor(dataSource: DataSource) {
        super(dataSource, Entity, {
            // This entity has a primary key that is not auto-generated.
            autoGenerateId: false,
            // This entity has a primary key whose name is not "id".
            primaryKey: e => e.entityId
        });
    }
}

Injecting LinqRepository

Protip: You can easily make LinqRepository injectable! For example, using InversifyJS:

import { decorate, injectable, unmanaged } from "inversify";
import { LinqRepository } from "typeorm-linq-repository";

decorate(injectable(), LinqRepository);
decorate(unmanaged(), LinqRepository, 0);
decorate(unmanaged(), LinqRepository, 1);

export { LinqRepository };

Injecting LinqRepository with NestJS

When creating injectable repositories extending LinqRepository in NestJS, you must use @nestjs/typeorm's InjectDataSource decorator to inject a data source into your repository's constructor. Doing so forces Nest to wait until the TypeORM connection is established before continuing to construct the repository. If you do not use InjectDataSource, you will encounter errors because LinqRepository will try to get the entity's repository from the connection before it is established.

Here is an example of an injectable repository in NestJS:

import { Injectable } from "@nestjs/common";
import { InjectDataSource } from "@nestjs/typeorm";
import { DataSource } from "typeorm";
import { LinqRepository } from "typeorm-linq-repository";
import { Entity } from "./entity.entity";

@Injectable()
export class EntityRepository extends LinqRepository<Entity> {
    // NOTE: @InjectDataSource is required to force Nest to wait for the TypeORM connection to be established
    // before typeorm-linq-repository's LinqRepository attempts to get the repository from the connection.
    public constructor(
        @InjectDataSource(/* "data-source-name" or empty for "default" */)
        dataSource: DataSource
    ) {
        super(dataSource, Entity);
    }
}

You can see a working example of injecting repositories extending LinqRepository in NestJS in this repository.

Using Queries

typeorm-linq-repository not only makes setting up repositories incredibly easy; it also gives you powerful, LINQ-style query syntax.

Retrieving Entities

You can query entities for all, many, or one result:

 // Gets all entities.
this._userRepository.getAll();

// Gets many entities.
this._userRepository
    .getAll()
    .where(u => u.admin)
    .isTrue();

// Gets one entity.
this._userRepository
    .getOne()
    .where(u => u.email)
    .equal(email);

// Finds one entity using its ID.
this._userRepository.getById(id);

Counting Results

You may call count() on a query to get the count of records matching the current query conditions without killing the query as awaiting or calling .then() on the query otherwise would; this way, you can use a query to count all records matching a set of conditions and then set paging parameters on the same query.

For example:

let activeUserQuery = this._userRepository
    .getAll()
    .where(u => u.active)
    .isTrue();

// Count all active users.
const activeUserCount = await activeUserQuery.count();

// Set paging parameters on the query.
activeUserQuery = activeUserQuery
    .skip(skip)
    .take(take);

const pagedActiveUsers = await activeUserQuery;

Type Safe Querying

This LINQ-style querying really shines by giving you type-safe includes, joins, and where statements, eliminating the need for hard-coded property names in query functions.

This includes conditional statements:

this._userRepository
    .getOne()
    .where(u => u.email)
    .equal(email);

As well as include statements:

this._userRepository
    .getById(id)
    .include(u => u.posts);

If the property posts ever changes, you get compile-time errors, ensuring the change is not overlooked in query statements.

Multiple Includes

You can use include() more than once to include several properties on the query's base type:

this._userRepository
    .getById(id)
    .include(u => u.posts)
    .include(u => u.orders);

Subsequent Includes and Current Property Type

Include statements transform the "current property type" on the Query so that subsequent thenInclude()s can be executed while maintaining this type safety.

this._userRepository
    .getById(id)
    .include(u => u.orders)
    .thenInclude(o => o.items);

this._userRepository
    .getById(id)
    .include(u => u.posts)
    .thenInclude(p => p.comments)
    .thenInclude(c => c.user);

You can use include() or thenInclude() on the same property more than once to subsequently include another relation without duplicating the include in the executed query.

this._userRepository
    .getById(id)
    .include(u => u.posts)
    .thenInclude(p => p.comments)
    .include(u => u.posts)
    .thenInclude(p => p.subscribedUsers);

Filtering Results

Queries can be filtered on one or more conditions using where(), and(), and or(). Note that, just as with TypeORM's QueryBuilder, using where() more than once will overwrite previous where()s, so use and() and or() to add more conditions.

this._userRepository
    .getAll()
    .where(u => u.isActive)
    .isTrue()
    .and(u => u.lastLogin)
    .greaterThan(date);

Note also that this caveat only applies to "normal" where conditions; a where condition on a join is local to that join and does not affect any "normal" where conditions on a query.

this._postRepository
    .getAll()
    .join((p: Post) => p.user)
    .where((u: User) => u.id)
    .equal(id)
    .where((p: Post) => p.archived)
    .isTrue();

Filtering Included Relations

To filter included or thenIncluded relationships (which is not possible by using .include(...).where(...) since using where after include resets the query rather than performing a where on the include), use join or thenJoin after the include or thenInclude.

this._postRepository
    .getAll()
    .include(p => p.comments)
    // We want to exclude included comments based on conditions on replies
    // while not filtering any posts.
    .thenInclude(c => c.replies)
    // Therefore, use a joinAlso() here to maintain a LEFT JOIN on comments
    .joinAlso(p => p.comments)
    // but use a thenJoin() here to restrict comments and replies
    // to an INNER JOIN based on conditions.
    .thenJoin(c => c.replies)
    .where(r => r.user.email)
    .equal(filterEmail);

Joined Properties in Comparisons

It is possible to join relationships on the fly during a conditional clause in order to compare a relationship's value.

this._postRepository
    .getAll()
    .where(p => p.date)
    .greaterThan(date)
    .and(p => p.user.id)
    .equal(userId);

In order to join through collections in this fashion, use the Array.map() method.

this._userRepository
    .getAll()
    .where(u => u.posts.map(p => p.comments.map(c => c.flagged)))
    .isTrue();

Note: If not already joined via one of the available join or include methods, relationships joined in this fashion will be joined as follows:

• where() and and() result in an INNER JOIN.
• or() results in a LEFT JOIN.

Grouped (Bracketed) Conditional Clauses

In order to group conditional clauses into parentheses, use isolatedWhere(), isolatedAnd(), and isolatedOr().

this._userRepository
    .getOne()
    .where(u => u.isAdmin)
    .isTrue()
    .isolatedOr(q => q
        .where(u => u.firstName)
        .equals("John")
        .and(u => u.lastName)
        .equals("Doe")
    ).isolatedOr(q => q
        .where(u => u.firstName)
        .equals("Jane")
        .and(u => u.lastName)
        .equals("Doe")
    );

Comparing Basic Values

The following query conditions are available for basic comparisons:

beginsWith(value: string): Finds results where the queried text begins with the supplied string.

contains(value: string): Finds results were the queried text contains the supplied string.

endsWith(value: string): Finds results where the queried text ends with the supplied string.

equal(value: string | number | boolean): Finds results where the queried value is equal to the supplied value.

greaterThan(value: number): Finds results where the queried value is greater than the supplied number.

greaterThanOrEqual(value: number): Finds results where the queried value is greater than or equal to the supplied number.

in(include: string[] | number[]): Finds results where the queried value intersects the specified array of values to include.

isFalse(): Finds results where the queried boolean value is false.

isNotNull(): Finds results where the queried relation is not null.

isNull(): Finds results where the queried relation is null.

isTrue(): Finds results where the queried boolean value is true.

lessThan(value: number): Finds results where the queried value is less than the supplied number.

lessThanOrEqual(value: number): Finds results where the queried value is less than or equal to the supplied number.

notEqual(value: string | number | boolean): Finds results where the queried value is not equal to the supplied value.

notIn(exclude: string[] | number[]): Finds results where the queried value intersects the specified array of values to exclude.

inSelected() and notInSelected() are also available and are covered later in this guide.

String Comparison

When comparing strings, the default behavior is to not match case (case-insensitive comparison).

If a case-sensitive comparison is desired, use the matchCase option when executing a comparison.

// Perform a case-sensitive comparison rather than the default case-insensitive.
equal(value, { matchCase: true });

Note that, due to a lack of type reflection in JavaScript, the opposite is true for comparing values with joined entities. See the Comparing Values With Joined Entities section below.

Inner Joins

Filter joined relations by using where(), and(), and or() on inner joins using join() and thenJoin().

this._userRepository
    .getAll()
    .join(u => u.posts)
    .where(p => p.archived)
    .isTrue();

this._userRepository
    .getOne()
    .join(u => u.posts)
    .where(p => p.flagged)
    .isTrue()
    .and(p => p.date)
    .greaterThan(date);

Just as with include() and thenInclude(), join() always uses the query's base type, while thenJoin() continues to use the last joined entity's type.

this._postRepository
    .getAll()
    .join(p => p.user)
    .where(u => u.id)
    .equal(id)
    .thenJoin(u => u.comments)
    .where(c => c.flagged)
    .isTrue()
    .join(p => p.comments)
    .thenJoin(c => c.user)
    .where(u => u.dateOfBirth)
    .lessThan(date);

Left Joins

As the above join() and thenJoin() perform an INNER JOIN, desired results may be lost if you wish to not exclude previously included results if the joined relations fail the join condition. Filter joined relations while not excluding previously included results by using joinAlso() and thenJoinAlso() to perform a LEFT JOIN instead.

Regarding Included Relationships

Note that .include() and .thenInclude() are not intended to work the same way as .join(), .joinAlso(), .thenJoin(), and .thenJoinAlso() in conjunction with .where().

That is, using .include().where() does NOT behave the same way as .join().where() (interpreted in "plain English" as "join where").

.include() and .thenInclude() were meant to stand alone in their own context rather than filtering the main entity based on joined relationships.

For example:

this._userRepository
    .getMany()
    // I want to include posts in my results, but I am filtering included posts without filtering user results.
    .include(u => u.posts)
    // However, I am also filtering on the user itself (.where() after .include() filters on the base type).
    .where(u => u.active)
    .isTrue();

On the other hand, if you do intend to include a relationship while also filtering results based on a condition on that included relationship, use .include() in conjunction with .join().where(), i.e.:

this._userRepository
    .getMany()
    // Include posts in results.
    .include(u => u.posts)
    // Use .join rather than .joinAlso to actually filter user results by post criteria.
    .join(u => u.posts)
    .where(p => p.archived)
    .isTrue();

Finally, if you intend to include a relationship while filtering those included relationships but not filtering out any entities of the base type, then use .joinAlso().where() in order to perform a LEFT JOIN as opposed to an INNER JOIN.

this._userRepository
    .getMany()
    // Include posts in results.
    .include(u => u.posts)
    // Use .joinAlso rather than .join to perform a left join to filter posts but not filter users.
    .joinAlso(u => u.posts)
    .where(p => p.archived)
    .isTrue();

Joining Foreign Entities

Join from an unrelated entity using from(). A simple example of this is not easily provided, so see examples below for further guidance on using this method.

this._songRepository
    .getAll()
    .join(s => s.artist)
    .where(a => a.id)
    .equal(artistId)
    .from(UserProfileAttribute)
    .thenJoin(p => p.genre)
    // ...

Comparing Values With Joined Entities

Perform comparisons with values on joined entities by calling from(), join(), and thenJoin() after calling where(), and(), or or().

this._userRepository
    .getAll()
    .join(u => u.posts)
    .where(p => p.recordLikeCount)
    .thenJoin(p => p.category)
    .greaterThanJoined(c => c.averageLikeCount);

The following query conditions are available for comparisons on related entities' properties:

equalJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is equal to the specified property on the last joined entity.

greaterThanJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is less than the specified property on the last joined entity.

greaterThanOrEqualJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is greater than or equal to the specified property on the last joined entity.

lessThanJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is less than the specified property on the last joined entity.

lessThanOrEqualJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is less than or equal to the specified property on the last joined entity.

notEqualJoined(selector: (obj: P) => any): Determines whether the property specified in the last "where" is not equal to the specified property on the last joined entity.

String Comparison When Comparing Values With Joined Entities

Note that although non-joined string comparisons defaults to case-insensitive comparison, due to a lack of type reflection in JavaScript, the opposite is true for comparing values with joined entities. Therefore, the default behavior when using the above methods is to perform a case sensitive comparison, so you must specify matchCase: false when using the above methods if you wish to perform a case-insensitive comparison.

// Perform a case-insensitive comparison rather than the default case-sensitive when comparing joined entity's properties.
equalJoined(x => x.property, { matchCase: false });

Checking Relations

It is possible to check for existence or absence of relations in an array of relations (or existence or absense of relations that meet a certain condition).

For example:

const accessiblePosts = await postRepository
    // Get posts where...
    .getAll()
    // Note: Must use groupBy method to check relations.
    .groupBy(p => p.id)
    // ...no tags exist (meaning the post is not restricted to a certain tag)...
    .whereNone(p => p.tags, t => t.id)
    // ...or the post contains the tag being searched for.
    .orAny(p => p.tags, t => t.id, t => t.id)
    .equal(tagId);

NOTE: As the underlying query executes methods that check relations as HAVING COUNT(...), you MUST use the groupBy method to group results on an arbitrary primitive property of the query's base type; for instance, the primary key.

The following relation checking methods are available:

whereAny: Checks for existence of the specified relations; optionally checks for existence of relations meeting a criteria determined by the optional conditionPropSelector argument in conjunction with the following comparing method.

whereNone: Checks for absence of the specified relations; optionally checks for absence of relations meeting a criteria determined by the optional conditionPropSelector argument in conjunction with the following comparing method.

andAny: The same as whereAny but performed as AND COUNT(...) > 0 (supplementing the initial HAVING COUNT(...)).

andNone: The same as whereNone but performed as AND COUNT(...) = 0 (supplementing the initial HAVING COUNT(...)).

orAny: The same as whereAny but performed as OR COUNT(...) > 0 (supplementing the initial HAVING COUNT(...)).

orNone: The same as whereNone but performed as OR COUNT(...) = 0 (supplementing the initial HAVING COUNT(...)).

Including or Excluding Results Within an Inner Query

To utilize an inner query, use the inSelected() and notInSelected() methods. Each takes an inner ISelectQuery, which is obtained by calling select() on the inner query after its construction and simply specifies which value to select from the inner query to project to the IN or NOT IN list.

The following example is overkill since, in reality, you would simply add the condition that the post is not archived on the main query, but consider what is going on within the queries in order to visualize how inner queries in typeorm-linq-repository work.

Consider a PostRepository from which we want to get all posts belonging to a certain user and only those that are not archived. The outer query in this instance gets all posts belonging to the specified user, while the inner query specified all posts that are not archived. The union of the two produces the results we want.

this._postRepository
    .getAll()
    .join(p => p.user)
    .where(u => u.id)
    .equal(id)
    .where(p => p.id)
    .inSelected(
        this._postRepository
            .getAll()
            .where(p => p.archived)
            .isFalse()
            .select(p => p.id)
    );

This next example is more representative of an actual situation in which an inner query is useful. Consider an application in which users set up a profile and add Profile Attributes which specify genres of songs they do NOT wish to hear; that is, the application would avoid songs with genres specified by the user's profile.

Given the following models:

Artist.ts

import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from "typeorm";
import { Song } from "./Song";

@Entity()
export class Artist {
    @PrimaryGeneratedColumn()
    public id: number;

    @Column({ nullable: false })
    public name: string;

    @OneToMany(() => Song, (song: Song) => song.artist)
    public songs: Song[];
}

Genre.ts

import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from "typeorm";
import { SongGenre } from "./SongGenre";

@Entity()
export class Genre {
    @PrimaryGeneratedColumn()
    public id: number;

    @Column({ nullable: false })
    public name: string;

    @OneToMany(() => SongGenre, (songGenre: SongGenre) => songGenre.genre)
    public songs: SongGenre[];
}

Song.ts

import { Column, Entity, ManyToOne, OneToMany, PrimaryGeneratedColumn } from "typeorm";
import { Artist } from "./Artist";
import { SongGenre } from "./SongGenre";

@Entity()
export class Song {
    @ManyToOne(() => Artist, (artist: Artist) => artist.songs)
    public artist: Artist;

    @OneToMany(() => SongGenre, (songGenre: SongGenre) => songGenre.song)
    public genres: SongGenre[];

    @PrimaryGeneratedColumn()
    public id: number;

    @Column({ nullable: false })
    public name: string;
}

SongGenre.ts

import { Entity, ManyToOne, PrimaryGeneratedColumn } from "typeorm";
import { Genre } from "./Genre";
import { Song } from "./Song";

/**
 * Links a song to a genre.
 */
@Entity()
export class SongGenre {
    @ManyToOne(() => Genre, (genre: Genre) => genre.songs)
    public genre: Genre;

    @PrimaryGeneratedColumn()
    public id: number;

    @ManyToOne(() => Song, (song: Song) => song.genres)
    public song: Song;
}

User.ts

import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from "typeorm";
import { UserProfileAttribute } from "./UserProfileAttribute";

@Entity()
export class User {
    @Column({ nullable: false })
    public email: string;

    @PrimaryGeneratedColumn()
    public id: number;

    @Column({ nullable: false })
    public password: string;

    @OneToMany(() => UserProfileAttribute, (profileAttribute: UserProfileAttribute) => profileAttribute.user)
    public profile: UserProfileAttribute[];
}

UserProfileAttribute.ts

import { Entity, ManyToOne, PrimaryGeneratedColumn } from "typeorm";
import { Genre } from "./Genre";
import { User } from "./User";

/**
 * An attribute of a user's profile specifying a genre that user does not wish to hear.
 */
@Entity()
export class UserProfileAttribute {
    @ManyToOne(() => Genre)
    public genre: Genre;

    @PrimaryGeneratedColumn()
    public id: number;

    @ManyToOne(() => User, (user: User) => user.profile)
    public user: User;
}

Now, consider the following query from which we want to gather all songs by a certain artist that a certain user wants to hear; that is, songs by that artist that do not match a genre blocked by the user's profile.

this._songRepository
    .getAll()
    .join(s => s.artist)
    .where(a => a.id)
    .equal(artistId)
    .where(s => s.id)
    .notInSelected(
        this._songRepository
            .getAll()
            .join(s => s.artist)
            .where(a => a.id)
            .equal(artistId)
            .from(UserProfileAttribute)
            .thenJoin(p => p.genre)
            .where(g => g.id)
            .join(s => s.songGenre)
            .thenJoin(sg => sg.genre)
            .equalJoined(g => g.id)
            .from(UserProfileAttribute)
            .thenJoin(p => p.user)
            .where(u => u.id)
            .equal(userId)
            .select(s => s.id)
    );

Selection Type

Calling select() after completing any comparison operations uses the query's base type. If you wish to select a property from a relation rather than the query's base type, you may call select() after one or more joins on the query.

this._songRepository
    .getAll()
    .join(s => s.genres)
    .thenJoin(sg => sg.genre)
    .select(g => g.id);

Ordering Queries

You can order queries in either direction and using as many subsequent order statements as needed.

this._userRepository
    .getAll()
    .orderBy(u => u.lastName)
    .thenBy(u => u.firstName);

You can use include statements to change the query's property type and order on properties of that child.

this._userRepository
    .getAll()
    .orderByDescending(u => u.email)
    .include(u => u.posts)
    .thenByDescending(p => p.date);

Grouping Results

You can group results by one or more properties using groupBy and thenGroupBy.

this._userRepository
    .getAll()
    .groupBy(u => u.lastName)
    .thenGroupBy(u => u.firstName);

Using Query Results

Queries are transformed into promises whenever you are ready to consume the results.

Queries can be returned as raw promises:

this._userRepository
    .getById(id)
    .toPromise();

Or invoked as a promise on the spot:

this._userRepository
    .getById(id)
    .then(user => {
        // ...
    });

Or, using ES6 async syntax:

const user = await this._userRepository.getById(user);

Using TypeORM's Query Builder

If you encounter an issue or a query which this query wrapper cannot accommodate, you can use TypeORM's native QueryBuilder.

this._userRepository.createQueryBuilder("user");

Persisting Entities

The following methods persist and remove entities from the database:

// Creates one or more entities.
create(entities: T | T[]): Promise<T | T[]>;

// Deletes one or more entities by reference or one entity by ID.
delete(entities: number | string | T | T[]): Promise<boolean>;

// Updates one or more entities.
update(entities: T | T[]): Promise<T | T[]>;

Transaction support

This library was unfortunately developed without regard to transactions, but another library called typeorm-transactional-cls-hooked makes utilizing transations extremely easy!

To use this library in conjuntion with typeorm-linq-repository, install typeorm-transactional-cls-hooked along with its dependencies:

npm install --save typeorm-transactional-cls-hooked cls-hooked

npm install --save-dev @types/cls-hooked

Then, per typeorm-transactional-cls-hooked's documentation, simply patch TypeORM's repository with typeorm-transactional-cls-hooked's base repository when bootstrapping your app:

import { initializeTransactionalContext, patchTypeORMRepositoryWithBaseRepository } from "typeorm-transactional-cls-hooked";

// Initialize cls-hooked.
initializeTransactionalContext();
// Patch TypeORM's Repository with typeorm-transactional-cls-hooked's BaseRepository.
patchTypeORMRepositoryWithBaseRepository();

That's it! Now all you need to do is use typeorm-transactional-cls-hooked's @Transactional() decorator on methods that persist entities to your repositories. See typeorm-transactional-cls-hooked's docs for more details.

Unit testing

Two libraries, typeorm-linq-repository-testing and typeorm-linq-repository-testing-nestjs, now make it easier to unit test LinqRepository.

typeorm-linq-repository-testing-nestjs contains a more "complete" example of usage since it has more practical usage in the context of another framework, but typeorm-linq-repository-testing provides the raw components if you need to build something similar for another framework.