typeorm-cursor-connection

Relay Cursor Connection implementations for TypeORM

EntityConnection

Connection for querying multiple entities from SelectQueryBuilder. It paginates the queryBuilder with the connection arguments.

export declare class EntityConnection<TEntity extends Object> extends Connection<TEntity, TEntity> {
    constructor(
      args: ConnectionArguments,
      sortOptions: EntityConnectionSortOption[],
      queryBuilder: SelectQueryBuilder<TEntity>
    );
}

MongoEntityConnection

Connection for querying multiple entities from MongoRepository.

export interface MongoEntityConnectionOptions<Entity> {
    sortOptions: { [fieldName: string]: 1 | -1; };
    repository: MongoRepository<Entity>;
    selector?: Selector;
}
export declare class MongoEntityConnection<Entity extends Object> extends Connection<Entity, Entity> {
    constructor(args: ConnectionArguments, options: MongoEntityConnectionOptions<Entity>);
}

How it works

A cursor is serialized data representing the position of the node in the connection. EntityConnection and MongoEntityConnection serialize the values of field, which is used for sorting, into the cursor.

@Entity()
class Post {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  title: string;

  @Column()
  createdAt: Date;
};

Let's suppose we have a table of Posts.

{ id: 1, title: 'Post A', createdAt: new Date('2018-03-02') }
{ id: 2, title: 'Post C', createdAt: new Date('2018-03-03') }
{ id: 3, title: 'Post D', createdAt: new Date('2018-03-04') }
{ id: 4, title: 'Post B', createdAt: new Date('2018-03-05') }

And we are querying the entities in the order we want.

const postConnectionOrderedByTitle = new EntityConnection(
  { first: 10 },
  [{ sort: 'title', order: 'ASC' }],
  getRepository(Post).createQueryBuilder(),
})
/*
                cursor
                --------
{ id: 1, title: 'Post A', createdAt: new Date('2018-03-02') }, -> cursor: ['Post A']
{ id: 4, title: 'Post B', createdAt: new Date('2018-03-05') }, -> cursor: ['Post B']
{ id: 2, title: 'Post C', createdAt: new Date('2018-03-03') }, -> cursor: ['Post C']
{ id: 3, title: 'Post D', createdAt: new Date('2018-03-04') }, -> cursor: ['Post D']
*/

Cursors are for making a new query after the place of the node, so we can use title field as the cursor for that connection. With the cursor, We can query Posts where Post's title is greater than the cursor.

But it can go wrong when not all title value is unique in the table. So we take the approach of keeping cursor value is unique in the connection.

In order to do that:

const postConnectionOrderedByTitle = new EntityConnection(
  { first: 10 },
  [
    { sort: 'title', order: 'ASC' },
    { sort: 'id', order: 'ASC' }
  ],
  getRepository(Post).createQueryBuilder(),
)
/*
     cursor[1]   cursor[0]
     --          --------
{ id: 1, title: 'Post A', createdAt: new Date('2018-03-02') }, -> cursor: ['Post A', 1]
{ id: 4, title: 'Post B', createdAt: new Date('2018-03-05') }, -> cursor: ['Post B', 4]
{ id: 2, title: 'Post C', createdAt: new Date('2018-03-03') }, -> cursor: ['Post C', 2]
{ id: 3, title: 'Post D', createdAt: new Date('2018-03-04') }, -> cursor: ['Post D', 3]
*/

We have the id field included to cursor, and it guarantees every cursor value is unique even when new Posts are inserted to the table.