json-rest-api 1.0.27 → 1.0.29

package/docs/API.md

@@ -2549,6 +2549,8 @@ The library uses standard JSON:API error format:
 
 ### Custom Error Handling
 
+Typed API errors thrown by getters, setters, computed fields, file detectors, or upload adapters retain their original code and details. For example, throwing `new RestApiResourceError('Upload forbidden', { subtype: 'forbidden' })` from an upload adapter produces a 403 response and still runs temporary-file cleanup.
+
 ```javascript
 // In hooks
 api.resource('articles').hook('beforeDataPost', async (context) => {

package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md

@@ -13,7 +13,7 @@ await api.addResource('posts', {
     content: { type: 'string', required: true },
     view_count: { type: 'number', default: 0, indexed: true },
     published_at: { type: 'dateTime', indexed: true },
-    created_at: { type: 'dateTime', defaultTo: Date.now, indexed: true }
+    created_at: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString(), indexed: true }
   },
   relationships: {
     comments: { 
@@ -54,7 +54,7 @@ await api.addResource('comments', {
   schema: {
     content: { type: 'string', required: true },
     author_name: { type: 'string', required: true, max: 100 },
-    created_at: { type: 'dateTime', defaultTo: Date.now, indexed: true },
+    created_at: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString(), indexed: true },
     likes: { type: 'number', default: 0, indexed: true },
     post_id: { type: 'id', belongsTo: 'posts', as: 'post', required: true }
   },
@@ -96,6 +96,8 @@ await api.resources.post_tags.createKnexTable();
 
 **Basic Pagination**
 
+When `sortableFields` is omitted or empty, visible stored schema fields and relationship aliases can be sorted. Query fields marked `sortable: true` are added to that set. Unknown fields and ordinary computed fields are rejected with 422. If a sort field is repeated, its first occurrence determines the direction.
+
 The API supports two types of pagination:
 
 1. **Offset-based pagination** using `page[number]` and `page[size]` parameters
@@ -671,6 +673,13 @@ Next multiField page: {
 
 **Cursor Pagination Notes:**
 - Cursors are simple strings containing the sort field values (format: `field:value,field2:value2`)
+- Sparse fieldsets may omit sort fields from the response; the Knex query still fetches those values internally to construct a complete cursor.
+- A cursor missing any active sort field is rejected with a validation error. Keep the same sort order when following a cursor.
+- Cursor values are validated against the sort field types. Invalid dates, numbers, or duplicate cursor fields produce HTTP 422.
+- `page[size]` and `page[number]` must be positive integers. Choose one of `page[number]`, `page[after]`, or `page[before]`; these cannot be combined.
+- Null sort values appear last in either sort direction. Generated cursors distinguish null from the literal string `"null"`; treat cursor strings as opaque values.
+- `page[before]` returns the adjacent preceding records in the requested sort order. Use a cursor for the first record of the current page to step back. When a backward response has more preceding records, its `links.next` and `meta.pagination.cursor.next` continue in the `before` direction.
+- Requested page sizes above `queryMaxLimit` are capped consistently for returned records, pagination metadata, and links.
 - The API automatically generates appropriate WHERE clauses based on sort direction
 - Cursor pagination is more efficient for large datasets as it doesn't need to count all records
 - Works seamlessly with any sort field, not just timestamps

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -132,7 +132,7 @@ await api.addResource('users', {
 });
 ```
 
-If a setter throws or rejects, the write fails with a validation error and the transaction rolls back instead of storing the untransformed value.
+If a setter throws or rejects, the write fails and the transaction rolls back. Typed API errors retain their code and details; other setter failures become validation errors. Getters and computed fields also propagate typed API errors, including `RestApiTemporalDataError`, so invalid output cannot be silently accepted.
 
 ### Getters - Transform After Retrieval
 
@@ -970,7 +970,7 @@ await api.addResource('posts', {
     title: { type: 'string', required: true },
     content: { type: 'string', required: true },
     author_id: { type: 'number', belongsTo: 'authors', as: 'author' },
-    published_at: { type: 'dateTime', default: 'now()' }
+    published_at: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() }
   },
   tableName: 'posts'
 });
@@ -1064,7 +1064,7 @@ await api.addResource('posts', {
       getter: (value) => value?.trim()
     },
     author_id: { type: 'number', belongsTo: 'authors', as: 'author' },
-    published_at: { type: 'dateTime', default: 'now()' }
+    published_at: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() }
   },
   tableName: 'posts'
 });

