@appweaver/data 0.0.0-stage → 2.0.0

package/utils/file-util.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFileUrl = buildFileUrl;
+exports.deletedResourceFileFields = deletedResourceFileFields;
+exports.parseRange = parseRange;
+exports.maxFileSize = maxFileSize;
+exports.sizeInBytes = sizeInBytes;
+exports.isValidMimeType = isValidMimeType;
+exports.generateFileName = generateFileName;
+exports.validateFileNamePatterns = validateFileNamePatterns;
+exports.sanitizeFilename = sanitizeFilename;
+exports.sanitizeFileSegment = sanitizeFileSegment;
+exports.aggregateFiles = aggregateFiles;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+/**
+ * Builds the access URL for a stored file. The `public` or `protected` path prefix is resolved from the access type
+ * configured in the file policy of the resource owning the file, and the route prefix is taken from the
+ * `STORAGE_FILES_ROUTE_PREFIX` configuration.
+ *
+ * @param {File} file - The file object containing the name and owning resource information.
+ * @return {string} The absolute URL for accessing the file.
+ */
+function buildFileUrl(file) {
+    const accessType = (0, core_1.injectPolicy)(file.resourceName ?? '', false)?.files?.[file.resourceField ?? '']?.accessType;
+    const pathPrefix = accessType === 'public' ? 'public' : 'protected';
+    const routePrefix = `/${core_1.storageConfig.FILES_ROUTE_PREFIX}/`.replace(/\/+/g, '/');
+    return `${common_1.appConfig.HOSTNAME}${routePrefix}${pathPrefix}/${file.name}`;
+}
+/**
+ * Splits the file fields of a deleted resource by what happens to their files. On a delete removing the resource from
+ * the database each field follows its `onResourceDeleted` option, which defaults to `'delete'`, while on a soft delete
+ * it follows its `onResourceSoftDeleted` option, which defaults to `'keep'`.
+ *
+ * @param {FilesConfig} [files] - The file fields of the deleted resource's model.
+ * @param {boolean} softDeleted - Whether the resource was soft deleted.
+ * @return {{deleted: string[], kept: string[]}} The fields whose files are removed from storage, and the fields whose
+ * files are retained, but no longer served.
+ */
+function deletedResourceFileFields(files = {}, softDeleted) {
+    const fields = { deleted: [], kept: [] };
+    for (const [field, fileField] of Object.entries(files)) {
+        const action = softDeleted
+            ? (fileField.onResourceSoftDeleted ?? 'keep')
+            : (fileField.onResourceDeleted ?? 'delete');
+        fields[action === 'delete' ? 'deleted' : 'kept'].push(field);
+    }
+    return fields;
+}
+/**
+ * Parses a range string and converts it into an object with start and end values.
+ *
+ * @param {string} [range] - The range string to parse, typically in the format "bytes=start-end".
+ * @return {{start: number, end?: number}} An object containing the start value and an optional end value.
+ */
+function parseRange(range) {
+    if (!range) {
+        return { start: 0 };
+    }
+    const parts = range.replace(/bytes=/, '').split('-');
+    const start = parseInt(parts[0], 10);
+    const end = parts[1] ? parseInt(parts[1], 10) : undefined;
+    return { start, end };
+}
+/**
+ * Calculates the maximum file size allowed based on the provided file configuration.
+ *
+ * @param {FilesConfig} fileConfig - An object containing file configuration data, including maximum size for each file
+ * type.
+ * @return {number} The maximum size in bytes allowed for any file based on the given configuration.
+ */
+function maxFileSize(fileConfig) {
+    const sizes = Object.values(fileConfig)
+        .map((conf) => sizeInBytes(conf.maxSize))
+        .filter((v) => v > 0);
+    if (!sizes.length) {
+        return (0, common_1.textToBytes)(common_1.config.str('SERVER_BODY_MAX_SIZE', '100M'));
+    }
+    return Math.max(...sizes);
+}
+/**
+ * Converts a given size represented as a string or number into its equivalent size in bytes.
+ *
+ * @param {string | number} [size] - The size to be converted, either as a string or a number.
+ * @return {number} The size in bytes. Returns 0 if the input is invalid or not provided.
+ */
+function sizeInBytes(size) {
+    return (0, common_1.isString)(size) ? (0, common_1.textToBytes)(size) : 0;
+}
+/**
+ * Validates if the provided MIME type matches a given pattern or regular expression.
+ *
+ * @param {string} mimeType - The MIME type to validate.
+ * @param {string|RegExp} [mimeTypeExp] - An optional pattern or regular expression to match the MIME type against.
+ *                                       If not provided, the method will always return true.
+ * @return {boolean} True if the MIME type matches the specified pattern or regular expression, false otherwise.
+ */
+function isValidMimeType(mimeType, mimeTypeExp) {
+    if (!mimeTypeExp) {
+        return true;
+    }
+    else if (mimeTypeExp instanceof RegExp) {
+        return mimeTypeExp.test(mimeType);
+    }
+    else {
+        const regexPattern = mimeTypeExp
+            .replace(/[.+?^$]/g, '\\$&')
+            .replace(/\*/g, '.*');
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(mimeType);
+    }
+}
+/**
+ * Generates a file name based on a given name, an optional pattern, and a set of variables.
+ *
+ * @param {string} name The original file name including its extension.
+ * @param {string} [pattern] An optional pattern to customize the generated file name. If not provided, a default
+ * pattern will be used.
+ * @param {Record<string, any>} [variables={}] Additional variables to replace in the pattern. These can include custom
+ * placeholders to dynamically generate the file name.
+ * @return {string} The generated, sanitized file name based on the provided or default pattern.
+ */
+function generateFileName(name, pattern, variables = {}) {
+    const nameParts = name.split('.');
+    let extension = '';
+    let nameWithoutExtension = name;
+    if (nameParts.length > 1) {
+        extension = nameParts.pop();
+        nameWithoutExtension = nameParts.join('.');
+    }
+    const defaultPattern = core_1.storageConfig.NAME_PATTERN ?? '{name}-{hash}.{extension}';
+    // Only the pattern itself is trusted to contain directory separators, every substituted value is reduced to a
+    // single path segment so that an uploaded file name cannot introduce a sub-path or a traversal.
+    let fileName = (0, common_1.replacePatternVariables)(pattern ?? defaultPattern, {
+        ...sanitizeVariables(variables),
+        name: sanitizeFileSegment(nameWithoutExtension),
+        extension: sanitizeFileSegment(extension)
+    });
+    fileName = sanitizeFilename(fileName);
+    fileName = fileName.endsWith('.')
+        ? fileName.substring(0, fileName.length - 1)
+        : fileName;
+    return ((0, common_1.normalizeStoragePath)(fileName) ||
+        sanitizeFileSegment(name) ||
+        (0, common_1.generateToken)('bytes', 32));
+}
+/**
+ * Validates that no configured file name pattern writes into a path reserved by `STORAGE_RESERVED_PATHS`. Both the
+ * global `STORAGE_NAME_PATTERN` and the `namePattern` of every file field of the provided models are checked. Patterns
+ * defined as a factory function cannot be resolved before an upload, so they are validated at runtime instead.
+ *
+ * @param {Record<string, ResourceModel>} models - The loaded resource models, keyed by model name.
+ * @throws {Error} Throws an error naming the model, the field, and the reserved path when a pattern is reserved.
+ */
+function validateFileNamePatterns(models) {
+    const reservedPaths = core_1.storageConfig.RESERVED_PATHS;
+    const globalReservedPath = (0, common_1.findReservedStoragePath)(core_1.storageConfig.NAME_PATTERN, reservedPaths);
+    if (globalReservedPath !== null) {
+        throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Configured STORAGE_NAME_PATTERN '${core_1.storageConfig.NAME_PATTERN}' is placed under the reserved ` +
+            `storage path '${globalReservedPath}'`);
+    }
+    for (const model of Object.values(models)) {
+        for (const [field, fileConfig] of Object.entries(model.config.files ?? {})) {
+            if (!(0, common_1.isString)(fileConfig.namePattern)) {
+                continue;
+            }
+            const reservedPath = (0, common_1.findReservedStoragePath)(fileConfig.namePattern, reservedPaths);
+            if (reservedPath !== null) {
+                throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `File name pattern '${fileConfig.namePattern}' of the '${model.name}.${field}' field is placed ` +
+                    `under the reserved storage path '${reservedPath}'`);
+            }
+        }
+    }
+}
+/**
+ * Sanitizes a given filename by removing invalid characters that are not allowed in file systems. Path separators are
+ * preserved, since a file name may be a path relative to the storage root.
+ *
+ * @param fileName The original filename to sanitize.
+ * @return A sanitized filename with invalid characters removed.
+ */
+function sanitizeFilename(fileName) {
+    const invalidFilenameChars = new Set([
+        '\\',
+        ':',
+        '*',
+        '?',
+        '"',
+        '<',
+        '>',
+        '|'
+    ]);
+    return [...fileName]
+        .filter((char) => {
+        const code = char.charCodeAt(0);
+        // Strip control characters (including NUL) and characters invalid in file names.
+        return code > 31 && code !== 127 && !invalidFilenameChars.has(char);
+    })
+        .join('');
+}
+/**
+ * Sanitizes an untrusted value into a single file path segment. In addition to the characters removed by
+ * {@link sanitizeFilename}, all path separators are stripped and leading dots are removed, so that the value can never
+ * introduce a subdirectory, a `..` traversal or a hidden file.
+ *
+ * @param value The untrusted value to sanitize.
+ * @return A sanitized single path segment, or an empty string when nothing usable remains.
+ */
+function sanitizeFileSegment(value) {
+    if (!(0, common_1.isString)(value)) {
+        return '';
+    }
+    // Trimming must precede the leading dot removal, otherwise a padded value such as '  ..  ' keeps its dots.
+    return sanitizeFilename(value)
+        .replace(/[/\\]+/g, '')
+        .trim()
+        .replace(/^\.+/, '')
+        .trim();
+}
+function sanitizeVariables(variables) {
+    return Object.fromEntries(Object.entries(variables).map(([key, value]) => [
+        key,
+        (0, common_1.isString)(value) ? sanitizeFileSegment(value) : value
+    ]));
+}
+/**
+ * Aggregates the provided files into a structured object based on the given configuration.
+ *
+ * @param {File[]} files - An array of file objects to be processed and aggregated.
+ * @param {FilesConfig} filesConfig - An object that defines the configuration for each file field, including whether
+ * the field supports multiple files.
+ * @return {Record<string, File | File[] | null>} A record where keys correspond to the configured fields, and values
+ * are either a single file, an array of files, or null if no files match the field.
+ */
+function aggregateFiles(files, filesConfig) {
+    const aggregated = Object.entries(filesConfig)
+        .map(([field, value]) => ({ [field]: value.array ? [] : null }))
+        .reduce((acc, obj) => Object.assign(acc, obj), {});
+    for (const file of files) {
+        const resourceField = file.resourceField;
+        if (resourceField) {
+            if (filesConfig[resourceField].array) {
+                if (!aggregated[resourceField]) {
+                    aggregated[resourceField] = [];
+                }
+                aggregated[resourceField].push(file);
+            }
+            else {
+                aggregated[resourceField] = file;
+            }
+        }
+    }
+    return aggregated;
+}

package/utils/model-util.d.ts

@@ -0,0 +1,36 @@
+import { ResourceModel } from '@appweaver/common';
+/**
+ * Checks whether the model with the given name soft deletes its records.
+ *
+ * @param {string} [resourceName] - The name of the model to check.
+ * @return {boolean} True if the model is loaded and has `softDelete` enabled.
+ */
+export declare function isSoftDeleteModel(resourceName?: string): boolean;
+/**
+ * Builds the condition matching only the records of a model that are not soft
+ * deleted, for the queries reading its records outside the resource service.
+ *
+ * @param {string} resourceName - The name of the model the condition is built for.
+ * @return {Object} The `deletedAt: null` condition for a soft deleted model, or
+ * an empty object otherwise.
+ */
+export declare function liveRecordFilter(resourceName: string): Record<string, any>;
+/**
+ * Validates that every relation cascading on delete from a model with
+ * `softDelete` enabled belongs to a model that soft deletes its records too.
+ *
+ * @param {Record<string, ResourceModel>} models - All loaded models keyed by name.
+ * @throws {Error} When a soft deleted model cascades into a model without soft delete.
+ */
+export declare function validateSoftDeleteCascades(models: Record<string, ResourceModel>): void;
+/**
+ * Validates that the default value of every scalar and virtual field satisfies
+ * the constraints declared on that same field. A default outside its own
+ * constraints produces records that do not match the output schema of their
+ * model, which only surfaces once the model is nested in a nullable relation,
+ * where the response serializer validates it before picking a schema branch.
+ *
+ * @param {Record<string, ResourceModel>} models - All loaded models keyed by name.
+ * @throws {Error} When any default value violates the constraints of its field.
+ */
+export declare function validateScalarDefaults(models: Record<string, ResourceModel>): void;

package/utils/model-util.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSoftDeleteModel = isSoftDeleteModel;
+exports.liveRecordFilter = liveRecordFilter;
+exports.validateSoftDeleteCascades = validateSoftDeleteCascades;
+exports.validateScalarDefaults = validateScalarDefaults;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+/**
+ * Checks whether the model with the given name soft deletes its records.
+ *
+ * @param {string} [resourceName] - The name of the model to check.
+ * @return {boolean} True if the model is loaded and has `softDelete` enabled.
+ */
+function isSoftDeleteModel(resourceName) {
+    if (!resourceName) {
+        return false;
+    }
+    const model = (0, core_1.injectModel)((0, common_1.capitalize)(resourceName), false);
+    return (0, common_1.hasSoftDelete)(model?.config);
+}
+/**
+ * Builds the condition matching only the records of a model that are not soft
+ * deleted, for the queries reading its records outside the resource service.
+ *
+ * @param {string} resourceName - The name of the model the condition is built for.
+ * @return {Object} The `deletedAt: null` condition for a soft deleted model, or
+ * an empty object otherwise.
+ */
+function liveRecordFilter(resourceName) {
+    return isSoftDeleteModel(resourceName) ? { deletedAt: null } : {};
+}
+/**
+ * Validates that every relation cascading on delete from a model with
+ * `softDelete` enabled belongs to a model that soft deletes its records too.
+ *
+ * @param {Record<string, ResourceModel>} models - All loaded models keyed by name.
+ * @throws {Error} When a soft deleted model cascades into a model without soft delete.
+ */
+function validateSoftDeleteCascades(models) {
+    const errors = (0, common_1.softDeleteCascadeErrors)(models);
+    if (errors.length > 0) {
+        throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Invalid resource model soft delete cascades:\n${errors
+            .map((error) => `  - ${error}`)
+            .join('\n')}`, { errors });
+    }
+}
+/**
+ * Validates that the default value of every scalar and virtual field satisfies
+ * the constraints declared on that same field. A default outside its own
+ * constraints produces records that do not match the output schema of their
+ * model, which only surfaces once the model is nested in a nullable relation,
+ * where the response serializer validates it before picking a schema branch.
+ *
+ * @param {Record<string, ResourceModel>} models - All loaded models keyed by name.
+ * @throws {Error} When any default value violates the constraints of its field.
+ */
+function validateScalarDefaults(models) {
+    const errors = [];
+    for (const model of Object.values(models)) {
+        const fields = {
+            ...(model.config.scalars ?? {}),
+            ...(model.config.virtual ?? {})
+        };
+        for (const [name, field] of Object.entries(fields)) {
+            for (const error of defaultValueErrors(field)) {
+                errors.push(`'${model.name}.${name}' ${error}`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Invalid resource model default values:\n${errors
+            .map((error) => `  - ${error}`)
+            .join('\n')}`, { errors });
+    }
+}
+function defaultValueErrors(field) {
+    if (field.default === undefined) {
+        return [];
+    }
+    // An array field defaults to a list of values, each validated on its own
+    const values = field.array
+        ? (0, common_1.isArray)(field.default)
+            ? field.default
+            : [field.default]
+        : [field.default];
+    return values.flatMap((value) => defaultErrors(field, value));
+}
+function defaultErrors(field, value) {
+    const errors = [];
+    const invalidType = (expected) => `has a default value of ${JSON.stringify(value)}, which is not ${expected}`;
+    const violates = (constraint, limit) => `has a default value of ${JSON.stringify(value)}, which violates its ` +
+        `own ${constraint} of ${JSON.stringify(limit)}`;
+    switch (field.type) {
+        case 'string':
+            if (!(0, common_1.isString)(value)) {
+                return [invalidType('a string')];
+            }
+            if (field.minLength !== undefined && value.length < field.minLength) {
+                errors.push(violates('minLength', field.minLength));
+            }
+            if (field.maxLength !== undefined && value.length > field.maxLength) {
+                errors.push(violates('maxLength', field.maxLength));
+            }
+            if (field.pattern !== undefined &&
+                !matchesPattern(value, field.pattern)) {
+                errors.push(violates('pattern', field.pattern));
+            }
+            break;
+        case 'int':
+        case 'bigInt':
+        case 'float':
+            if (!(0, common_1.isNumber)(value)) {
+                return [invalidType('a number')];
+            }
+            if (field.type !== 'float' && !Number.isInteger(value)) {
+                return [invalidType('an integer')];
+            }
+            if (field.minimum !== undefined && value < field.minimum) {
+                errors.push(violates('minimum', field.minimum));
+            }
+            if (field.maximum !== undefined && value > field.maximum) {
+                errors.push(violates('maximum', field.maximum));
+            }
+            break;
+        case 'boolean':
+            if (!(0, common_1.isBoolean)(value)) {
+                errors.push(invalidType('a boolean'));
+            }
+            break;
+        case 'dateTime':
+            if (!(value instanceof Date) &&
+                (!(0, common_1.isString)(value) || Number.isNaN(Date.parse(value)))) {
+                errors.push(invalidType('a valid date'));
+            }
+            break;
+        case 'enum':
+            if (!(field.values ?? []).includes(value)) {
+                errors.push(violates('allowed values', field.values ?? []));
+            }
+            break;
+    }
+    return errors;
+}
+/** Tests a value against a field pattern, skipping patterns that are not valid
+ * regular expressions since they cannot be evaluated. */
+function matchesPattern(value, pattern) {
+    try {
+        return new RegExp(pattern).test(value);
+    }
+    catch {
+        return true;
+    }
+}

package/utils/policy-util.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runs the given function with internal access, where the resource and file services skip the policies: the access
+ * checks, the read and write restrictions, and the file access checks. Everything else, like the service hooks,
+ * validation, events, and cache invalidation, still runs. Meant for the framework's own flows and trusted application
+ * code, such as jobs and seeders, that act on behalf of the system rather than the requesting user.
+ *
+ * The internal access covers every call made while the function runs, including the ones made by the service hooks.
+ *
+ * @param {Function} fn - The function to run with internal access.
+ * @return {Object} The value returned by the function.
+ */
+export declare function withoutPolicies<T>(fn: () => T): T;
+/**
+ * Checks whether the current call runs with internal access, started by {@link withoutPolicies}.
+ *
+ * @return {boolean} True if the policies are skipped for the current call, otherwise false.
+ */
+export declare function arePoliciesSkipped(): boolean;

package/utils/policy-util.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withoutPolicies = withoutPolicies;
+exports.arePoliciesSkipped = arePoliciesSkipped;
+const node_async_hooks_1 = require("node:async_hooks");
+const internalAccess = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Runs the given function with internal access, where the resource and file services skip the policies: the access
+ * checks, the read and write restrictions, and the file access checks. Everything else, like the service hooks,
+ * validation, events, and cache invalidation, still runs. Meant for the framework's own flows and trusted application
+ * code, such as jobs and seeders, that act on behalf of the system rather than the requesting user.
+ *
+ * The internal access covers every call made while the function runs, including the ones made by the service hooks.
+ *
+ * @param {Function} fn - The function to run with internal access.
+ * @return {Object} The value returned by the function.
+ */
+function withoutPolicies(fn) {
+    return internalAccess.run(true, fn);
+}
+/**
+ * Checks whether the current call runs with internal access, started by {@link withoutPolicies}.
+ *
+ * @return {boolean} True if the policies are skipped for the current call, otherwise false.
+ */
+function arePoliciesSkipped() {
+    return internalAccess.getStore() === true;
+}

package/utils/virtual-util.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Projects virtual field values onto a resource object based on its model definition. Virtual fields with an output
+ * value function are evaluated against the resource, constant output values are assigned directly, and remaining
+ * required virtual fields receive their default value. Nested relation and file objects are projected recursively
+ * using their own model definitions.
+ *
+ * @param {Object} resource - The resource object to project virtual fields onto.
+ * @param {string} resourceName - The name of the resource model describing the object.
+ * @return {Object} A copy of the resource object with all virtual field values set.
+ */
+export declare function projectVirtualFields<T>(resource: T, resourceName: string): T;

package/utils/virtual-util.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectVirtualFields = projectVirtualFields;
+const common_1 = require("@appweaver/common");
+const core_1 = require("@appweaver/core");
+/**
+ * Projects virtual field values onto a resource object based on its model definition. Virtual fields with an output
+ * value function are evaluated against the resource, constant output values are assigned directly, and remaining
+ * required virtual fields receive their default value. Nested relation and file objects are projected recursively
+ * using their own model definitions.
+ *
+ * @param {Object} resource - The resource object to project virtual fields onto.
+ * @param {string} resourceName - The name of the resource model describing the object.
+ * @return {Object} A copy of the resource object with all virtual field values set.
+ */
+function projectVirtualFields(resource, resourceName) {
+    if (!resource) {
+        return resource;
+    }
+    const projectedVirtual = { ...resource };
+    const resourceModel = (0, core_1.injectModel)(resourceName, false);
+    const relationsModel = resourceModel?.relationsModel;
+    const filesModel = resourceModel?.filesModel;
+    // Set output or default value for virtual fields
+    for (const [fieldName, virtual] of Object.entries(resourceModel?.config?.virtual ?? {})) {
+        const outputValue = virtual.output?.value;
+        if ((0, common_1.isFunction)(outputValue)) {
+            projectedVirtual[fieldName] = outputValue(projectedVirtual);
+        }
+        else if (outputValue) {
+            projectedVirtual[fieldName] = outputValue;
+        }
+        else if (virtual.required !== false) {
+            projectedVirtual[fieldName] =
+                virtual.default ?? (0, common_1.defaultScalarValue)(virtual);
+        }
+    }
+    // Recursively project virtual fields for nested relational objects
+    for (const key in projectedVirtual) {
+        const value = projectedVirtual[key];
+        const relationSchema = (0, common_1.extractSchemaProperties)(relationsModel, key);
+        const fileSchema = (0, common_1.extractSchemaProperties)(filesModel, key);
+        if ((0, common_1.isPlainObject)(value) || ((0, common_1.isArray)(value) && (0, common_1.isPlainObject)(value[0]))) {
+            const nestedResourceName = (0, common_1.extractResourceName)(relationSchema ?? fileSchema);
+            if (nestedResourceName) {
+                projectedVirtual[key] = (0, common_1.isArray)(value)
+                    ? value.map((item) => projectVirtualFields(item, nestedResourceName))
+                    : projectVirtualFields(value, nestedResourceName);
+            }
+        }
+    }
+    return projectedVirtual;
+}