@appweaver/core 1.3.1 → 1.4.1

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;

package/resource/utils/cursor-util.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryFingerprint = queryFingerprint;
+exports.encodeCursor = encodeCursor;
+exports.pageCursors = pageCursors;
+exports.decodeCursor = decodeCursor;
+const common_1 = require("@appweaver/common");
+const errors_1 = require("../../errors");
+/**
+ * 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.
+ */
+function queryFingerprint(resourceName, query, orderBy) {
+    const serialized = stableStringify([resourceName, query ?? {}, orderBy]);
+    return (0, common_1.makeHash)(serialized, 'sha256', 'base64url').slice(0, 16);
+}
+/**
+ * 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.
+ */
+function encodeCursor(id, fingerprint, backward = false) {
+    const payload = { i: id, f: fingerprint };
+    if (backward) {
+        payload.b = true;
+    }
+    return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+}
+/**
+ * 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.
+ */
+function pageCursors(resources, fingerprint, hasNext, hasPrev) {
+    // A queried record always carries its primary key, which a model type need
+    // not declare
+    const first = resources[0];
+    const last = resources[resources.length - 1];
+    if (!first || !last) {
+        return { nextCursor: null, prevCursor: null };
+    }
+    return {
+        nextCursor: hasNext ? encodeCursor(last.id, fingerprint) : null,
+        prevCursor: hasPrev ? encodeCursor(first.id, fingerprint, true) : null
+    };
+}
+/**
+ * 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.
+ */
+function decodeCursor(cursor, fingerprint) {
+    if (!cursor) {
+        return undefined;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new errors_1.HttpError('Invalid pagination cursor', 400, e);
+    }
+    if (!(0, common_1.isPlainObject)(payload) || payload.i === undefined) {
+        throw new errors_1.HttpError('Invalid pagination cursor', 400);
+    }
+    if (payload.f !== fingerprint) {
+        throw new errors_1.HttpError('Pagination cursor does not match the filter and sort of this query', 400);
+    }
+    return { id: payload.i, backward: payload.b === true };
+}
+/**
+ * Serializes a value with its object keys in a stable order, so two equal
+ * queries fingerprint identically whatever order their properties arrived in.
+ *
+ * @param {any} value - The value to serialize.
+ * @return {string} The serialized value.
+ */
+function stableStringify(value) {
+    if ((0, common_1.isArray)(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if ((0, common_1.isPlainObject)(value)) {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}

package/resource/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './aggregate-util';
+export * from './cursor-util';
 export * from './filter-util';
 export * from './relation-util';
 export * from './sort-util';

package/resource/utils/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./aggregate-util"), exports);
+__exportStar(require("./cursor-util"), exports);
 __exportStar(require("./filter-util"), exports);
 __exportStar(require("./relation-util"), exports);
 __exportStar(require("./sort-util"), exports);

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

@@ -1,4 +1,4 @@
-import { ActionType } from '@appweaver/common';
+import { ActionType, ResourceId } from '@appweaver/common';
 /** The nested write actions a single relation field can be mapped to. */
 export type RelationActions = Record<string, Partial<{
     connect: any;
@@ -74,11 +74,11 @@ export declare function missingRelationFields(resourceName: string | undefined,
  * user. Returns undefined when the model does not audit the `createdById` field or when no user is authenticated.
  *
  * @param {string} resourceName - The name of the model the audit relation is built for.
- * @return {{connect: {id: number}}|undefined} The connect action pointing at the id of the currently authenticated
+ * @return {{connect: {id: ResourceId}}|undefined} The connect action pointing at the id of the currently authenticated
  * user, or undefined if the model does not audit the `createdById` field or no user is authenticated.
  */
 export declare function createdByConnect(resourceName: string): {
     connect: {
-        id: number;
+        id: ResourceId;
     };
 } | undefined;

package/resource/utils/relation-util.js

@@ -9,6 +9,9 @@ const common_1 = require("@appweaver/common");
 const context_1 = require("../../context");
 const security_1 = require("../../security");
 const errors_1 = require("../../errors");
+/** Levels of a self referencing relation read when the relation configures no
+ * `maxDepth`, i.e. the relation itself and nothing below it. */
+const DEFAULT_RELATION_MAX_DEPTH = 1;
 /**
  * Builds the Prisma `include` clause for the relation and file fields of a resource model. A field is included when
  * its configured output type allows it for the given action, or always when no action is specified, and the relations
@@ -41,7 +44,7 @@ function mapRelationInclusions(resourceName, action) {
         }
         // Check if the relation should be included based on the output type
         if (shouldIncludeRelation(relationField?.output?.type, action)) {
-            inclusion[key] = buildNestedInclusion(relationField, action);
+            inclusion[key] = buildNestedInclusion(relationField, key, action);
         }
     }
     return inclusion;
@@ -276,7 +279,7 @@ function missingRelationFields(resourceName, data) {
  * user. Returns undefined when the model does not audit the `createdById` field or when no user is authenticated.
  *
  * @param {string} resourceName - The name of the model the audit relation is built for.
- * @return {{connect: {id: number}}|undefined} The connect action pointing at the id of the currently authenticated
+ * @return {{connect: {id: ResourceId}}|undefined} The connect action pointing at the id of the currently authenticated
  * user, or undefined if the model does not audit the `createdById` field or no user is authenticated.
  */
 function createdByConnect(resourceName) {
@@ -294,34 +297,67 @@ function createdByConnect(resourceName) {
         : undefined;
 }
 /**
- * Resolves the inclusion value of a single relation field by walking its configured nested output includes
- * recursively. Returns `true` when the relation has no nested includes to apply for the given action, or a nested
- * `include` clause otherwise.
+ * Resolves the inclusion value of a single relation field, walking both the levels a self referencing relation
+ * repeats itself for and the nested includes it configures. Returns `true` when the relation reads no further than
+ * itself for the given action, or a nested `include` clause otherwise.
+ *
+ * A relation whose related model holds the same relation again points back at its own model, so it repeats itself
+ * down the tree up to its configured `output.maxDepth`, letting a category carry its ancestors without every level
+ * being spelled out. An `output.include` entry naming that same relation configures the level itself and replaces
+ * the repetition.
  *
  * @param {RelationField} relationField - The configuration of the relation whose inclusion value is resolved, read
- * from its `output.include` property.
+ * from its `output.include` and `output.maxDepth` properties.
+ * @param {string} key - The field name the relation is declared under, matched against the related model to detect a
+ * relation pointing back at its own model.
  * @param {ActionType} [action] - The action the inclusions are built for, matched against the configured output type
  * of every nested relation.
- * @return {boolean|Object} True if the relation has no nested relations to include for the given action, or the
- * nested `include` clause otherwise.
+ * @param {number} [depth=1] - The level of the relation being resolved, counting the relation itself as the first.
+ * @return {boolean|Object} True if the relation reads no further than itself, or the nested `include` clause
+ * otherwise.
  */
-function buildNestedInclusion(relationField, action) {
+function buildNestedInclusion(relationField, key, action, depth = 1) {
     const nestedIncludeConfig = relationField?.output?.include;
-    if (!nestedIncludeConfig || Object.keys(nestedIncludeConfig).length === 0) {
-        return true;
-    }
     const nestedInclusion = {};
-    for (const [nestedKey, nestedOutput] of Object.entries(nestedIncludeConfig)) {
+    // A file field carries no related model, so it reads no further than itself
+    const relatedModel = relationField?.model
+        ? (0, context_1.injectModel)((0, common_1.capitalize)(relationField.model), false)
+        : undefined;
+    const selfRelation = selfReferencingRelation(relatedModel, key);
+    const maxDepth = relationField?.output?.maxDepth ?? DEFAULT_RELATION_MAX_DEPTH;
+    if (selfRelation && depth < maxDepth && !nestedIncludeConfig?.[key]) {
+        nestedInclusion[key] = buildNestedInclusion({ ...selfRelation, output: relationField.output }, key, action, depth + 1);
+    }
+    for (const [nestedKey, nestedOutput] of Object.entries(nestedIncludeConfig ?? {})) {
         // Check if the nested relation should be included
-        if (shouldIncludeRelation(nestedOutput?.type, action)) {
-            // Recursively build nested inclusions
-            nestedInclusion[nestedKey] = buildNestedInclusion({ output: nestedOutput }, action);
+        if (!shouldIncludeRelation(nestedOutput?.type, action)) {
+            continue;
         }
+        // The related model carries the field the nested include names, so each
+        // level is resolved against the model it actually belongs to
+        const nestedRelation = relatedModel?.config?.relations?.[nestedKey] ??
+            relatedModel?.config?.files?.[nestedKey];
+        nestedInclusion[nestedKey] = buildNestedInclusion({ ...nestedRelation, output: nestedOutput }, nestedKey, action);
     }
     return Object.keys(nestedInclusion).length > 0
         ? { include: nestedInclusion }
         : true;
 }
+/**
+ * Reads the relation a related model holds under the given field name, when it points back at that same model. It is
+ * the relation a self referencing field repeats itself through, i.e. the `parent` of the parent of a category.
+ *
+ * @param {ResourceModel} [model] - The related model the field is looked up on.
+ * @param {string} key - The field name of the relation.
+ * @return {RelationField | undefined} The relation of the model under that name when it references the model itself,
+ * undefined otherwise.
+ */
+function selfReferencingRelation(model, key) {
+    const relation = key ? model?.config?.relations?.[key] : undefined;
+    return relation && (0, common_1.capitalize)(relation.model) === model?.name
+        ? relation
+        : undefined;
+}
 /**
  * Decides whether a relation with the given configured output type is included for the given action. The `none` type
  * is never included, the `single` type is excluded from the query action, and the `multiple` type is only included on

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

@@ -18,3 +18,14 @@ import { ActionType, QuerySort } from '@appweaver/common';
  * direction, or targets a relation that the action does not include in its response.
  */
 export declare function mapSortValues(sort: QuerySort, resourceName: string, action?: ActionType): any[];
+/**
+ * Maps a sort input the same way {@link mapSortValues} does, and terminates it with the primary key when no entry
+ * orders by it. Without a total order, records sharing every sort value can be skipped or repeated across pages.
+ *
+ * @param {QuerySort} sort - The sort input to map, as a comma-separated field list or a sort object.
+ * @param {string} resourceName - The name of the model the sort is applied on.
+ * @param {ActionType} [action] - The action the sort is applied on. Defaults to the query action.
+ * @return {Object[]} The `orderBy` entries, ending in a unique one.
+ * @throws {HttpError} 400 under the same conditions as {@link mapSortValues}.
+ */
+export declare function mapStableSortValues(sort: QuerySort, resourceName: string, action?: ActionType): any[];

package/resource/utils/sort-util.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapSortValues = mapSortValues;
+exports.mapStableSortValues = mapStableSortValues;
 const common_1 = require("@appweaver/common");
 const context_1 = require("../../context");
 const errors_1 = require("../../errors");
@@ -46,6 +47,23 @@ function mapSortValues(sort, resourceName, action = 'query') {
     }
     return orderBy;
 }
+/**
+ * Maps a sort input the same way {@link mapSortValues} does, and terminates it with the primary key when no entry
+ * orders by it. Without a total order, records sharing every sort value can be skipped or repeated across pages.
+ *
+ * @param {QuerySort} sort - The sort input to map, as a comma-separated field list or a sort object.
+ * @param {string} resourceName - The name of the model the sort is applied on.
+ * @param {ActionType} [action] - The action the sort is applied on. Defaults to the query action.
+ * @return {Object[]} The `orderBy` entries, ending in a unique one.
+ * @throws {HttpError} 400 under the same conditions as {@link mapSortValues}.
+ */
+function mapStableSortValues(sort, resourceName, action = 'query') {
+    const orderBy = mapSortValues(sort, resourceName, action);
+    if (!orderBy.some((entry) => 'id' in entry)) {
+        orderBy.push({ id: 'asc' });
+    }
+    return orderBy;
+}
 /**
  * Flattens a sort input into the list of its field paths and directions, keeping the order the fields were declared
  * in. String inputs are split on commas, with a `-` or `+` prefix selecting the direction, and object inputs are

package/security/api-key/api-key-auth.js

@@ -26,7 +26,9 @@ exports.apiKeyAuth = (0, fastify_plugin_1.default)(async (server) => {
         // Use configured delimiter to split an API key and separate ID from the
         // rest of the key value
         const apiKeyParts = sanitizedApiKey.split(common_1.config.SECURITY_API_KEY_DELIMITER);
-        const apiKeyId = parseInt(apiKeyParts.shift() ?? '', 10);
+        // The id prefix is read back in the primary key type of the ApiKey model,
+        // which can be configured as a string like on any other model
+        const apiKeyId = (0, common_1.toResourceId)(apiKeyParts.shift() ?? '', (0, context_1.injectModel)('ApiKey', false)?.config?.id);
         const apiKeyValue = apiKeyParts.join(common_1.config.SECURITY_API_KEY_DELIMITER);
         const cacheKey = cacheService.buildCacheKey({
             baseKey: `apikey:${apiKeyId}`,
@@ -35,6 +37,7 @@ exports.apiKeyAuth = (0, fastify_plugin_1.default)(async (server) => {
         let apiKey = await cacheService.getCachedValue(cacheKey);
         if (!apiKey) {
             try {
+                // The generated client types the id after the configured primary key
                 apiKey = await db
                     .client()
                     .apiKey.findFirst({ where: { id: apiKeyId } });

package/security/auth-service.d.ts

@@ -1,14 +1,14 @@
-import { AuthScope, AuthSource, AuthUser, RouteConfig } from '@appweaver/common';
+import { AuthScope, AuthSource, AuthUser, ResourceId, RouteConfig } from '@appweaver/common';
 import { AuthTokens, JwtPayload, UserAdditionalData } from '../types';
 export declare class AuthService {
     /**
      * Finds an authenticated user by their unique identifier.
      *
-     * @param {number} id - The unique identifier of the authenticated user to find.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to find.
      * @return {Promise<AuthUser | null>} A promise that resolves to the authenticated user object if found, otherwise
      * null.
      */
-    findById(id: number): Promise<AuthUser | null>;
+    findById(id: ResourceId): Promise<AuthUser | null>;
     /**
      * Retrieves a user by their username.
      *
@@ -19,12 +19,12 @@ export declare class AuthService {
     /**
      * Updates an authenticated user's information in the system.
      *
-     * @param {number} id - The unique identifier of the authenticated user to be updated.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to be updated.
      * @param {Partial<AuthUser> & { password?: string }} data - The partial user data to update, optionally including a
      * password.
      * @return {Promise<AuthUser>} A promise that resolves to the updated authenticated user object.
      */
-    updateAuthUser(id: number, data: Partial<AuthUser> & {
+    updateAuthUser(id: ResourceId, data: Partial<AuthUser> & {
         password?: string;
     }): Promise<AuthUser>;
     /**
@@ -112,9 +112,9 @@ export declare class AuthService {
     /**
      * Logs out a user by updating their authentication information with a logout timestamp.
      *
-     * @param {number} id - The unique identifier of the user to be logged out.
+     * @param {ResourceId} id - The unique identifier of the user to be logged out.
      * @return {Promise<boolean>} A promise that resolves to a boolean indicating whether the logout operation was
      * successful.
      */
-    logout(id: number): Promise<boolean>;
+    logout(id: ResourceId): Promise<boolean>;
 }