@platformatic/sql-mapper 2.55.0 → 2.57.0

package/lib/cursor.js

@@ -0,0 +1,86 @@
+'use strict'
+
+const errors = require('./errors')
+
+function sanitizeCursor (cursor, orderBy, inputToFieldMap, fields, primaryKeys) {
+  if (!orderBy || orderBy.length === 0) throw new errors.MissingOrderByClauseError()
+  let hasUniqueField = false
+  const validCursorFields = new Map()
+
+  for (const [key, value] of Object.entries(cursor)) {
+    const dbField = inputToFieldMap[key]
+    if (!dbField) throw new errors.UnknownFieldError(key)
+    const order = orderBy.find((order) => order.field === key)
+    if (!order) throw new errors.MissingOrderByFieldForCursorError(key)
+    if (primaryKeys.has(dbField)) hasUniqueField = true
+    validCursorFields.set(key, {
+      dbField,
+      value,
+      direction: order.direction.toLowerCase(),
+      fieldWrap: fields[dbField]
+    })
+  }
+  if (!hasUniqueField) throw new errors.MissingUniqueFieldInCursorError()
+
+  // Process fields in orderBy order
+  const cursorFields = []
+  for (const order of orderBy) {
+    if (validCursorFields.has(order.field)) {
+      cursorFields.push(validCursorFields.get(order.field))
+    }
+  }
+  return cursorFields
+}
+
+function buildTupleQuery (cursorFields, sql, computeCriteriaValue, isBackwardPagination) {
+  const direction = cursorFields[0].direction
+  let operator
+  if (isBackwardPagination) {
+    operator = direction === 'desc' ? '>' : '<'
+  } else {
+    operator = direction === 'desc' ? '<' : '>'
+  }
+  const fields = sql.join(
+    cursorFields.map(({ dbField }) => sql.ident(dbField)),
+    sql`, `
+  )
+  const values = sql.join(
+    cursorFields.map(({ fieldWrap, value }) => computeCriteriaValue(fieldWrap, value)),
+    sql`, `
+  )
+  return sql`(${fields}) ${sql.__dangerous__rawValue(operator)} (${values})`
+}
+
+function buildQuery (cursorFields, sql, computeCriteriaValue, isBackwardPagination) {
+  const conditions = []
+  const equalityParts = []
+  for (const { dbField, fieldWrap, value, direction } of cursorFields) {
+    let operator
+    if (isBackwardPagination) {
+      operator = direction === 'desc' ? '>' : '<'
+    } else {
+      operator = direction === 'desc' ? '<' : '>'
+    }
+    const inequalityPart = sql`${sql.ident(dbField)} ${sql.__dangerous__rawValue(operator)} ${computeCriteriaValue(fieldWrap, value)}`
+    if (equalityParts.length === 0) {
+      conditions.push(inequalityPart)
+    } else {
+      conditions.push(sql`${sql.join(equalityParts, sql` AND `)} AND ${inequalityPart}`)
+    }
+    equalityParts.push(sql`${sql.ident(dbField)} = ${computeCriteriaValue(fieldWrap, value)}`)
+  }
+  return sql`(${sql.join(conditions, sql` OR `)})`
+}
+
+function buildCursorCondition (sql, cursor, orderBy, inputToFieldMap, fields, computeCriteriaValue, primaryKeys, isBackwardPagination) {
+  if (!cursor || Object.keys(cursor).length === 0) return null
+  const cursorFields = sanitizeCursor(cursor, orderBy, inputToFieldMap, fields, primaryKeys)
+  const sameSortDirection = cursorFields.every(({ direction }) => direction === cursorFields[0].direction)
+  return sameSortDirection
+    ? buildTupleQuery(cursorFields, sql, computeCriteriaValue, isBackwardPagination)
+    : buildQuery(cursorFields, sql, computeCriteriaValue, isBackwardPagination)
+}
+
+module.exports = {
+  buildCursorCondition,
+}

package/lib/entity.js

@@ -12,6 +12,7 @@ const { singularize } = require('inflected')
 const { findNearestString } = require('@platformatic/utils')
 const errors = require('./errors')
 const { wrapDB } = require('./telemetry')
