@appweaver/data 0.0.0-stage → 2.0.1

package/resource/utils/relation-util.js

@@ -0,0 +1,400 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapRelationInclusions = mapRelationInclusions;
+exports.mapRelationActions = mapRelationActions;
+exports.unknownRelationFields = unknownRelationFields;
+exports.missingRelationFields = missingRelationFields;
+exports.createdByConnect = createdByConnect;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+const delete_util_1 = require("./delete-util");
+/** 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
+ * configured with an output count contribute to the `_count` selection instead.
+ *
+ * @param {string} resourceName - The name of the model whose relations are included.
+ * @param {ActionType} [action] - The action the inclusions are built for, matched against the configured output type
+ * of every field. When omitted, all fields whose output type is not `none` are included.
+ * @return {Object} The `include` clause mapping each included field to `true` or to its own nested `include` clause,
+ * extended with a `_count` selection for the relations configured with an output count.
+ */
+function mapRelationInclusions(resourceName, action) {
+    const inclusion = {};
+    const resourceModel = (0, core_1.injectModel)(resourceName);
+    const relationConfig = resourceModel.config.relations;
+    const fileConfig = resourceModel.config.files;
+    const relationModelProps = (0, common_1.extractSchemaProperties)(resourceModel.relationsModel);
+    const fileModelProps = (0, common_1.extractSchemaProperties)(resourceModel.filesModel);
+    // Add relation and file fields to the inclusion map if the include type is
+    // satisfied or the requested action is not specified. Also, add the count
+    // aggregation actions for relations if configured.
+    for (const key of Object.keys({
+        ...relationModelProps,
+        ...fileModelProps
+    })) {
+        const relationField = relationConfig?.[key] || fileConfig?.[key];
+        if (relationField?.output?.count) {
+            inclusion._count = inclusion._count ?? { select: {} };
+            // Soft deleted related records are not counted
+            inclusion._count.select[key] =
+                (0, delete_util_1.liveInclusionFilter)(relationField.model) ?? true;
+        }
+        // Check if the relation should be included based on the output type
+        if (shouldIncludeRelation(relationField?.output?.type, action)) {
+            inclusion[key] = buildNestedInclusion(relationField, key, action);
+        }
+    }
+    return inclusion;
+}
+/**
+ * Maps the relation and file fields of a write payload to the Prisma nested write actions. Bare key values and arrays
+ * of them are normalized to objects first, then every item is classified: items with an id and additional data become
+ * inline updates when the parent action is an update and inline updates are enabled for the relation, items with only
+ * an id are connected, and items without an id are created inline or matched through a connect-or-create when
+ * `input.uniqueKey` is configured. On an update action, the items of the current record that are absent from the new
+ * value, as well as the relations set to null, are disconnected, or deleted when `orphanRemoval` is configured.
+ * Relations that were not loaded on the current record are left untouched.
+ *
+ * @param {string} resourceName - The name of the model the write payload belongs to.
+ * @param {'create'|'update'} action - The write action the relation actions are mapped for. Inline updates and the
+ * removal of the relations absent from the new value are only applied on an update action.
+ * @param {Object} data - The sanitized write payload whose relation and file fields are mapped. The non-relation
+ * fields are skipped, except for the null values of the array scalar fields, which are mapped to an empty array on an
+ * update action and to undefined on a create action.
+ * @param {Object} [currentData] - The currently stored record with its relations loaded, required on an update action
+ * to determine which relations to disconnect or delete.
+ * @return {RelationActions} The nested write clause per relation field, mapping each one to its `connect`, `create`,
+ * `update`, `connectOrCreate`, `disconnect` and `delete` actions, or to undefined for the relations no action can be
+ * applied to.
+ * @throws {ResourceError} `RESOURCE_INVALID_RELATION` if an inline payload holds fields the related model does not
+ * accept for its action, an inline create payload is missing required fields, a record with an id carries data the
+ * relation cannot update inline, or the relation accepts no new records and an id was not provided.
+ */
+function mapRelationActions(resourceName, action, data, currentData) {
+    const relations = {};
+    const resourceModel = (0, core_1.injectModel)(resourceName);
+    const readModel = resourceModel.readModel;
+    const relationsModel = resourceModel.relationsModel;
+    const relationsConfig = resourceModel.config.relations;
+    for (const key in data) {
+        let value = data[key];
+        const relationSchema = (0, common_1.extractSchemaProperties)(relationsModel, key);
+        if (!relationSchema) {
+            // Set empty array or undefined value for null array type fields
+            if (value === null) {
+                if ((0, common_1.extractSchemaProperties)(readModel, key)?.type === 'array') {
+                    relations[key] = action === 'update' ? [] : undefined;
+                }
+                else if (action === 'create') {
+                    relations[key] = undefined;
+                }
+            }
+            // Skip mapping for non-relation fields
+            continue;
+        }
+        const config = relationsConfig?.[key];
+        // The unique key is only used to match existing records for the
+        // connect-or-create action; connect and inline update always use the id
+        const uniqueKey = config?.input?.allowCreate
+            ? config?.input?.uniqueKey || 'id'
+            : 'id';
+        const isArrayType = relationSchema.type === 'array';
+        // Normalize array values to single values if a value type is not an array
+        if (!isArrayType && (0, common_1.isArray)(value)) {
+            value = value[0];
+        }
+        // Set null values to undefined value for create actions. On update action
+        // they will be returned as disconnected relations.
+        if (action === 'create' && value === null) {
+            relations[key] = undefined;
+            continue;
+        }
+        // Normalize plain key values or arrays to object values
+        if (isArrayType) {
+            if ((0, common_1.isArray)(value) && !(0, common_1.isPlainObject)(value[0])) {
+                value = value.map((v) => ({
+                    [uniqueKey]: v
+                }));
+            }
+        }
+        else if (!(0, common_1.isObject)(value)) {
+            // Only bare key values are wrapped. The loose object check keeps
+            // null values untouched, so they still map to a disconnect action.
+            value = { [uniqueKey]: value };
+        }
+        // Classify every relation input item into its relation write action:
+        // items with an id and additional data become inline updates (on parent
+        // update requests with inline updates enabled), items with only an id are
+        // connected, and items without an id are created inline or matched with
+        // connect-or-create, both of which require `allowCreate`
+        if (value) {
+            const items = isArrayType && (0, common_1.isArray)(value) ? value : [value];
+            const createdBy = createdByConnect(config?.model ?? resourceName);
+            const actions = {
+                connect: [],
+                update: [],
+                create: [],
+                connectOrCreate: []
+            };
+            for (const item of items) {
+                if (!(0, common_1.isPlainObject)(item)) {
+                    continue;
+                }
+                if (item.id !== undefined && item.id !== null) {
+                    const { id, ...updateData } = item;
+                    const fields = Object.keys(updateData);
+                    if (fields.length === 0) {
+                        actions.connect.push({ id });
+                        continue;
+                    }
+                    // The database updates relations only within an update action
+                    if (action !== 'update' || !config?.input?.allowUpdate) {
+                        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidRelation, `${resourceName} relation '${key}' does not accept inline updates, an existing record is connected by its id only`, { model: resourceName, relation: key, unknownFields: fields });
+                    }
+                    assertKnownFields(resourceName, key, unknownRelationFields(config?.model, 'update', updateData));
+                    actions.update.push({ where: { id }, data: updateData });
+                }
+                else if (!config?.input?.allowCreate) {
+                    // Without inline creation the related record must already exist,
+                    // so it is created through its own endpoint first
+                    throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidRelation, `${resourceName} relation '${key}' does not accept new records, an id is required`, { model: resourceName, relation: key });
+                }
+                else {
+                    // A null id marks no existing record, it is not part of the data
+                    const { id: _id, ...createData } = item;
+                    assertKnownFields(resourceName, key, unknownRelationFields(config?.model, 'create', createData));
+                    const missingFields = missingRelationFields(config?.model, createData);
+                    if (missingFields.length > 0) {
+                        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidRelation, `${resourceName} relation '${key}' is missing required fields: ${missingFields.join(', ')}`, { model: resourceName, relation: key, missingFields });
+                    }
+                    // A unique key matches an existing record before a new one is created
+                    if (config?.input?.uniqueKey) {
+                        actions.connectOrCreate.push({
+                            where: { [uniqueKey]: item[uniqueKey] },
+                            create: { ...createData, createdBy }
+                        });
+                    }
+                    else {
+                        actions.create.push({ ...createData, createdBy });
+                    }
+                }
+            }
+            const relationActions = {};
+            for (const [actionName, actionItems] of Object.entries(actions)) {
+                if (actionItems.length > 0) {
+                    relationActions[actionName] = isArrayType
+                        ? actionItems
+                        : actionItems[0];
+                }
+            }
+            // An empty list maps to no action, rather than leaving the raw list in
+            // the write data, where the database rejects it
+            relations[key] =
+                Object.keys(relationActions).length > 0 ? relationActions : undefined;
+        }
+        // Map relation disconnects if keys are no longer present or the new
+        // value is null. Delete relations if orphanRemoval is set to true.
+        // Relations that are not set on the current resource are left untouched,
+        // so no relation action is applied for them.
+        if (action === 'update') {
+            const currentValue = currentData[key];
+            const removalMethod = config?.orphanRemoval ? 'delete' : 'disconnect';
+            if (currentValue && isArrayType) {
+                const newValueKeys = value?.map((v) => v[uniqueKey]) ?? [];
+                const currentValueKeys = currentValue
+                    .filter((v) => newValueKeys.indexOf(v[uniqueKey]) === -1)
+                    .map((v) => ({
+                    [uniqueKey]: v[uniqueKey]
+                }));
+                if (currentValueKeys.length > 0) {
+                    relations[key] = {
+                        [removalMethod]: currentValueKeys,
+                        ...(relations[key] ?? {})
+                    };
+                }
+            }
+            else if (currentValue && value === null) {
+                relations[key] = {
+                    [removalMethod]: { [uniqueKey]: currentValue[uniqueKey] },
+                    ...(relations[key] ?? {})
+                };
+            }
+            else if (currentValue === undefined) {
+                // The relation was not loaded on the current record, so no relation
+                // action can be applied safely
+                relations[key] = undefined;
+            }
+        }
+    }
+    return relations;
+}
+/**
+ * Lists the fields of an inline relation payload the related model does not accept for the given action, so a payload
+ * written through a service call is rejected the same way the request validation rejects it.
+ *
+ * @param {string} [resourceName] - The name of the related model whose field restrictions are applied. When omitted,
+ * no fields are reported.
+ * @param {'create'|'update'} action - The write action the payload is checked for, selecting either the relation
+ * create or the relation update model of the related resource.
+ * @param {Object} data - The inline relation payload to check, without its `id` field.
+ * @return {string[]} The names of the payload fields the related model does not accept for the action, or an empty
+ * list if the related model declares no fields for it.
+ */
+function unknownRelationFields(resourceName, action, data) {
+    const resourceModel = resourceName
+        ? (0, core_1.injectModel)(resourceName, false)
+        : undefined;
+    const writeModel = action === 'create'
+        ? resourceModel?.relationCreateModel
+        : resourceModel?.relationUpdateModel;
+    const properties = (0, common_1.extractSchemaProperties)(writeModel);
+    if (!properties) {
+        return [];
+    }
+    return Object.keys(data).filter((name) => !(name in properties));
+}
+/**
+ * Lists the fields the related model requires on creation that the given inline relation payload does not provide.
+ *
+ * @param {string} [resourceName] - The name of the related model whose required fields are checked. When omitted, no
+ * fields are reported as missing.
+ * @param {Object} data - The inline relation payload to check.
+ * @return {string[]} The names of the fields the related model requires on creation that the payload leaves
+ * undefined, or an empty list if the related model declares no create schema.
+ */
+function missingRelationFields(resourceName, data) {
+    const resourceModel = resourceName
+        ? (0, core_1.injectModel)(resourceName, false)
+        : undefined;
+    const createModel = resourceModel?.relationCreateModel;
+    if (!createModel) {
+        return [];
+    }
+    const schema = createModel['$ref']
+        ? createModel['$defs']?.[createModel['$ref']]
+        : createModel;
+    return (schema?.required ?? []).filter((name) => data[name] === undefined);
+}
+/**
+ * Builds the connect action for the `createdBy` audit relation of a resource, pointing at the currently authenticated
+ * 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: 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) {
+    const resourceModel = (0, core_1.injectModel)(resourceName, false);
+    if (resourceModel?.config.audit?.createdById === false) {
+        return undefined;
+    }
+    const currentUser = (0, core_1.currentAuthUser)();
+    return currentUser
+        ? {
+            connect: {
+                id: currentUser.id
+            }
+        }
+        : undefined;
+}
+/**
+ * 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` 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.
+ * @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 its nested `include` clause, and
+ * for a list relation of a soft deleted model, the `where` clause skipping the deleted records.
+ */
+function buildNestedInclusion(relationField, key, action, depth = 1) {
+    const nestedIncludeConfig = relationField?.output?.include;
+    const nestedInclusion = {};
+    // A file field carries no related model, so it reads no further than itself
+    const relatedModel = relationField?.model
+        ? (0, core_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)) {
+            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);
+    }
+    // A list relation reads only the related records that are not soft deleted,
+    // while a single relation is cleared of them after it is read
+    const liveFilter = relatedModel && (0, common_1.isRelationArray)(relationField)
+        ? (0, delete_util_1.liveInclusionFilter)(relatedModel.name)
+        : undefined;
+    const hasNested = Object.keys(nestedInclusion).length > 0;
+    if (!hasNested && !liveFilter) {
+        return true;
+    }
+    return {
+        ...(liveFilter ?? {}),
+        ...(hasNested ? { include: nestedInclusion } : {})
+    };
+}
+/**
+ * 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
+ * the query action or when no action is specified.
+ *
+ * @param {OutputType} [outputType] - The configured output type of the relation. When omitted, the relation is
+ * included for every action.
+ * @param {ActionType} [action] - The action the relation would be included for. When omitted, every output type
+ * except `none` is included.
+ * @return {boolean} True if the relation should be included, false otherwise.
+ */
+function shouldIncludeRelation(outputType, action) {
+    if (outputType === 'none') {
+        return false;
+    }
+    if (outputType === 'single' && action === 'query') {
+        return false;
+    }
+    return !(outputType === 'multiple' && action && action !== 'query');
+}
+function assertKnownFields(resourceName, relation, unknownFields) {
+    if (unknownFields.length > 0) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidRelation, `${resourceName} relation '${relation}' does not accept the fields: ${unknownFields.join(', ')}`, { model: resourceName, relation, unknownFields });
+    }
+}

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

