@appweaver/core 1.3.0 → 1.4.0

package/resource/resource-routes.js

@@ -76,8 +76,8 @@ function resourceRoutes(name, routesConfig = {}) {
                 onRequest: routeAuth(queryConfig),
                 config: queryConfig
             }, async (request, reply) => {
-                const { page, size, sort, ...body } = request.body;
-                const response = await service.query(body.filter, page, size, sort);
+                const { page, size, sort, cursor, totalCount, ...body } = request.body;
+                const response = await service.query(body.filter, page, size, sort, cursor, totalCount);
                 return reply.send(response);
             });
         }

package/resource/resource-schema.d.ts

@@ -1,24 +1,25 @@
-import { AuthType, RecaptchaConfig, ResourceRoutesConfig, ResourceSchemaConfig } from '@appweaver/common';
-export declare const Id: import("@sinclair/typebox").TObject<{
+import { TObject, TSchema } from '@sinclair/typebox';
+import { AuthType, IdField, RecaptchaConfig, ResourceRoutesConfig, ResourceSchemaConfig } from '@appweaver/common';
+export declare const ID_STRING_MAX_LENGTH = 36;
+export declare const Id: TObject<{
     id: import("@sinclair/typebox").TInteger;
 }>;
-export declare const IdString: import("@sinclair/typebox").TObject<{
+export declare const IdString: TObject<{
     id: import("@sinclair/typebox").TString;
 }>;
-export declare const AuditData: import("@sinclair/typebox").TObject<{
-    updatedAt: import("@sinclair/typebox").TUnsafe<Date>;
-    createdAt: import("@sinclair/typebox").TUnsafe<Date>;
-    createdById: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<number | null>>;
-}>;
-export declare const QueryRequestData: import("@sinclair/typebox").TObject<{
+export declare const QueryRequestData: TObject<{
     page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     size: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<string | null>>;
+    totalCount: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
-export declare const QueryResponseData: import("@sinclair/typebox").TObject<{
+export declare const QueryResponseData: TObject<{
     resultCount: import("@sinclair/typebox").TNumber;
-    totalCount: import("@sinclair/typebox").TNumber;
+    totalCount: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<number | null>>;
+    nextCursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<string | null>>;
+    prevCursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<string | null>>;
 }>;
-export declare const AggregateRequestData: import("@sinclair/typebox").TObject<{
+export declare const AggregateRequestData: TObject<{
     from: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<Date>>;
     to: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<Date>>;
     step: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
@@ -26,3 +27,28 @@ export declare const AggregateRequestData: import("@sinclair/typebox").TObject<{
 }>;
 export declare const AggregateResponseData: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
 export declare function createSchema(name: string, routeAuthTypes: Record<keyof ResourceRoutesConfig, AuthType[] | undefined>, routeRecaptcha: Record<keyof ResourceRoutesConfig, RecaptchaConfig>): ResourceSchemaConfig;
+/**
+ * Builds the schema of a single primary key value, used wherever an id is
+ * accepted on its own (i.e. a relation input connecting an existing record).
+ *
+ * @param {IdField} [idField] - The id configuration, integer by default.
+ * @return {TSchema} The schema of the id value.
+ */
+export declare function idValueSchema(idField?: IdField): TSchema;
+/**
+ * Builds the primary key schema of a model, used as the route path parameter
+ * and as the connection shape of the relation inputs pointing at the model. A
+ * fresh object per call, since each model annotates its own schemas.
+ *
+ * @param {IdField} [idField] - The id configuration, integer by default.
+ * @return {TObject} The primary key schema of the model.
+ */
+export declare function idSchema(idField?: IdField): TObject;
+/**
+ * Builds the audit field schema of a model. The `createdById` field references
+ * the authentication model, so it follows that model's id type.
+ *
+ * @param {IdField} [authIdField] - The auth model id configuration, integer by default.
+ * @return {TObject} The schema holding all supported audit fields.
+ */
+export declare function auditSchema(authIdField?: IdField): TObject;

package/resource/resource-schema.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AggregateResponseData = exports.AggregateRequestData = exports.QueryResponseData = exports.QueryRequestData = exports.AuditData = exports.IdString = exports.Id = void 0;
+exports.AggregateResponseData = exports.AggregateRequestData = exports.QueryResponseData = exports.QueryRequestData = exports.IdString = exports.Id = exports.ID_STRING_MAX_LENGTH = void 0;
 exports.createSchema = createSchema;
+exports.idValueSchema = idValueSchema;
+exports.idSchema = idSchema;
+exports.auditSchema = auditSchema;
 const typebox_1 = require("@sinclair/typebox");
 const common_1 = require("@appweaver/common");
 const context_1 = require("../context");
@@ -9,26 +12,31 @@ const security_1 = require("../security");
 const errors_1 = require("../errors");
 const utils_1 = require("../utils");
 const schemas_1 = require("./schemas");
+// Maximum length of a string primary key, sized for the longest value the
+// supported generators produce (a 36-character UUID)
+exports.ID_STRING_MAX_LENGTH = 36;
 exports.Id = typebox_1.Type.Object({
-    id: typebox_1.Type.Integer({ minimum: 1 })
+    id: typebox_1.Type.Integer({ minimum: 1, example: 1 })
 });
 exports.IdString = typebox_1.Type.Object({
-    id: typebox_1.Type.String({ maxLength: 36 })
-});
-exports.AuditData = typebox_1.Type.Object({
-    updatedAt: (0, common_1.StringDate)(),
-    createdAt: (0, common_1.StringDate)(),
-    createdById: (0, common_1.Nullable)(typebox_1.Type.Integer({ minimum: 1, example: 1 }))
+    id: typebox_1.Type.String({ maxLength: exports.ID_STRING_MAX_LENGTH, example: 'a1b2c3d4' })
 });
+const CURSOR_EXAMPLE = 'eyJpIjo0MiwiZiI6IkhkQjVfa2VMTVlyNyJ9';
 // The sort property is declared per model instead, since its object form
 // references the sortable fields of the queried resource
 exports.QueryRequestData = typebox_1.Type.Object({
     page: typebox_1.Type.Optional(typebox_1.Type.Number({ minimum: 1, example: 1 })),
-    size: typebox_1.Type.Optional(typebox_1.Type.Number({ minimum: 0, maximum: 1000, example: 50 }))
+    size: typebox_1.Type.Optional(typebox_1.Type.Number({ minimum: 0, maximum: 2000, example: 50 })),
+    cursor: (0, common_1.Nullable)(typebox_1.Type.String({ example: CURSOR_EXAMPLE })),
+    totalCount: typebox_1.Type.Optional(typebox_1.Type.Boolean({ default: true, example: true }))
 });
+// The absent values are returned as null rather than omitted, so a client reads
+// "no further page" and "not counted" off the response instead of a missing key
 exports.QueryResponseData = typebox_1.Type.Object({
     resultCount: typebox_1.Type.Number({ example: 10 }),
-    totalCount: typebox_1.Type.Number({ example: 100 })
+    totalCount: (0, common_1.Nullable)(typebox_1.Type.Number({ example: 100 })),
+    nextCursor: (0, common_1.Nullable)(typebox_1.Type.String({ example: CURSOR_EXAMPLE })),
+    prevCursor: (0, common_1.Nullable)(typebox_1.Type.String({ example: CURSOR_EXAMPLE }))
 });
 // The select and dateField properties are declared per model instead, since
 // they reference the aggregatable fields of the aggregated resource
@@ -43,6 +51,9 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
     const resourceModel = (0, context_1.injectModel)(name);
     const resourceName = (0, common_1.camelToSnakeCase)(name, ' ');
     const tag = (0, common_1.plural)(name);
+    // The path parameter follows the primary key type of this model, so a string
+    // id is neither coerced to a number nor rejected by the request validation
+    const idParams = resourceModel.idModel;
     // Register the recursive query filter and sort schemas of all loaded models,
     // referenced by the query, aggregate, and export request bodies
     (0, schemas_1.registerQueryFilterSchemas)();
@@ -85,7 +96,7 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
                 200: resourceModel.readOneModel,
                 ...errors_1.AllErrorResponses
             },
-            params: exports.Id
+            params: idParams
         },
         querySchema: {
             tags: [tag],
@@ -134,7 +145,7 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
                 ...errors_1.AllErrorResponses
             },
             body: resourceModel.updateOneModel,
-            params: exports.Id
+            params: idParams
         },
         deleteSchema: {
             tags: [tag],
@@ -146,7 +157,7 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
                 200: resourceModel.readOneModel,
                 ...errors_1.AllErrorResponses
             },
-            params: exports.Id
+            params: idParams
         },
         exportSchema: {
             tags: [tag],
@@ -178,7 +189,7 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
                 ...errors_1.AllErrorResponses
             },
             body: resourceModel.fileUploadModel,
-            params: exports.Id
+            params: idParams
         },
         fileDeleteSchema: {
             tags: [tag],
@@ -191,7 +202,7 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
                 ...errors_1.AllErrorResponses
             },
             body: resourceModel.fileDeleteModel,
-            params: exports.Id
+            params: idParams
         }
     };
     for (const resourceConfig of Object.values(resourceSchemaConfig)) {
@@ -199,3 +210,40 @@ function createSchema(name, routeAuthTypes, routeRecaptcha) {
     }
     return resourceSchemaConfig;
 }
