objection-cursor0.5.4 • Public • Published
An Objection.js plugin for cursor based pagination.
Using offsets for pagination is a widely popular technique. Clients tell the number of results they want per page, and the page number they want to return results from. While easy to implement and use, offsets come with a drawback: when items are written to the database at a high frequency, offset based pagination becomes unreliable. For example, if we fetch a page with 10 rows, and then 10 rows are added, fetching the second page might contain the same rows as the first page.
Cursor based pagination works by returning a pointer to a row in the database. Fetching the next/previous page will then return items after/before the given pointer. While reliable, this technique comes with a few drawbacks itself:
- The cursor must be based on a unique column (or columns)
- The concept of pages is lost, and thus you cannot jump to a specific one
Cursor pagination is used by companies such as Twitter, Facebook and Slack, and goes well with infinite scroll elements in general.
$ npm install objection-cursor
const Model = Model;const cursorMixin = ;// Set optionsconst cursor = ;Model...// Options are not requiredModel...
const query = Movie// Strict ordering is required;query;
const query = Movie// Order by a JSON field of an eagerly joined relation...
Cursors ordered by nullable columns won't work out-of-the-box. For this reason the mixin also introduces an
orderByCoalesce method, which you can use to treat nulls as some other value for the sake of comparisons. Same as
orderByCoalesce supports reference builders, but not raw queries.
const query = Movie// Coalesce null values into empty string// Same as above// First non-null value will be used// Works with refs// Reference builders and raw queries can be coalesced to...
cursor(options | Model)
You can setup the mixin with or without options.
Example (with options):
const Model = Model;const cursorMixin = ;const cursor =;Model...Movie;
Example (without options):
const Model = Model;const cursorMixin = ;Model...
cursor- A URL-safe string used to determine after/before which element items should be returned.
true, return items before the one specified in the cursor. Use this to "go back".
results: // Resulted rows.pageInfo:next: // Provide this in the next `cursorPage` call to fetch items after the last ones.previous: // Provide this in the next `previousCursorPage` call to fetch items before the last ones.hasNext: // If `options.pageInfo.hasNext` is true.hasPrevious: // If `options.pageInfo.hasPrevious` is true.remaining: // If `options.pageInfo.remaining` is true. Number of items remaining (after or before `results`).total: // If `options.pageInfo.total` is true. Total number of rows (without limit).
orderByCoalesce(column, [direction, [values]])
Use this if you want to sort by a nullable column.
column- Column to sort by.
direction- Sort direction.
values- Values to coalesce to. If column has a null value, treat it as the first non-null value in
values. Can be one or many of: string, ReferenceBuilder or RawQuery.
Values shown are defaults.
limit: 50 // Default limit in all queriespageInfo:// When true, these values will be added to `pageInfo` in query responsetotal: false // Total amount of rowsremaining: false // Remaining amount of rows in *this* directionhasNext: false // Are there rows after current results?hasPrevious: false // Are there rows before current results?
pageInfo.totalrequires an additional query.
pageInfo.remainingrequires and additional query.
pageInfo.hasNextrequires the same queries as
pageInfo.hasPreviousrequires the same queries as