package/docs/GUIDE/GUIDE_Y_Appendices.md

@@ -6,7 +6,7 @@ This document explains how the JSON REST API handles date and time values throug
 
 ## Supported Date/Time Types
 
-The API supports three temporal data types in schemas:
+The API supports three string temporal types and two numeric epoch types in schemas:
 
 ### 1. `date`
 - **Format**: `YYYY-MM-DD`
@@ -16,8 +16,8 @@ The API supports three temporal data types in schemas:
 - **JSON Output**: ISO 8601 date string
 
 ### 2. `dateTime`
-- **Format**: `YYYY-MM-DD HH:MM:SS` (input) / ISO 8601 (output)
-- **Example Input**: `2024-01-15 14:30:00`
+- **Format**: RFC 3339 with seconds and an explicit `Z` or `±HH:MM` offset
+- **Example Input**: `2024-01-15T14:30:00Z`
 - **Example Output**: `2024-01-15T14:30:00.000Z`
 - **Usage**: Timestamps, created/updated times, or any date with time
 - **Database Storage**: DATETIME (MySQL) or TIMESTAMP (PostgreSQL)
@@ -30,6 +30,13 @@ The API supports three temporal data types in schemas:
 - **Database Storage**: TIME column type
 - **JSON Output**: ISO 8601 time string
 
+### 4. `epochMilliseconds` and `epochSeconds`
+- **Format**: An integer number or canonical base-10 integer string
+- **Example**: `1767323045000` (`epochMilliseconds`) or `1767323045` (`epochSeconds`)
+- **Usage**: Systems whose temporal contract is explicitly a Unix epoch value
+- **Database Storage**: BIGINT for table-backed resources
+- **JSON Output**: Integer number in the same unit declared by the schema type
+
 ## Schema Definition
 
 Define date/time fields in your schema like this:
@@ -37,12 +44,18 @@ Define date/time fields in your schema like this:
 ```javascript
 const articleSchema = {
   publishedDate: { type: 'date', required: true },
-  createdAt: { type: 'dateTime', defaultTo: 'now()' },
-  updatedAt: { type: 'dateTime', defaultTo: 'now()' },
+  createdAt: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() },
+  updatedAt: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() },
   dailyPostTime: { type: 'time', nullable: true }
 };
 ```
 
+`Date.prototype.toISOString()` always emits three fractional-second digits, so
+use it directly with unspecified precision or `temporalPrecision: 3` (or
+higher). A lower precision requires a producer that returns no more than the
+configured number of digits. Validation rejects excess input precision rather
+than silently truncating it.
+
 ## Input Validation
 
 ### On Write Operations (POST/PUT/PATCH)
