@appweaver/core 1.1.5 → 1.2.0

package/resource/utils/filter-util.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapQueryFilter = mapQueryFilter;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../../context");
+/**
+ * Logical filter operators mapped to their database query connectives. Both
+ * `_not` and `_nor` negate the conjunction of their conditions.
+ */
+const logicalOperators = {
+    _and: 'AND',
+    _or: 'OR',
+    _not: 'NOT',
+    _nor: 'NOT'
+};
+/** List relation filter operators mapped to their database quantifiers. */
+const relationOperators = {
+    _some: 'some',
+    _every: 'every',
+    _none: 'none'
+};
+/** Reads a boolean operator value, accepting the `'false'` string as false. */
+const isTruthy = (value) => !(value === false || value === 'false');
+/** Wraps a single operator value into a list. */
+const asArray = (value) => ((0, common_1.isArray)(value) ? value : [value]);
+/**
+ * Maps an SQL LIKE pattern to the matching string condition, based on the
+ * placement of its `%` wildcards. A pattern without wildcards matches exactly.
+ */
+const likePattern = (pattern) => {
+    const value = String(pattern);
+    const startsWildcard = value.startsWith('%');
+    const endsWildcard = value.endsWith('%') && value.length > 1;
+    const inner = value.slice(startsWildcard ? 1 : 0, endsWildcard ? -1 : undefined);
+    if (startsWildcard && endsWildcard) {
+        return { contains: inner };
+    }
+    if (endsWildcard) {
+        return { startsWith: inner };
+    }
+    if (startsWildcard) {
+        return { endsWith: inner };
+    }
+    return { equals: value };
+};
+/**
+ * Field comparison operators mapped to their database query conditions.
+ * Operators combined in the same object are merged into a single condition.
+ */
+const fieldOperators = {
+    _eq: (value) => ({ equals: value }),
+    _ne: (value) => ({ not: value }),
+    _gt: (value) => ({ gt: value }),
+    _gte: (value) => ({ gte: value }),
+    _lt: (value) => ({ lt: value }),
+    _lte: (value) => ({ lte: value }),
+    _in: (value) => ({ in: asArray(value) }),
+    _nin: (value) => ({ notIn: asArray(value) }),
+    _between: (value) => ({ gte: value?.[0], lte: value?.[1] }),
+    _like: (value) => likePattern(value),
+    _ilike: (value) => ({ ...likePattern(value), mode: 'insensitive' }),
+    _starts: (value) => ({ startsWith: value }),
+    _ends: (value) => ({ endsWith: value }),
+    _contains: (value) => ({ contains: value }),
+    _exists: (value) => (isTruthy(value) ? { not: null } : { equals: null }),
+    _has: (value) => ({ has: value }),
+    _hasSome: (value) => ({ hasSome: asArray(value) }),
+    _hasEvery: (value) => ({ hasEvery: asArray(value) }),
+    _isEmpty: (value) => ({ isEmpty: isTruthy(value) })
+};
+/**
+ * Maps a request filter to a Prisma `where` clause based on the schema of the
+ * given resource model. The logical operators (`_and`, `_or`, `_not`, `_nor`)
+ * combine their nested conditions with the matching connective, the field
+ * operator objects (`_eq`, `_gt`, `_like`, `_exists`, ...) are translated to
+ * their database conditions, and the list relation quantifiers (`_some`,
+ * `_every`, `_none`) filter the related records. Plain values keep their
+ * shorthand meaning: relation and file fields are matched by id (wrapped in a
+ * `some` condition for the array relations), array fields use the `has` and
+ * `hasSome` operators, an array value on a numeric or date field becomes an
+ * inclusive `gte`/`lte` range, other array values become an `in` inclusion,
+ * nested objects are mapped recursively against the related model, and null
+ * values are passed through to match records without a value or a related
+ * record. Values that match no known field are passed through with only their
+ * operators translated, so the Prisma operators can still be used directly.
+ *
+ * @param {Object} filter The request filter object to map.
+ * @param {string} resourceName The name of the model the filter is matched
+ * against. It is set to the related model name when recursing into a nested
+ * relation or file filter.
+ * @returns {Object} The `where` clause with every recognized field mapped to its
+ * database condition and the unrecognized values passed through unchanged.
+ */
+function mapQueryFilter(filter, resourceName) {
+    const queryFilter = {};
+    const resourceModel = (0, context_1.injectModel)(resourceName, false);
+    const readModel = resourceModel?.readModel;
+    const relationsModel = resourceModel?.relationsModel;
+    const filesModel = resourceModel?.filesModel;
+    for (const key in filter) {
+        const value = filter[key];
+        // Logical operators combine their conditions, given either as a filter
+        // object whose entries become separate conditions or as a list of
+        // filters, with the matching database connective
+        if (logicalOperators[key]) {
+            const operator = logicalOperators[key];
+            const conditions = mapFilterConditions(value, (item) => mapQueryFilter(item, resourceName));
+            queryFilter[operator] = [...(queryFilter[operator] ?? []), ...conditions];
+            continue;
+        }
+        // List relation quantifiers filter the related records of the model the
+        // current filter level is matched against
+        if (relationOperators[key] && (0, common_1.isPlainObject)(value)) {
+            queryFilter[relationOperators[key]] = mapQueryFilter(value, resourceName);
+            continue;
+        }
+        const readSchema = (0, common_1.extractSchemaProperties)(readModel, key);
+        const relationSchema = (0, common_1.extractSchemaProperties)(relationsModel, key);
+        const fileSchema = (0, common_1.extractSchemaProperties)(filesModel, key);
+        const isArrayType = readSchema?.type === 'array' ||
+            relationSchema?.type === 'array' ||
+            fileSchema?.type === 'array';
+        const isArrayValue = (0, common_1.isArray)(value);
+        // Null values are passed through untouched, matching records without a
+        // value or, for relations, without a related record.
+        if (value === null) {
+            queryFilter[key] = null;
+            continue;
+        }
+        // Recursively map nested objects and handle arrays of objects. Arrays of
+        // plain values are mapped below as inclusion, range or relation filters.
+        if ((0, common_1.isPlainObject)(value) || (isArrayValue && (0, common_1.isPlainObject)(value[0]))) {
+            const relatedName = (0, common_1.extractResourceName)(relationSchema ?? fileSchema);
+            if (relatedName) {
+                queryFilter[key] = isArrayValue
+                    ? value.map((item) => mapQueryFilter(item, relatedName))
+                    : mapRelationFilter(value, relatedName, isArrayType);
+            }
+            else {
+                // Objects that match no relation have their field operators
+                // translated and everything else passed through unchanged
+                queryFilter[key] = mapFieldFilter(value);
+            }
+        }
+        // Map ID values for both single and array types of relationships
+        else if (relationSchema || fileSchema) {
+            const queryId = { id: isArrayValue ? { in: value } : value };
+            queryFilter[key] = isArrayType ? { some: queryId } : queryId;
+        }
+        // Map fields without relationships, supporting array types
+        else if (readSchema) {
+            if (isArrayType) {
+                queryFilter[key] = isArrayValue ? { hasSome: value } : { has: value };
+            }
+            else if (isArrayValue) {
+                // For date and numeric types, apply range filtering with inclusive
+                // intervals
+                if (value.length > 0 &&
+                    value.length <= 2 &&
+                    (['number', 'integer'].includes(readSchema.type) ||
+                        ['date', 'date-time'].includes(readSchema.format))) {
+                    queryFilter[key] = {
+                        gte: value[0],
+                        lte: value[1]
+                    };
+                }
+                // Map array values for inclusion checks
+                else {
+                    queryFilter[key] = { in: value };
+                }
+            }
+        }
+        // If no query filter was defined, assign the original value
+        if (queryFilter[key] === undefined) {
+            queryFilter[key] = value;
+        }
+    }
+    return queryFilter;
+}
+/**
+ * Normalizes the value of a logical filter operator to the list of its
+ * mapped conditions. A list of filters maps every item separately, while a
+ * single filter object maps every entry into its own condition, so the
+ * logical connective is applied per field.
+ *
+ * @param {Object|Object[]} value The logical operator value to normalize.
+ * @param {Function} map The function mapping a single filter condition.
+ * @returns {Object[]} The list of mapped filter conditions.
+ */
+function mapFilterConditions(value, map) {
+    if ((0, common_1.isArray)(value)) {
+        return value.map(map);
+    }
+    if ((0, common_1.isPlainObject)(value)) {
+        return Object.entries(value).map(([key, item]) => map({ [key]: item }));
+    }
+    return [value];
+}
+/**
+ * Maps the filter of a relation or file field to its database condition
+ * against the related model. The `_exists` operator is resolved based on the
+ * relation cardinality: a list relation wraps the remaining conditions in a
+ * `some` (or `none`) quantifier, while a single relation maps to an `is` or
+ * `isNot` null check, wrapping the remaining conditions in an `is` filter.
+ *
+ * @param {Object} filter The relation filter object to map.
+ * @param {string} resourceName The name of the related model the filter is
+ * matched against.
+ * @param {boolean} isArrayType Whether the relation is a list (to-many)
+ * relation.
+ * @returns {Object} The database condition of the relation field.
+ */
+function mapRelationFilter(filter, resourceName, isArrayType) {
+    const { _exists, ...conditions } = filter;
+    const mapped = mapQueryFilter(conditions, resourceName);
+    if (_exists === undefined) {
+        return mapped;
+    }
+    const exists = isTruthy(_exists);
+    const hasConditions = Object.keys(conditions).length > 0;
+    if (isArrayType) {
+        return exists ? { some: mapped } : { none: mapped };
+    }
+    if (!exists) {
+        return { is: null };
+    }
+    return hasConditions ? { is: mapped } : { isNot: null };
+}
+/**
+ * Maps a field condition object to its database condition by translating the
+ * filter operators anywhere in its structure. The field operators of one
+ * object are merged into a single condition, a `_not` holding an operator
+ * object or a plain value negates it, the logical operators combine their
+ * nested conditions, and everything else is passed through unchanged, so
+ * native database conditions keep working.
+ *
+ * @param {*} value The field condition value to map.
+ * @returns {*} The database condition with every filter operator translated.
+ */
+function mapFieldFilter(value) {
+    if ((0, common_1.isArray)(value)) {
+        return value.map((item) => mapFieldFilter(item));
+    }
+    if (!(0, common_1.isPlainObject)(value)) {
+        return value;
+    }
+    const condition = {};
+    for (const [key, item] of Object.entries(value)) {
+        // A `_not` negates its operator object or plain value directly, while an
+        // object of field conditions is combined as a logical NOT below
+        if (key === '_not' && (!(0, common_1.isPlainObject)(item) || hasFieldOperators(item))) {
+            condition['not'] = mapFieldFilter(item);
+            continue;
+        }
+        if (logicalOperators[key]) {
+            const operator = logicalOperators[key];
+            const conditions = mapFilterConditions(item, (entry) => mapFieldFilter(entry));
+            condition[operator] = [...(condition[operator] ?? []), ...conditions];
+            continue;
+        }
+        if (relationOperators[key]) {
+            condition[relationOperators[key]] = mapFieldFilter(item);
+            continue;
+        }
+        if (fieldOperators[key]) {
+            Object.assign(condition, fieldOperators[key](item));
+            continue;
+        }
+        condition[key] = mapFieldFilter(item);
+    }
+    return condition;
+}
+/**
+ * Checks whether the given value is an object holding at least one field
+ * comparison operator (i.e. `_eq`, `_gt`, `_like`, ...).
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean} True if the value contains a field operator.
+ */
+function hasFieldOperators(value) {
+    return ((0, common_1.isPlainObject)(value) &&
+        Object.keys(value).some((key) => fieldOperators[key] || key === '_not'));
+}