@@ -0,0 +1,31 @@
+import { ActionType, QuerySort } from '@appweaver/common';
+/**
+ * Maps a sort input to the ordered list of Prisma `orderBy` entries. The input is accepted either as a comma-separated
+ * field list, where a field prefixed with `-` is sorted in descending order, or as a (possibly nested) object of `asc`
+ * and `desc` field directions. Both forms support the same field paths: a scalar field of the
+ * model, a field of a to-one relation (`author.createdAt` or `{ author: { createdAt: 'desc' } }`), and the related
+ * record count of a to-many relation, given either as its count field (`tagsCount`) or as the relation itself
+ * (`tags`). The default `createdAt` sort is dropped when the model does not audit that field.
+ *
+ * @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, deciding which relations are included in the
+ * response and are therefore available to sort by. Defaults to the query action.
+ * @return {Object[]} One `orderBy` entry per field, in the order the fields were listed, each holding the single path
+ * of that field mapped to `asc` or `desc`. Two fields of the same relation get an entry each, since a database order
+ * entry accepts a single field path.
+ * @throws {ResourceError} `RESOURCE_INVALID_SORT` if a field does not exist on its model, cannot be sorted by, is given an unknown sort
+ * 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 {ResourceError} `RESOURCE_INVALID_SORT` under the same conditions as {@link mapSortValues}.
+ */
+export declare function mapStableSortValues(sort: QuerySort, resourceName: string, action?: ActionType): any[];