+const { buildCursorCondition } = require('./cursor')
 
 function createMapper (defaultDb, sql, log, table, fields, primaryKeys, relations, queries, autoTimestamp, schema, useSchemaInName, limitConfig, columns, constraintsList) {
   /* istanbul ignore next */ // Ignoring because this won't be fully covered by DB not supporting schemas (SQLite)
@@ -306,35 +307,51 @@ function createMapper (defaultDb, sql, log, table, fields, primaryKeys, relation
     const db = getDB(opts)
     const fieldsToRetrieve = computeFields(opts.fields).map((f) => sql.ident(f))
     const criteria = computeCriteria(opts)
+    const criteriaExists = criteria.length > 0
+    const isBackwardPagination = opts.nextPage === false
 
     let query = sql`
       SELECT ${sql.join(fieldsToRetrieve, sql`, `)}
       FROM ${tableName(sql, table, schema)}
     `
 
-    if (criteria.length > 0) {
+    if (criteriaExists) {
       query = sql`${query} WHERE ${sql.join(criteria, sql` AND `)}`
     }
 
+    if (opts.cursor) {
+      const cursorCondition = buildCursorCondition(sql, opts.cursor, opts.orderBy, inputToFieldMap, fields, computeCriteriaValue, primaryKeys, isBackwardPagination)
+      if (cursorCondition) {
+        if (criteriaExists) query = sql`${query} AND ${cursorCondition}`
+        else query = sql`${query} WHERE ${cursorCondition}`
+      }
+    }
+
     if (opts.orderBy && opts.orderBy.length > 0) {
       const orderBy = opts.orderBy.map((order) => {
         const field = inputToFieldMap[order.field]
-        return sql`${sql.ident(field)} ${sql.__dangerous__rawValue(order.direction)}`
+        let direction = order.direction.toLowerCase()
+        if (isBackwardPagination) {
+          direction = direction === 'asc' ? 'desc' : 'asc'
+        }
+        return sql`${sql.ident(field)} ${sql.__dangerous__rawValue(direction)}`
       })
       query = sql`${query} ORDER BY ${sql.join(orderBy, sql`, `)}`
     }
 
-    query = sql`${query} LIMIT ${sanitizeLimit(opts.limit, limitConfig)}`
-    if (opts.offset !== undefined) {
-      if (opts.offset < 0) {
-        throw new errors.ParamNotAllowedError(opts.offset)
+    if (opts.paginate !== false) {
+      query = sql`${query} LIMIT ${sanitizeLimit(opts.limit, limitConfig)}`
+      if (opts.offset !== undefined) {
+        if (opts.offset < 0) {
+          throw new errors.ParamNotAllowedError(opts.offset)
+        }
+        query = sql`${query} OFFSET ${opts.offset}`
       }
-      query = sql`${query} OFFSET ${opts.offset}`
     }
 
     const rows = await db.query(query)
     const res = rows.map(fixOutput)
-    return res
+    return isBackwardPagination ? res.reverse() : res
   }
 
   async function count (opts = {}) {

package/lib/errors.js

@@ -21,4 +21,7 @@ module.exports = {
   MissingValueForPrimaryKeyError: createError(`${ERROR_PREFIX}_MISSING_VALUE_FOR_PRIMARY_KEY`, 'Missing value for primary key %s'),
   MissingWhereClauseError: createError(`${ERROR_PREFIX}_MISSING_WHERE_CLAUSE`, 'Missing where clause', 400),
   SQLiteOnlySupportsAutoIncrementOnOneColumnError: createError(`${ERROR_PREFIX}_SQLITE_ONLY_SUPPORTS_AUTO_INCREMENT_ON_ONE_COLUMN`, 'SQLite only supports autoIncrement on one column'),
+  MissingOrderByClauseError: createError(`${ERROR_PREFIX}_MISSING_ORDER_BY_CLAUSE`, 'Missing orderBy clause'),
+  MissingOrderByFieldForCursorError: createError(`${ERROR_PREFIX}_MISSING_ORDER_BY_FIELD_FOR_CURSOR`, 'Cursor field(s) %s must be included in orderBy'),
+  MissingUniqueFieldInCursorError: createError(`${ERROR_PREFIX}_MISSING_UNIQUE_FIELD_IN_CURSOR`, 'Cursor must contain at least one primary key field'),
 }

package/mapper.d.ts

@@ -140,6 +140,10 @@ export interface WhereCondition {
   }
 }
 
+export type Cursor = {
+  [columnName: string]: string | number | boolean | null,
+}
+
 interface Find<EntityFields> {
   (options?: {
     /**
@@ -162,6 +166,20 @@ interface Find<EntityFields> {
      * Number of entities to skip.
      */
     offset?: number,
+    /**
+     * If false pagination is disabled.
+     * @default true
+     */
+    paginate?: boolean,
+    /**
+     * Cursor to paginate the results.
+     */
+    cursor?: Cursor,
+    /**
+      * If set to false, the previous page will be fetched in cursor pagination.
+     * @default true
+     */
+    nextPage?: boolean,
     /**
      * If present, the entity participates in transaction
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/sql-mapper",
-  "version": "2.55.0",
+  "version": "2.57.0",
   "description": "A data mapper utility for SQL databases",
   "main": "mapper.js",
   "types": "mapper.d.ts",
@@ -35,8 +35,8 @@
     "camelcase": "^6.3.0",
     "fastify-plugin": "^5.0.0",
     "inflected": "^2.1.0",
-    "@platformatic/telemetry": "2.55.0",
-    "@platformatic/utils": "2.55.0"
+    "@platformatic/utils": "2.57.0",
+    "@platformatic/telemetry": "2.57.0"
   },
   "tsd": {
     "directory": "test/types"