package/resource/utils/index.d.ts

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

package/resource/utils/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./aggregate-util"), exports);
+__exportStar(require("./filter-util"), exports);
+__exportStar(require("./relation-util"), exports);
+__exportStar(require("./sort-util"), exports);

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

@@ -0,0 +1,84 @@
+import { ActionType } from '@appweaver/common';
+/** The nested write actions a single relation field can be mapped to. */
+export type RelationActions = Record<string, Partial<{
+    connect: any;
+    create: any;
+    update: any;
+    connectOrCreate: any;
+    disconnect: any;
+    delete: any;
+}>>;
+/**
+ * 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.
+ */
+export declare function mapRelationInclusions(resourceName: string, action?: ActionType): Record<string, any>;
+/**
+ * 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 {HttpError} 400 if an inline create payload is missing required fields, or if the relation accepts no new
+ * records and an id was not provided.
+ */
+export declare function mapRelationActions(resourceName: string, action: 'create' | 'update', data: any, currentData?: any): RelationActions;
+/**
+ * Restricts an inline relation payload to the fields the related model accepts for the given action. The request
+ * schema accepts the create and the update fields together, since the properties it does not declare are stripped
+ * before the request reaches the service, so the configured field restrictions of the related model are applied here
+ * instead.
+ *
+ * @param {string} [resourceName] - The name of the related model whose field restrictions are applied. When omitted,
+ * the payload is returned unchanged.
+ * @param {'create'|'update'} action - The write action the payload is restricted for, selecting either the relation
+ * create or the relation update model of the related resource.
+ * @param {Object} data - The inline relation payload to restrict.
+ * @return {Object} The payload reduced to the fields the related model accepts for the action, excluding the `id`
+ * field, or the payload unchanged if the related model declares no fields for it.
+ */
+export declare function relationWriteData(resourceName: string | undefined, action: 'create' | 'update', data: any): any;
+/**
+ * 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.
+ */
+export declare function missingRelationFields(resourceName: string | undefined, data: any): string[];
+/**
+ * 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: number}}|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;
+    };
+} | undefined;