package/resource/utils/sort-util.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapSortValues = mapSortValues;
+exports.mapStableSortValues = mapStableSortValues;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+const relation_util_1 = require("./relation-util");
+/** The audit fields every model declares unless it opts out of them. */
+const defaultAuditFields = {
+    updatedAt: true,
+    createdAt: true,
+    createdById: true
+};
+/**
+ * Maps a sort input to the ordered list of Prisma `orderBy` entries. The input is accepted either as a comma-separated
+ * field list, where a field prefixed with `-` is sorted in descending order, or as a (possibly nested) object of `asc`
+ * and `desc` field directions. Both forms support the same field paths: a scalar field of the
+ * model, a field of a to-one relation (`author.createdAt` or `{ author: { createdAt: 'desc' } }`), and the related
+ * record count of a to-many relation, given either as its count field (`tagsCount`) or as the relation itself
+ * (`tags`). The default `createdAt` sort is dropped when the model does not audit that field.
+ *
+ * @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, deciding which relations are included in the
+ * response and are therefore available to sort by. Defaults to the query action.
+ * @return {Object[]} One `orderBy` entry per field, in the order the fields were listed, each holding the single path
+ * of that field mapped to `asc` or `desc`. Two fields of the same relation get an entry each, since a database order
+ * entry accepts a single field path.
+ * @throws {ResourceError} `RESOURCE_INVALID_SORT` if a field does not exist on its model, cannot be sorted by, is given an unknown sort
+ * direction, or targets a relation that the action does not include in its response.
+ */
+function mapSortValues(sort, resourceName, action = 'query') {
+    const inclusions = (0, relation_util_1.mapRelationInclusions)(resourceName, action);
+    const orderBy = [];
+    const mappedPaths = new Set();
+    for (const [path, direction] of sortEntries(sort)) {
+        const mappedPath = mapSortPath(resourceName, path, inclusions);
+        // Every field gets an entry of its own, since a database order entry holds
+        // a single field path, even when several of them share a relation. A field
+        // listed twice is already ordered by its first entry, so it is dropped
+        if (!mappedPath || mappedPaths.has(mappedPath)) {
+            continue;
+        }
+        mappedPaths.add(mappedPath);
+        orderBy.push((0, common_1.setValue)({}, mappedPath, direction));
+    }
+    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 {ResourceError} `RESOURCE_INVALID_SORT` 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
+ * walked recursively, joining the nested keys with a dot.
+ *
+ * @param {QuerySort} sort - The sort input to flatten.
+ * @param {string} [parentPath] - The dot notation path of the object the walk descended from.
+ * @return {SortEntry[]} The flattened sort entries, each holding a dot notation field path and its direction.
+ * @throws {ResourceError} `RESOURCE_INVALID_SORT` if a sort value is neither a direction nor a nested object of directions.
+ */
+function sortEntries(sort, parentPath = '') {
+    if ((0, common_1.isString)(sort)) {
+        return sort
+            .split(',')
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0 && part !== '-' && part !== '+')
+            .map((part) => [
+            part.replace(/^[-+]/, ''),
+            part.startsWith('-') ? 'desc' : 'asc'
+        ]);
+    }
+    if (!(0, common_1.isPlainObject)(sort)) {
+        throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Invalid sort value${parentPath ? ` for the '${parentPath}' field` : ''}, ` +
+            'expected a field list string or a sort object', { field: parentPath || undefined });
+    }
+    const entries = [];
+    for (const [field, value] of Object.entries(sort)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const path = parentPath ? `${parentPath}.${field}` : field;
+        if ((0, common_1.isPlainObject)(value)) {
+            entries.push(...sortEntries(value, path));
+            continue;
+        }
+        if (value !== 'asc' && value !== 'desc') {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Invalid sort direction '${value}' for the '${path}' field, expected 'asc' or 'desc'`, { field: path });
+        }
+        entries.push([path, value]);
+    }
+    return entries;
+}
+/**
+ * Resolves a single sort field path against the model it is applied on, validating every segment and rewriting the
+ * relation counts to their `_count` form. Relation segments are additionally checked against the relations the action
+ * includes in its response, since a relation that is not included cannot be sorted by.
+ *
+ * @param {string} resourceName - The name of the model the path starts at.
+ * @param {string} path - The dot notation field path to resolve.
+ * @param {Object} inclusions - The `include` clause of the action, as built by {@link mapRelationInclusions}.
+ * @return {string|undefined} The resolved dot notation path, or undefined when the field is the `createdAt` audit
+ * field of a model that does not audit it, in which case the sort entry is dropped.
+ * @throws {ResourceError} `RESOURCE_INVALID_SORT` if a segment does not exist on its model, cannot be sorted by, or targets a relation the
+ * action does not include in its response.
+ */
+function mapSortPath(resourceName, path, inclusions) {
+    const segments = path.split('.').filter((segment) => segment.length > 0);
+    const mappedSegments = [];
+    let modelName = resourceName;
+    let modelInclusions = inclusions;
+    for (const [index, field] of segments.entries()) {
+        const model = (0, core_1.injectModel)(modelName, false);
+        if (!model) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, the '${modelName}' model is not loaded`, { model: modelName, field: path });
+        }
+        const isLast = index === segments.length - 1;
+        const relation = relationField(model, field);
+        // A scalar field ends the path, so it is the only segment a relation of the
+        // same name cannot shadow
+        if (!relation && isScalarField(model, field)) {
+            if (!isLast) {
+                throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, '${field}' is not a relation of the ${model.name} model`, { model: model.name, field: path });
+            }
+            // The default sort still names the createdAt field on the models that do
+            // not audit it, so the entry is dropped instead of rejected
+            if (field === 'createdAt' && model.config.audit?.createdAt === false) {
+                return undefined;
+            }
+            mappedSegments.push(field);
+            break;
+        }
+        // A count field sorts by the number of related records, which the database
+        // orders by through the _count aggregation of the relation
+        if (!relation && isLast && (0, common_1.isCountField)(field)) {
+            const countedField = field.slice(0, -'Count'.length);
+            const countedRelation = relationField(model, countedField);
+            if (countedRelation && isFieldArray(countedRelation)) {
+                mappedSegments.push(countedField, '_count');
+                break;
+            }
+        }
+        if (!relation) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, '${field}' is not a sortable field of the ${model.name} model`, { model: model.name, field: path });
+        }
+        // A to-many relation holds no single value to sort by, so it is sorted by
+        // the number of its related records instead
+        if (isFieldArray(relation)) {
+            if (!isLast) {
+                throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, the '${field}' relation holds a list of records, ` +
+                    `sort by the '${(0, common_1.countFieldName)(field)}' field instead`, { model: model.name, field: path });
+            }
+            mappedSegments.push(field, '_count');
+            break;
+        }
+        if (isLast) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, the '${field}' relation requires a nested field to sort by`, { model: model.name, field: path });
+        }
+        const inclusion = modelInclusions?.[field];
+        if (!inclusion) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceInvalidSort, `Cannot sort by the '${path}' field, the '${field}' relation is not included in the response`, { model: model.name, field: path });
+        }
+        mappedSegments.push(field);
+        modelName = (0, common_1.capitalize)(relatedModelName(model, field));
+        modelInclusions = (0, common_1.isPlainObject)(inclusion) ? inclusion.include : undefined;
+    }
+    return mappedSegments.join('.');
+}
+/**
+ * Reads the relation or file field configuration of a model field.
+ *
+ * @param {ResourceModel} model - The model the field belongs to.
+ * @param {string} field - The name of the field to read.
+ * @return {RelationField|FileField|undefined} The relation or file configuration of the field, or undefined when the
+ * field is not a relation.
+ */
+function relationField(model, field) {
+    return model.config.relations?.[field] ?? model.config.files?.[field];
+}
+/**
+ * Resolves the model name a relation or file field of a model points at.
+ *
+ * @param {ResourceModel} model - The model the relation belongs to.
+ * @param {string} field - The name of the relation field.
+ * @return {string} The name of the related model, which is always `File` for a file field.
+ */
+function relatedModelName(model, field) {
+    return model.config.relations?.[field]?.model ?? 'File';
+}
+/**
+ * Determines whether a relation or file field holds a list of related records, which can only be sorted by their
+ * count.
+ *
+ * @param {RelationField|FileField} field - The relation or file field configuration.
+ * @return {boolean} True when the field holds a list of related records.
+ */
+function isFieldArray(field) {
+    return 'model' in field ? (0, common_1.isRelationArray)(field) : field.array === true;
+}
+/**
+ * Determines whether a model field is a scalar column the database can sort by. The id and the audited fields are
+ * always sortable, the configured scalars are sortable unless they are hidden or hold a list of values, and the
+ * virtual fields are never sortable, since they have no column of their own.
+ *
+ * @param {ResourceModel} model - The model the field belongs to.
+ * @param {string} field - The name of the field to check.
+ * @return {boolean} True when the field can be sorted by.
+ */
+function isScalarField(model, field) {
+    if (field === 'id') {
+        return true;
+    }
+    const auditFields = { ...defaultAuditFields, ...(model.config.audit ?? {}) };
+    if (field in auditFields) {
+        // The createdAt field of a model that does not audit it is still accepted,
+        // so the default sort value does not have to be adjusted per model
+        return auditFields[field] === true || field === 'createdAt';
+    }
+    const scalar = model.config.scalars?.[field];
+    return !!scalar && !scalar.hidden && scalar.array !== true;
+}