Skip to main content
Version: 6.5

Cursor <Entity, Hint, Fields, Excludes, IncludeCount>

As an alternative to the offset-based pagination with limit and offset, we can paginate based on a cursor. A cursor is an opaque string that defines a specific place in ordered entity graph. You can use em.findByCursor() to access those options. Under the hood, it will call em.find() and em.count() just like the em.findAndCount() method, but will use the cursor options instead.

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
const currentCursor = await em.findByCursor(User, {}, {
  first: 10,
  after: previousCursor, // can be either string or `Cursor` instance
  orderBy: { id: 'desc' },
});

// to fetch next page
const nextCursor = await em.findByCursor(User, {}, {
  first: 10,
  after: currentCursor.endCursor, // or currentCursor.endCursor
  orderBy: { id: 'desc' },
});

The Cursor object provides the following interface:

Cursor<User> {
  items: [
    User { ... },
    User { ... },
    User { ... },
    ...
  ],
  totalCount: 50,
  length: 10,
  startCursor: 'WzRd',
  endCursor: 'WzZd',
  hasPrevPage: true,
  hasNextPage: true,
}

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • new Cursor<Entity, Hint, Fields, Excludes, IncludeCount>(items, totalCount, options, meta): Cursor<Entity, Hint, Fields, Excludes, IncludeCount>

  • Parameters

    • items: Loaded<Entity, Hint, Fields, Excludes>[]
    • totalCount: IncludeCount extends true ? number : undefined
    • options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>
    • meta: EntityMetadata<Entity>

    Returns Cursor<Entity, Hint, Fields, Excludes, IncludeCount>

Properties

readonlyhasNextPage

hasNextPage: boolean

readonlyhasPrevPage

hasPrevPage: boolean

readonlyitems

items: Loaded<Entity, Hint, Fields, Excludes>[]

readonlytotalCount

totalCount: IncludeCount extends true ? number : undefined

Accessors

endCursor

  • get endCursor(): null | string

  • Returns null | string

length

  • get length(): number

  • Returns number

startCursor

  • get startCursor(): null | string

  • Returns null | string

Methods

[iterator]

  • [iterator](): IterableIterator<Loaded<Entity, Hint, Fields, Excludes>, any, any>

  • Returns IterableIterator<Loaded<Entity, Hint, Fields, Excludes>, any, any>

from

  • from(entity): string

  • Computes the cursor value for a given entity.

    Parameters

    • entity: Entity | Loaded<Entity, Hint, Fields, Excludes>

    Returns string

staticdecode

  • decode(value): unknown[]

  • Parameters

    • value: string

    Returns unknown[]

staticencode

  • encode(value): string

  • Parameters

    • value: unknown[]

    Returns string

staticfor

  • for<Entity>(meta, entity, orderBy): string

staticgetDefinition

  • getDefinition<Entity>(meta, orderBy): [never, QueryOrder][]
Page Options