+/**
+ * Builds the schema of a single primary key value, used wherever an id is
+ * accepted on its own (i.e. a relation input connecting an existing record).
+ *
+ * @param {IdField} [idField] - The id configuration, integer by default.
+ * @return {TSchema} The schema of the id value.
+ */
+function idValueSchema(idField) {
+    return (0, common_1.idFieldType)(idField) === 'string'
+        ? exports.IdString.properties.id
+        : exports.Id.properties.id;
+}
+/**
+ * Builds the primary key schema of a model, used as the route path parameter
+ * and as the connection shape of the relation inputs pointing at the model. A
+ * fresh object per call, since each model annotates its own schemas.
+ *
+ * @param {IdField} [idField] - The id configuration, integer by default.
+ * @return {TObject} The primary key schema of the model.
+ */
+function idSchema(idField) {
+    return typebox_1.Type.Object({ id: idValueSchema(idField) });
+}
+/**
+ * Builds the audit field schema of a model. The `createdById` field references
+ * the authentication model, so it follows that model's id type.
+ *
+ * @param {IdField} [authIdField] - The auth model id configuration, integer by default.
+ * @return {TObject} The schema holding all supported audit fields.
+ */
+function auditSchema(authIdField) {
+    return typebox_1.Type.Object({
+        updatedAt: (0, common_1.StringDate)(),
+        createdAt: (0, common_1.StringDate)(),
+        createdById: (0, common_1.Nullable)(idValueSchema(authIdField))
+    });
+}