@@ -64,21 +77,28 @@ The API validates and normalizes date/time inputs:
 ```
 
 **Accepted Input Formats:**
-- **date**: 
-  - `YYYY-MM-DD` (parsed at UTC midnight)
-  - ISO 8601 date strings
-  - Any JavaScript Date parseable string
-- **dateTime**: 
-  - ISO 8601 strings (`2024-01-15T14:30:00Z`) - recommended
-  - `YYYY-MM-DD HH:MM:SS` (assumed UTC)
-  - JavaScript Date parseable strings
-  - Unix timestamps (as numbers)
-- **time**: 
-  - `HH:MM:SS` or `HH:MM`
-  - Extracted from datetime strings
+- **date**: a real calendar date in `YYYY-MM-DD` form
+- **dateTime**: an RFC 3339 string with seconds and an explicit timezone, such as `2024-01-15T14:30:00Z` or `2024-01-15T22:30:00+08:00`
+- **time**: an offset-free `HH:MM[:SS[.fraction]]` string
+
+JavaScript `Date` objects, SQL datetime strings, Unix timestamps, locale text, and other values accepted by `Date.parse()` are not valid JSON temporal inputs. Use `epochMilliseconds` or `epochSeconds` schema fields for Unix timestamps.
 
 **Storage Format:**
-All date/time values are converted to JavaScript Date objects before storage, allowing the database driver to handle the appropriate formatting for each database system.
+Schema validation preserves valid JSON temporal strings exactly. The built-in storage adapters convert `date` and `dateTime` strings to database-native `Date` values at the database boundary, while `time` remains a string. A custom field-level `storage.serialize` function receives the validated string and owns any custom database conversion.
+
+The built-in `dateTime` conversion supports millisecond precision. A value such
+as `2026-09-01T10:20:30.123456Z` fails with HTTP 422 before the write, because
+converting it to `Date` would lose information. Trailing zeroes beyond three
+digits are accepted (`.123000Z` represents exactly `.123Z`). To retain finer
+precision in table-backed storage, use a custom `storage.serialize` function
+and a database column and driver that preserve it. The same serializer is used
+for filters and cursor comparisons, with `operation: 'filter'` and `context: null`.
+
+Response normalization preserves fractional digits returned as strings by
+storage, up to the field's declared precision, including during conversion of
+timezone offsets to UTC. It also converts valid epoch strings and `bigint`
+values from database drivers to JSON numbers, rejecting invalid or out-of-range
+epoch data.
 
 ## Output Normalization
 
@@ -105,9 +125,16 @@ All date/time values are normalized when returned from the API:
 ### Key Normalization Behaviors:
 
 1. **Boolean Normalization**: Database values of `1`/`0` are converted to `true`/`false`
-2. **Date Objects**: All date/time values are returned as JavaScript Date objects internally, then serialized to ISO 8601 strings in JSON responses
+2. **JSON Temporal Values**: `date`, `dateTime`, and `time` attributes are returned as strings that match the same public schema contract accepted on input
 3. **UTC Assumption**: MySQL DATETIME values (which lack timezone info) are assumed to be UTC
 
+Normalization runs once after the database read and again at the final response
+boundary. The final pass covers getters, computed fields, query projections,
+and finishing hooks that produce native `Date` values, including nested
+relationships in simplified write responses. A malformed non-null temporal value is not
+reported as `null`; it fails with `REST_API_TEMPORAL_DATA_INVALID` and HTTP 500
+so stored-data or enrichment defects remain visible.
+
 ## Database-Specific Handling
 
 ### MySQL
@@ -164,7 +191,7 @@ If migrating from a system that stores dates differently:
 
 1. **Local Time Storage**: Convert all dates to UTC before importing
 2. **String Storage**: Ensure strings match expected formats
-3. **Numeric Timestamps**: Use `timestamp` type for Unix timestamps
+3. **Numeric Timestamps**: Use `epochMilliseconds` or `epochSeconds`, matching the producer's actual unit
 
 ### Database Configuration
 
@@ -206,23 +233,24 @@ For optimal date handling, configure your database connection:
 
 ### Issue 3: Time Values Need Date Context
 **Symptom**: Can't perform date arithmetic on time-only values  
-**Cause**: Time values lack date context  
-**Solution**: The API attaches times to epoch date (1970-01-01) in UTC
+**Cause**: Time values intentionally have no date or timezone context
+**Solution**: Keep recurring wall-clock values as `time`; use `dateTime` when an instant is required
 
 ## Technical Implementation Details
 
 The date/time handling is implemented in two key areas:
 
 1. **Input Validation** (`json-rest-schema`):
-   - Validates format on write operations
-   - Converts all date inputs to JavaScript Date objects
-   - Ensures date-only values parse at UTC midnight
-   - Returns Date objects for storage (Knex handles DB-specific formatting)
+   - Validates strict JSON temporal strings on write operations
+   - Preserves accepted strings exactly
+   - Rejects JavaScript `Date` objects and permissive legacy date formats
 
-2. **Output Normalization** (`database-value-normalizers.js`):
+2. **Storage and Output Normalization** (`storage` adapters and `database-value-normalizers.js`):
+   - Converts validated `date` and `dateTime` strings at the database boundary
+   - Uses the same database-native representation for writes and query comparisons
    - Handles database-specific quirks (MySQL timezone issues)
-   - Ensures Date objects are properly created from database values
+   - Parses database date values before emitting schema-valid JSON strings
    - Fixes MySQL datetime strings by assuming UTC
    - Maintains consistency across different database engines
 
-This two-stage approach ensures data integrity on input and consistent formatting on output, regardless of the underlying database system. The key insight is that JavaScript Date objects are used as the common format throughout the pipeline, with database drivers handling the conversion to/from their native formats.
+This separation keeps the public JSON contract strict and serializable while still giving database drivers native values at the storage boundary.

package/index.js

@@ -34,6 +34,7 @@ export { S3Storage } from './plugins/storage/s3-storage.js'
 // Error classes for consumers who need them
 export {
   RestApiFieldsetError,
+  RestApiTemporalDataError,
   RestApiValidationError,
   RestApiResourceError,
   RestApiPayloadError

package/lib/rest-api-errors.js

@@ -1,6 +1,7 @@
 import { HookedApiError } from 'hooked-api'
 
 export const REST_API_FIELDSET_ERROR_CODE = 'REST_API_FIELDSET_INVALID'
+export const REST_API_TEMPORAL_DATA_ERROR_CODE = 'REST_API_TEMPORAL_DATA_INVALID'
 
 /**
  * REST API specific error classes that can be mapped to HTTP status codes
@@ -125,3 +126,37 @@ export class RestApiFieldsetError extends HookedApiError {
     }
   }
 }
+
+/**
+ * A non-null temporal value produced by storage or response enrichment does
+ * not satisfy the resource's public temporal contract.
+ */
+export class RestApiTemporalDataError extends HookedApiError {
+  constructor ({ field, resourceType, fieldType, source = 'database' } = {}) {
+    const fieldPath = [resourceType, field].filter(Boolean).join('.') || 'unknown field'
+    super(
+      `Invalid ${source} value for ${fieldType || 'temporal'} field '${fieldPath}'.`,
+      REST_API_TEMPORAL_DATA_ERROR_CODE
+    )
+    this.type = 'rest_api_temporal_data'
+    this.statusCode = 500
+    this.details = {
+      field,
+      resourceType,
+      fieldType,
+      source
+    }
+  }
+
+  toJSON () {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      type: this.type,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "main": "index.js",
   "type": "module",
   "scripts": {
@@ -29,7 +29,7 @@
   "description": "REST API plugin for hooked-api with JSON:API compliance",
   "dependencies": {
     "hooked-api": "^1.0.24",
-    "json-rest-schema": "^1.0.14",
+    "json-rest-schema": "^1.0.17",
     "semver": "^7.7.2"
   },
   "peerDependencies": {

package/plugins/core/connectors/lib/transport-http-helpers.js

@@ -1,4 +1,7 @@
-import { REST_API_FIELDSET_ERROR_CODE } from '../../../../lib/rest-api-errors.js'
+import {
+  REST_API_FIELDSET_ERROR_CODE,
+  REST_API_TEMPORAL_DATA_ERROR_CODE
+} from '../../../../lib/rest-api-errors.js'
 
 const JSON_API_WRITE_CONTENT_TYPES = [
   'application/vnd.api+json',
@@ -73,6 +76,14 @@ export function mapRestApiErrorToHttp (error) {
       title: 'Invalid Sparse Fieldset',
       detail: error.message
     }]
+  } else if (error.code === REST_API_TEMPORAL_DATA_ERROR_CODE) {
+    status = 500
+    errors = [{
+      status: '500',
+      code: error.code,
+      title: 'Invalid Temporal Data',
+      detail: error.message
+    }]
   } else if (error.code === 'REST_API_VALIDATION') {
     status = 422
     if (error.details?.violations?.length) {

package/plugins/core/file-handling-plugin.js

@@ -33,6 +33,7 @@
  */
 
 import { RestApiValidationError } from '../../lib/rest-api-errors.js'
+import { isRestApiError } from '../../lib/error-context.js'
 
 export const FileHandlingPlugin = {
   name: 'file-handling',
@@ -165,6 +166,7 @@ export const FileHandlingPlugin = {
             break
           }
         } catch (error) {
+          if (isRestApiError(error)) throw error
           log.warn(`Detector '${detector.name}' failed:`, error)
         }
       }
@@ -269,6 +271,7 @@ export const FileHandlingPlugin = {
             })
             log.debug(`Uploaded file for field '${fieldConfig.field}' to: ${storedUrl}`)
           } catch (error) {
+            if (isRestApiError(error)) throw error
             throw new RestApiValidationError(
               `Failed to upload file for field '${fieldConfig.field}': ${error.message}`,
               {

package/plugins/core/lib/anyapi/schema-utils.js

@@ -219,8 +219,9 @@ export const TYPE_TO_POOL = new Map([
   ['date', 'date'],
   ['datetime', 'date'],
   ['dateTime', 'date'],
-  ['timestamp', 'date'],
   ['time', 'date'],
+  ['epochMilliseconds', 'number'],
+  ['epochSeconds', 'number'],
   ['json', 'json'],
   ['object', 'json'],
 ])

package/plugins/core/lib/anyapi/utils/descriptor-helpers.js

@@ -1,5 +1,5 @@
 import { RestApiValidationError } from '../../../../../lib/rest-api-errors.js'
-import { normalizeDateValue } from '../../querying-writing/database-value-normalizers.js'
+import { normalizeValueForDatabaseStorage } from '../../querying-writing/database-value-normalizers.js'
 
 export const normalizeId = (value) => (value === null || value === undefined ? null : String(value))
 
@@ -93,7 +93,9 @@ export const coerceValueForDefinition = (value, definition, { isRelationship } =
   }
 
   if (['date', 'dateTime', 'time'].includes(type)) {
-    return normalizeDateValue(value, type)
+    return normalizeValueForDatabaseStorage(value, type, {
+      temporalPrecision: definition?.temporalPrecision
+    })
   }
 
   return value

package/plugins/core/lib/dbTablesOperations.js

@@ -300,7 +300,8 @@ function normalizeColumnShape (definition = {}) {
       return 'datetime'
     case 'time':
       return 'time'
-    case 'timestamp':
+    case 'epochMilliseconds':
+    case 'epochSeconds':
       return 'integer'
     case 'array':
     case 'object':
@@ -344,7 +345,8 @@ function normalizeDesiredTypeKind (definition = {}) {
     case 'blob':
     case 'file':
       return 'binary'
-    case 'timestamp':
+    case 'epochMilliseconds':
+    case 'epochSeconds':
       return 'integer'
     case 'string':
     case 'none':
@@ -361,6 +363,10 @@ function normalizeComparableDefault (value) {
   return String(value)
 }
 
+const hasStaticDefault = (definition = {}) => (
+  definition.defaultTo !== undefined && typeof definition.defaultTo !== 'function'
+)
+
 function normalizeDesiredColumn (tableContext, fieldName, definition, options = {}) {
   const nullable = definition.nullable === true
     ? true
@@ -375,8 +381,10 @@ function normalizeDesiredColumn (tableContext, fieldName, definition, options =
     typeKind: normalizeDesiredTypeKind(definition),
     nullable,
     required: definition.required === true,
-    hasDefault: definition.defaultTo !== undefined,
-    defaultValue: normalizeComparableDefault(definition.defaultTo),
+    hasDefault: hasStaticDefault(definition),
+    defaultValue: hasStaticDefault(definition)
+      ? normalizeComparableDefault(definition.defaultTo)
+      : undefined,
     unsigned: definition.type === 'id' ? definition.unsigned !== false : definition.unsigned === true,
     maxLength: definition.maxLength ?? null,
     numericPrecision: definition.precision ?? null,
@@ -499,8 +507,9 @@ function mapTypeToKnex (table, columnName, definition, options = {}) {
         ? table.time(columnName, { precision: temporalPrecision })
         : table.time(columnName)
 
-    case 'timestamp':
-      return table.integer(columnName)
+    case 'epochMilliseconds':
+    case 'epochSeconds':
+      return table.bigInteger(columnName)
 
     case 'array':
     case 'object':
@@ -524,7 +533,7 @@ function applyColumnConstraints (column, definition) {
     column.notNullable()
   }
 
-  if (definition.defaultTo !== undefined) {
+  if (hasStaticDefault(definition)) {
     column.defaultTo(definition.defaultTo)
   }
 
@@ -631,8 +640,9 @@ function buildColumnBuilderCode (columnName, definition, options = {}) {
         }
         break
 
-      case 'timestamp':
-        line = `table.integer(${quoteJsString(columnName)})`
+      case 'epochMilliseconds':
+      case 'epochSeconds':
+        line = `table.bigInteger(${quoteJsString(columnName)})`
         break
 
       case 'array':
@@ -658,7 +668,7 @@ function buildColumnBuilderCode (columnName, definition, options = {}) {
     line += '.notNullable()'
   }
 
-  if (definition.defaultTo !== undefined) {
+  if (hasStaticDefault(definition)) {
     line += `.defaultTo(${formatCodeLiteral(definition.defaultTo)})`
   }
 

package/plugins/core/lib/querying/knex-pagination-helpers.js

@@ -1,5 +1,6 @@
 import { getFieldValue } from '../storage/storage-mapping.js'
 import { serializeJsonApiQuery } from '../querying-writing/connectors-query-parser.js'
+import { normalizeDateValue } from '../querying-writing/database-value-normalizers.js'
 
 const buildJsonApiLink = (baseUrl, queryParams, page) => {
   const queryString = serializeJsonApiQuery(queryParams, { page })
@@ -157,7 +158,7 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
 
   if (pageCount !== undefined) {
     links.first = buildJsonApiLink(baseUrl, queryParams, { number: 1, size: pageSize })
-    links.last = buildJsonApiLink(baseUrl, queryParams, { number: pageCount, size: pageSize })
+    links.last = buildJsonApiLink(baseUrl, queryParams, { number: Math.max(1, pageCount), size: pageSize })
 
     if (page > 1) {
       links.prev = buildJsonApiLink(baseUrl, queryParams, { number: page - 1, size: pageSize })
@@ -233,15 +234,28 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
  * 4. Cursor used in 'next' link for fetching subsequent pages
  * 5. Enables efficient "WHERE (field1, field2) > (val1, val2)" queries
  */
-export const createCursor = (record, sortFields = ['id'], { schemaInfo = null } = {}) => {
+export const createCursor = (record, sortFields = ['id'], { schemaInfo = null, definitions = {} } = {}) => {
   const parts = []
   sortFields.forEach(field => {
-    const value = schemaInfo
+    let value = schemaInfo
       ? getFieldValue(record, schemaInfo, field)
       : record[field]
+    const definition = definitions[field] || schemaInfo?.schemaStructure?.[field]
+    if (value === null) {
+      parts.push(`${field}:~null`)
+      return
+    }
+    if (['date', 'dateTime', 'time'].includes(definition?.type) && value != null) {
+      value = normalizeDateValue(value, definition.type, {
+        temporalPrecision: definition.temporalPrecision,
+        fieldName: field,
+        resourceType: schemaInfo?.scopeName || schemaInfo?.tableName,
+        source: 'cursor'
+      })
+    }
     if (value !== undefined) {
       const stringValue = value instanceof Date ? value.toISOString() : String(value)
-      parts.push(`${field}:${encodeURIComponent(stringValue)}`)
+      parts.push(`${field}:${encodeURIComponent(stringValue).replace(/^~/, '%7E')}`)
     }
   })
   return parts.join(',')
@@ -301,7 +315,7 @@ export const createCursor = (record, sortFields = ['id'], { schemaInfo = null }
  */
 export const parseCursor = (cursor) => {
   try {
-    const data = {}
+    const data = Object.create(null)
     if (!cursor || cursor.trim() === '') {
       throw new Error('Empty cursor')
     }
@@ -321,7 +335,8 @@ export const parseCursor = (cursor) => {
         throw new Error('Invalid cursor format: empty field name')
       }
 
-      data[field] = decodeURIComponent(encodedValue)
+      if (Object.hasOwn(data, field)) throw new Error(`Duplicate cursor field '${field}'`)
+      data[field] = encodedValue === '~null' ? null : decodeURIComponent(encodedValue)
     }
 
     return data
@@ -413,7 +428,7 @@ export const generateCursorPaginationLinks = (
   pageSize,
   hasMore,
   sortFields = ['id'],
-  { schemaInfo = null } = {}
+  { schemaInfo = null, definitions = {} } = {}
 ) => {
   // Allow empty urlPrefix to generate relative links
   if (!records.length) return null
@@ -432,9 +447,10 @@ export const generateCursorPaginationLinks = (
   links.first = buildJsonApiLink(baseUrl, queryParams, { size: pageSize })
 
   if (hasMore && records.length > 0) {
-    const lastRecord = records[records.length - 1]
-    const nextCursor = createCursor(lastRecord, sortFields, { schemaInfo })
-    links.next = buildJsonApiLink(baseUrl, queryParams, { size: pageSize, after: nextCursor })
+    const direction = queryParams.page?.before ? 'before' : 'after'
+    const boundary = direction === 'before' ? records[0] : records[records.length - 1]
+    const nextCursor = createCursor(boundary, sortFields, { schemaInfo, definitions })
+    links.next = buildJsonApiLink(baseUrl, queryParams, { size: pageSize, [direction]: nextCursor })
   }
 
   return links
@@ -497,16 +513,16 @@ export const generateCursorPaginationLinks = (
  * 3. Added to response.meta.pagination
  * 4. Clients can use cursor directly or use the next link
  */
-export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'], { schemaInfo = null } = {}) => {
+export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'], { schemaInfo = null, definitions = {}, before = false } = {}) => {
   const meta = {
     pageSize,
     hasMore
   }
 
   if (hasMore && records.length > 0) {
-    const lastRecord = records[records.length - 1]
+    const lastRecord = before ? records[0] : records[records.length - 1]
     meta.cursor = {
-      next: createCursor(lastRecord, sortFields, { schemaInfo })
+      next: createCursor(lastRecord, sortFields, { schemaInfo, definitions })
     }
   }