package/resource/resource-service.d.ts

@@ -1,4 +1,4 @@
-import { ActionType, AggregateResponse, AggregateSelect, IResourceService, QueryFilter, QueryResponse, QuerySort, Resource, ResourceClient, ResourceData } from '@appweaver/common';
+import { ActionType, AggregateResponse, AggregateSelect, AggregateSelected, IResourceService, QueryFilter, QueryResponse, QuerySort, Resource, ResourceId, ResourceClient, ResourceData } from '@appweaver/common';
 export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Resource, Create = ResourceData<Resource>, Update = Partial<ResourceData<Resource>>, Query = QueryFilter<ReadOne>> implements IResourceService<ReadOne, ReadMany, Create, Update, Query> {
     readonly modelName: string;
     /**
@@ -24,14 +24,14 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * configured for output on the find action. A resource event is emitted after
      * a successful lookup.
      *
-     * @param {number} id The id of the resource to find.
+     * @param {ResourceId} id The id of the resource to find.
      * @returns {Promise<Object>} The found resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
      * out by the read restrictions, 403 if the access check denies it, and 500 on
      * a database error.
      */
-    find(id: number): Promise<ReadOne>;
+    find(id: ResourceId): Promise<ReadOne>;
     /**
      * Queries a page of resources matching the provided filter. The filter is
      * mapped to a database query, combined with the optional `searchText` full
@@ -47,21 +47,28 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * as plain field values. Its `searchText` property, if present, is passed to
      * {@link ResourceService.textSearchQuery} instead of being matched as a
      * field.
-     * @param {number} [page] The one-based page number of results to return.
+     * @param {number} [page] The one-based page number of results to return,
+     * ignored when a cursor is given.
      * @param {number} [size] The maximum number of results per page.
      * @param {QuerySort} [sort] The fields to sort by, either as a comma-separated
      * list where a field prefixed with `-` is sorted in descending order
-     * (i.e. `-createdAt,id`), or as an object of field directions
+     * (i.e. `-createdAt,title`), or as an object of field directions
      * (i.e. `{ createdAt: 'desc', id: 'asc' }`). Both forms support the fields of
      * the included to-one relations, given with a dot notation (`author.createdAt`)
      * or as a nested object (`{ author: { createdAt: 'desc' } }`).
+     * @param {string} [cursor] The cursor of the page to return, as issued in the
+     * `nextCursor` or `prevCursor` of an earlier response, which also carries the
+     * direction the page runs in. Takes precedence over `page`.
+     * @param {boolean} [totalCount] Whether to count all matching resources, which
+     * costs a scan of every one of them.
      * @returns {Promise<QueryResponse<Object>>} The paged query response containing
-     * the returned resources, the count of the returned items and the total count
-     * of matching resources.
+     * the returned resources, the count of the returned items, the cursors of the
+     * adjacent pages, and the total count unless it was opted out of.
      * @throws {@link HttpError} 400 if the sort input names a field that cannot be
-     * sorted by, and 500 on a database error.
+     * sorted by or the cursor was issued for another filter or sort order, and 500
+     * on a database error.
      */
-    query(filter?: Query, page?: number, size?: number, sort?: QuerySort<ReadMany>): Promise<QueryResponse<ReadMany>>;
+    query(filter?: Query, page?: number, size?: number, sort?: QuerySort<ReadMany>, cursor?: string | null, totalCount?: boolean): Promise<QueryResponse<ReadMany>>;
     /**
      * Aggregates resources matching the provided filter over a date range, both
      * as a single overall result and as a series of results for the equally sized
@@ -92,11 +99,13 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * When false, the step is interpreted in seconds.
      * @returns {Promise<AggregateResponse<Object>>} The aggregation response with
      * the overall total and one result per period, each labeled with the median
-     * date of its period.
+     * date of its period. It is typed by the fields the selection named, not by
+     * the whole model, whenever the selection is passed as an object literal or
+     * annotated with `satisfies`.
      * @throws {@link HttpError} 400 if the selection is empty or names a field or
      * operator that cannot be aggregated, and 500 on a database error.
      */
-    aggregate(filter: Query | undefined, select: AggregateSelect<ReadOne>, dateField?: string, from?: string, to?: string, step?: number, safeIncrement?: boolean): Promise<AggregateResponse<ReadOne>>;
+    aggregate<S extends AggregateSelect<ReadOne>>(filter: Query | undefined, select: S, dateField?: string, from?: string, to?: string, step?: number, safeIncrement?: boolean): Promise<AggregateResponse<AggregateSelected<ReadOne, S>>>;
     /**
      * Creates a new resource. The provided data is merged with the write
      * restrictions, checked for access, sanitized against the model configuration
@@ -124,7 +133,7 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * and a resource event carrying both the previous and the current state is
      * emitted after a successful update.
      *
-     * @param {number} id The id of the resource to update.
+     * @param {ResourceId} id The id of the resource to update.
      * @param {Object} data The partial data to update the resource with, including
      * any inline relation and file payloads.
      * @returns {Promise<Object>} The updated resource with its virtual fields and
@@ -134,21 +143,21 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * if an inline relation payload is missing required fields or the relation
      * does not accept new records, and 500 on a database error.
      */
-    update(id: number, data: Update): Promise<ReadOne>;
+    update(id: ResourceId, data: Update): Promise<ReadOne>;
     /**
      * Deletes an existing resource by its id. The current record is loaded with
      * the read restrictions applied and checked for access before it is deleted
      * inside a single transaction. The resource cache is invalidated and a
      * resource event is emitted after a successful delete.
      *
-     * @param {number} id The id of the resource to delete.
+     * @param {ResourceId} id The id of the resource to delete.
      * @returns {Promise<Object>} The deleted resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
      * out by the read restrictions, 403 if the access check denies the action, and
      * 500 on a database error.
      */
-    delete(id: number): Promise<ReadOne>;
+    delete(id: ResourceId): Promise<ReadOne>;
     /**
      * This method should be overridden with custom logic for restricting read
      * operations on specific data for currently logged-in user and other
@@ -160,7 +169,7 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      *
      * @param {ActionType} action The called action method on this service (find,
      * query, aggregate, update, or delete)
-     * @param {Object|number} data The passed data to the called function can be
+     * @param {Object|ResourceId} data The passed data to the called function can be
      * number or object. If the data is a type of number, then it represents the
      * resource id, otherwise it depends on the action and can be one of the
      * following:

package/resource/resource-service.js

@@ -48,7 +48,7 @@ class ResourceService {
      * configured for output on the find action. A resource event is emitted after
      * a successful lookup.
      *
-     * @param {number} id The id of the resource to find.
+     * @param {ResourceId} id The id of the resource to find.
      * @returns {Promise<Object>} The found resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
@@ -95,52 +95,85 @@ class ResourceService {
      * as plain field values. Its `searchText` property, if present, is passed to
      * {@link ResourceService.textSearchQuery} instead of being matched as a
      * field.
-     * @param {number} [page] The one-based page number of results to return.
+     * @param {number} [page] The one-based page number of results to return,
+     * ignored when a cursor is given.
      * @param {number} [size] The maximum number of results per page.
      * @param {QuerySort} [sort] The fields to sort by, either as a comma-separated
      * list where a field prefixed with `-` is sorted in descending order
-     * (i.e. `-createdAt,id`), or as an object of field directions
+     * (i.e. `-createdAt,title`), or as an object of field directions
      * (i.e. `{ createdAt: 'desc', id: 'asc' }`). Both forms support the fields of
      * the included to-one relations, given with a dot notation (`author.createdAt`)
      * or as a nested object (`{ author: { createdAt: 'desc' } }`).
+     * @param {string} [cursor] The cursor of the page to return, as issued in the
+     * `nextCursor` or `prevCursor` of an earlier response, which also carries the
+     * direction the page runs in. Takes precedence over `page`.
+     * @param {boolean} [totalCount] Whether to count all matching resources, which
+     * costs a scan of every one of them.
      * @returns {Promise<QueryResponse<Object>>} The paged query response containing
-     * the returned resources, the count of the returned items and the total count
-     * of matching resources.
+     * the returned resources, the count of the returned items, the cursors of the
+     * adjacent pages, and the total count unless it was opted out of.
      * @throws {@link HttpError} 400 if the sort input names a field that cannot be
-     * sorted by, and 500 on a database error.
+     * sorted by or the cursor was issued for another filter or sort order, and 500
+     * on a database error.
      */
-    async query(filter = {}, page = 1, size = 50, sort = '-createdAt,id') {
+    async query(filter = {}, page = 1, size = 50, sort = '-createdAt', cursor, totalCount = true) {
         const restrictions = await this.readRestrictions('query', filter);
         const textSearch = this.extractTextSearchQuery(filter);
         const mappedFilter = (0, utils_2.mapQueryFilter)(filter, this._client.name);
         const query = { AND: [mappedFilter, textSearch, restrictions] };
         const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'query');
-        const orderBy = (0, utils_2.mapSortValues)(sort, this._client.name, 'query');
+        const orderBy = (0, utils_2.mapStableSortValues)(sort, this._client.name, 'query');
+        // Binding to the mapped query rather than the filter also invalidates a
+        // cursor on a changed text search or read restriction
+        const fingerprint = (0, utils_2.queryFingerprint)(this._client.name, query, orderBy);
+        const decodedCursor = (0, utils_2.decodeCursor)(cursor, fingerprint);
+        // One record past the page tells whether a further page exists
+        const backward = decodedCursor?.backward === true;
+        const take = size > 0 ? size + 1 : 0;
+        const findMany = this._client.findMany({
+            where: { ...query },
+            include: includeRelations,
+            // A cursor skips the record it addresses, an offset the pages before it
+            cursor: decodedCursor ? { id: decodedCursor.id } : undefined,
+            skip: decodedCursor ? 1 : (page - 1) * size,
+            take: backward ? -take : take,
+            orderBy
+        });
         let resources;
-        let totalCount;
+        let count;
         try {
-            [resources, totalCount] = await this._db.client().$transaction([
-                this._client.findMany({
-                    where: { ...query },
-                    include: includeRelations,
-                    skip: (page - 1) * size,
-                    take: size,
-                    orderBy
-                }),
-                this._client.count({
-                    where: { ...query }
-                })
-            ]);
+            if (totalCount) {
+                [resources, count] = await this._db
+                    .client()
+                    .$transaction([
+                    findMany,
+                    this._client.count({ where: { ...query } })
+                ]);
+            }
+            else {
+                resources = await findMany;
+            }
         }
         catch (e) {
             throw new errors_1.HttpError(`${this._client.name} query error`, 500, e);
         }
+        // The over-fetched record leads a backward page and trails a forward one
+        const hasMore = resources.length > size;
+        if (hasMore) {
+            resources = backward
+                ? resources.slice(resources.length - size)
+                : resources.slice(0, size);
+        }
+        // The page a cursor was followed from always exists
+        const hasNext = backward || hasMore;
+        const hasPrev = backward ? hasMore : !!decodedCursor || page > 1;
         this._events.emitResourceEvent(this._client.name, 'query', {
             current: resources
         });
         return {
             resultCount: resources.length,
-            totalCount,
+            totalCount: count ?? null,
+            ...(0, utils_2.pageCursors)(resources, fingerprint, hasNext, hasPrev),
             items: resources.map((resource) => this.projectResource(resource))
         };
     }
@@ -174,7 +207,9 @@ class ResourceService {
      * When false, the step is interpreted in seconds.
      * @returns {Promise<AggregateResponse<Object>>} The aggregation response with
      * the overall total and one result per period, each labeled with the median
-     * date of its period.
+     * date of its period. It is typed by the fields the selection named, not by
+     * the whole model, whenever the selection is passed as an object literal or
+     * annotated with `satisfies`.
      * @throws {@link HttpError} 400 if the selection is empty or names a field or
      * operator that cannot be aggregated, and 500 on a database error.
      */
@@ -284,7 +319,7 @@ class ResourceService {
      * and a resource event carrying both the previous and the current state is
      * emitted after a successful update.
      *
-     * @param {number} id The id of the resource to update.
+     * @param {ResourceId} id The id of the resource to update.
      * @param {Object} data The partial data to update the resource with, including
      * any inline relation and file payloads.
      * @returns {Promise<Object>} The updated resource with its virtual fields and
@@ -355,7 +390,7 @@ class ResourceService {
      * inside a single transaction. The resource cache is invalidated and a
      * resource event is emitted after a successful delete.
      *
-     * @param {number} id The id of the resource to delete.
+     * @param {ResourceId} id The id of the resource to delete.
      * @returns {Promise<Object>} The deleted resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
@@ -408,7 +443,7 @@ class ResourceService {
      *
      * @param {ActionType} action The called action method on this service (find,
      * query, aggregate, update, or delete)
-     * @param {Object|number} data The passed data to the called function can be
+     * @param {Object|ResourceId} data The passed data to the called function can be
      * number or object. If the data is a type of number, then it represents the
      * resource id, otherwise it depends on the action and can be one of the
      * following:

package/resource/schemas/resource-sort-schema.js

@@ -101,10 +101,10 @@ function registerQuerySortSchemas() {
 function querySortSchema(modelName) {
     return typebox_1.Type.Optional(typebox_1.Type.Union([
         typebox_1.Type.String({
-            example: '-createdAt,id',
+            example: '-createdAt,title',
             description: 'Comma-separated list of fields to sort by, where a field prefixed ' +
                 'with `-` is sorted in descending order and a dot notation path ' +
-                'targets a field of an included relation (i.e. `-author.createdAt,id`)'
+                'targets a field of an included relation'
         }),
         typebox_1.Type.Ref((0, exports.querySortName)(modelName))
     ], {

package/resource/utils/cursor-util.d.ts

@@ -0,0 +1,60 @@
+import { QueryResponse, ResourceId } from '@appweaver/common';
+/** The cursors a query response carries, kept in step with the response contract. */
+export type PageCursors = Pick<QueryResponse<unknown>, 'nextCursor' | 'prevCursor'>;
+/** A decoded cursor, holding the record it points at and the direction to page in. */
+export type DecodedCursor = {
+    id: ResourceId;
+    /** True when the cursor pages towards the preceding records */
+    backward: boolean;
+};
+/**
+ * Builds the fingerprint identifying the query a cursor belongs to. A cursor
+ * only yields the intended records while the resource, the query, and the order
+ * stay the same, so it carries the fingerprint and is rejected on mismatch.
+ *
+ * @param {string} resourceName - The name of the queried model.
+ * @param {Object} query - The mapped database query the cursor was issued for.
+ * @param {Object[]} orderBy - The mapped order entries the cursor was issued for.
+ * @return {string} The fingerprint of the query.
+ */
+export declare function queryFingerprint(resourceName: string, query: any, orderBy: any[]): string;
+/**
+ * Encodes the cursor of a page adjacent to a query result. The direction belongs
+ * to the cursor rather than to the request, so a caller cannot pair one with a
+ * direction it was not issued for.
+ *
+ * @param {ResourceId} id - The primary key of the record the page continues from.
+ * @param {string} fingerprint - The fingerprint of the query, as built by
+ * {@link queryFingerprint}.
+ * @param {boolean} [backward] - Whether the cursor pages towards the preceding
+ * records.
+ * @return {string} The encoded cursor.
+ */
+export declare function encodeCursor(id: ResourceId, fingerprint: string, backward?: boolean): string;
+/**
+ * Builds the cursors of the pages adjacent to a returned page, each addressing
+ * the record of this page it continues from. A page that has no neighbour in a
+ * direction, and an empty page, yield null rather than an absent cursor.
+ *
+ * @param {Object[]} resources - The records of the returned page, in the order
+ * they were queried in.
+ * @param {string} fingerprint - The fingerprint of the query the page belongs to.
+ * @param {boolean} hasNext - Whether a page follows the returned one.
+ * @param {boolean} hasPrev - Whether a page precedes the returned one.
+ * @return {PageCursors} The cursors of the existing adjacent pages.
+ */
+export declare function pageCursors<T>(resources: T[], fingerprint: string, hasNext: boolean, hasPrev: boolean): PageCursors;
+/**
+ * Decodes the cursor a query request carries, resolving the record the page
+ * continues from and the direction it runs in.
+ *
+ * @param {string} [cursor] - The cursor of the request, which may be the null
+ * one of a page that does not exist.
+ * @param {string} fingerprint - The fingerprint of the query the cursor is used
+ * on, as built by {@link queryFingerprint}.
+ * @return {DecodedCursor | undefined} The decoded cursor, or `undefined` when the
+ * request carries none.
+ * @throws {HttpError} 400 if the cursor is malformed, or was issued for another
+ * resource, filter, or sort order.
+ */
+export declare function decodeCursor(cursor: string | null | undefined, fingerprint: string): DecodedCursor | undefined;