@appweaver/core 1.0.25 → 1.1.0

package/security/oauth2/oauth2-facebook.js

@@ -13,7 +13,7 @@ exports.oauth2Facebook = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1
 });
 async function fetchFacebookUser(accessToken) {
     const params = new URLSearchParams();
-    params.append('fields', 'id,name,email');
+    params.append('fields', 'id,name,email,picture.width(512)');
     params.append('access_token', accessToken);
     const resp = await fetch(`${common_1.config.SECURITY_OAUTH2_FACEBOOK_USER_INFO_URL}?${params}`, { method: 'GET' });
     if (!resp.ok) {
@@ -25,6 +25,7 @@ async function fetchFacebookUser(accessToken) {
         id: data.id,
         email: data.email,
         firstName,
-        lastName
+        lastName,
+        avatarUrl: data.picture?.data?.url
     };
 }

package/security/oauth2/oauth2-google.js

@@ -23,6 +23,7 @@ async function fetchGoogleUser(accessToken) {
         id: data.id,
         email: data.email,
         firstName: data.given_name,
-        lastName: data.family_name
+        lastName: data.family_name,
+        avatarUrl: data.picture
     };
 }

package/seeder/seeder.d.ts

@@ -10,7 +10,7 @@ export declare class Seeder extends LifecycleManager {
     /**
      * Executes the seeders by discovering, validating, and running seeder files.
      * Logs the seeding process, including warnings for checksum mismatches
-     * and files that do not exist but are present in database table.
+     * and files that do not exist but are present in the database table.
      *
      * @return Resolves when all seeders have been processed. Logs relevant
      * information during execution.

package/seeder/seeder.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Seeder = void 0;
 const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const common_1 = require("@appweaver/common");
 const lifecycle_manager_1 = require("../app/lifecycle-manager");
@@ -27,7 +28,7 @@ class Seeder extends lifecycle_manager_1.LifecycleManager {
     /**
      * Executes the seeders by discovering, validating, and running seeder files.
      * Logs the seeding process, including warnings for checksum mismatches
-     * and files that do not exist but are present in database table.
+     * and files that do not exist but are present in the database table.
      *
      * @return Resolves when all seeders have been processed. Logs relevant
      * information during execution.
@@ -133,11 +134,11 @@ class Seeder extends lifecycle_manager_1.LifecycleManager {
                 }
             }
         }
-        const seederHash = await this.seederHash(seederFile);
+        const checksum = await this.seederHash(seederFile);
         // Insert seeder result into the database
         await this._db.client().seeder.create({
             data: {
-                checksum: seederHash,
+                checksum,
                 seederName: this.seederName(seederFile),
                 startedAt: start,
                 finishedAt: new Date(),
@@ -161,8 +162,7 @@ class Seeder extends lifecycle_manager_1.LifecycleManager {
     }
     /** @internal */
     async seederHash(seederFile) {
-        const seederContent = await promises_1.default.readFile(seederFile, 'utf8');
-        return (0, common_1.makeHash)(seederContent);
+        return (0, common_1.makeHash)(node_fs_1.default.createReadStream(seederFile, 'utf8'));
     }
     /** @internal */
     seederName(seederFile) {

package/server/index.d.ts

@@ -2,3 +2,4 @@ export * from './create-server';
 export * from './register-model';
 export * from './register-plugin';
 export * from './register-route';
+export * from './virtual-projection';

package/server/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./create-server"), exports);
 __exportStar(require("./register-model"), exports);
 __exportStar(require("./register-plugin"), exports);
 __exportStar(require("./register-route"), exports);
+__exportStar(require("./virtual-projection"), exports);

package/server/register-route.js

@@ -10,6 +10,7 @@ const common_1 = require("@appweaver/common");
 const context_1 = require("../context");
 const security_1 = require("../security");
 const errors_1 = require("../errors");
+const virtual_projection_1 = require("./virtual-projection");
 function registerRoute(handler, config) {
     const routes = [];
     const tempServer = (0, fastify_1.default)({
@@ -37,6 +38,12 @@ function registerRoute(handler, config) {
                 recaptcha: config?.recaptcha,
                 recaptchaAction: config?.recaptchaAction
             });
+            // Automatically project virtual fields onto response payloads for routes
+            // whose response schemas reference resource models
+            const projectionPlan = (0, virtual_projection_1.buildVirtualProjectionPlan)(route.schema?.response, (id) => server.getSchema(id));
+            const projectionHook = Object.keys(projectionPlan).length > 0
+                ? (0, virtual_projection_1.createVirtualProjectionHook)(projectionPlan)
+                : undefined;
             // Merge received route schema with default values based on configuration
             const mergedRoute = {
                 ...route,
@@ -61,6 +68,12 @@ function registerRoute(handler, config) {
                     config?.recaptcha || config?.recaptchaAction ? recaptcha : undefined,
                     ...((0, common_1.isArray)(route.onRequest) ? route.onRequest : [route.onRequest])
                 ].filter((h) => h !== undefined),
+                preSerialization: [
+                    ...((0, common_1.isArray)(route.preSerialization)
+                        ? route.preSerialization
+                        : [route.preSerialization]),
+                    projectionHook
+                ].filter((h) => h !== undefined),
                 config: {
                     ...config,
                     ...route.config

package/server/virtual-projection.d.ts

@@ -0,0 +1,26 @@
+import { preSerializationAsyncHookHandler } from 'fastify';
+export type VirtualProjectionEntry = {
+    path: string[];
+    resourceName: string;
+};
+export type VirtualProjectionPlan = Record<string, VirtualProjectionEntry[]>;
+/**
+ * Builds a virtual field projection plan from route response schemas. Each 2xx response schema is walked, resolving
+ * `$ref` references through the provided schema lookup, and every location referencing a resource output model
+ * (`<Name>`, `<Name>Single` or `<Name>Multiple`) whose model defines virtual fields — directly or through nested
+ * relations and files — is recorded as a payload path to project before serialization.
+ *
+ * @param {Record<string, unknown>} [responseSchemas] - The route `schema.response` object keyed by status code.
+ * @param {(id: string) => unknown} getSchema - Lookup function resolving a schema `$id` to its schema object.
+ * @return {VirtualProjectionPlan} Projection entries grouped by response status code, empty when no resource output
+ * models with virtual fields are referenced.
+ */
+export declare function buildVirtualProjectionPlan(responseSchemas: Record<string, unknown> | undefined, getSchema: (id: string) => unknown): VirtualProjectionPlan;
+/**
+ * Creates a Fastify `preSerialization` hook that applies a virtual field projection plan to the response payload.
+ * Projection failures are logged and never fail the request — the original payload is returned instead.
+ *
+ * @param {VirtualProjectionPlan} plan - The projection plan built from the route response schemas.
+ * @return {preSerializationAsyncHookHandler} The `preSerialization` hook applying the plan.
+ */
+export declare function createVirtualProjectionHook(plan: VirtualProjectionPlan): preSerializationAsyncHookHandler;

package/server/virtual-projection.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVirtualProjectionPlan = buildVirtualProjectionPlan;
+exports.createVirtualProjectionHook = createVirtualProjectionHook;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+const utils_1 = require("../utils");
+/** Path segment marking an array level inside a projection path. */
+const ARRAY_SEGMENT = '[]';
+/**
+ * Schema `$id` suffixes of resource output models that represent a single resource instance. Longer suffixes are
+ * matched first so that `PostSingle` resolves to the `Post` model instead of a (nonexistent) `PostSingle` model.
+ */
+const INSTANCE_SUFFIXES = ['Single', 'Multiple', ''];
+/**
+ * Builds a virtual field projection plan from route response schemas. Each 2xx response schema is walked, resolving
+ * `$ref` references through the provided schema lookup, and every location referencing a resource output model
+ * (`<Name>`, `<Name>Single` or `<Name>Multiple`) whose model defines virtual fields — directly or through nested
+ * relations and files — is recorded as a payload path to project before serialization.
+ *
+ * @param {Record<string, unknown>} [responseSchemas] - The route `schema.response` object keyed by status code.
+ * @param {(id: string) => unknown} getSchema - Lookup function resolving a schema `$id` to its schema object.
+ * @return {VirtualProjectionPlan} Projection entries grouped by response status code, empty when no resource output
+ * models with virtual fields are referenced.
+ */
+function buildVirtualProjectionPlan(responseSchemas, getSchema) {
+    const plan = {};
+    for (const [status, schema] of Object.entries(responseSchemas ?? {})) {
+        if (!/^2(\d\d|xx)$/i.test(status)) {
+            continue;
+        }
+        const entries = [];
+        collectProjectionEntries(schema, [], entries, getSchema, new Set());
+        if (entries.length > 0) {
+            plan[status.toLowerCase()] = entries;
+        }
+    }
+    return plan;
+}
+/**
+ * Creates a Fastify `preSerialization` hook that applies a virtual field projection plan to the response payload.
+ * Projection failures are logged and never fail the request — the original payload is returned instead.
+ *
+ * @param {VirtualProjectionPlan} plan - The projection plan built from the route response schemas.
+ * @return {preSerializationAsyncHookHandler} The `preSerialization` hook applying the plan.
+ */
+function createVirtualProjectionHook(plan) {
+    return async (_request, reply, payload) => {
+        const entries = plan[String(reply.statusCode)] ?? plan['2xx'];
+        if (!entries?.length || (!(0, common_1.isObject)(payload) && !(0, common_1.isArray)(payload))) {
+            return payload;
+        }
+        try {
+            let projected = payload;
+            for (const entry of entries) {
+                projected = applyProjection(projected, entry.path, 0, entry.resourceName);
+            }
+            return projected;
+        }
+        catch (e) {
+            common_1.logger.warn(e, 'Error projecting virtual fields on response payload');
+            return payload;
+        }
+    };
+}
+/**
+ * Recursively walks a response schema and collects the payload paths at which resource output models appear. Resolves
+ * `$ref` references through the schema lookup, unwraps OpenAPI media type `content` objects, descends into `allOf` /
+ * `anyOf` / `oneOf` branches, and appends an {@link ARRAY_SEGMENT} marker for every array level entered.
+ *
+ * @param {unknown} schema - The schema node currently being walked, ignored when it is not an object.
+ * @param {string[]} path - Payload path segments accumulated from the response root to the current node.
+ * @param {VirtualProjectionEntry[]} entries - Accumulator the collected projection entries are pushed into.
+ * @param {(id: string) => unknown} getSchema - Lookup function resolving a schema `$id` to its schema object.
+ * @param {Set<string>} visitedRefs - Schema `$id`s already resolved along the current descent, guarding against
+ * circular references.
+ * @return {void}
+ */
+function collectProjectionEntries(schema, path, entries, getSchema, visitedRefs) {
+    if (!(0, common_1.isObject)(schema)) {
+        return;
+    }
+    if ((0, common_1.isString)(schema['$ref'])) {
+        const refName = schema['$ref'].replace(/#$/, '');
+        if (recordInstanceEntry(refName, path, entries)) {
+            return;
+        }
+        // Guard against circular schema references along the current descent
+        if (visitedRefs.has(refName)) {
+            return;
+        }
+        collectProjectionEntries(getSchema(refName), path, entries, getSchema, new Set([...visitedRefs, refName]));
+        return;
+    }
+    if ((0, common_1.isString)(schema['$id']) &&
+        recordInstanceEntry(schema['$id'], path, entries)) {
+        return;
+    }
+    // OpenAPI-style response objects wrap the schema in media type content
+    if ((0, common_1.isObject)(schema['content'])) {
+        for (const media of Object.values(schema['content'])) {
+            collectProjectionEntries(media?.schema, path, entries, getSchema, visitedRefs);
+        }
+        return;
+    }
+    for (const composite of ['allOf', 'anyOf', 'oneOf']) {
+        if ((0, common_1.isArray)(schema[composite])) {
+            for (const branch of schema[composite]) {
+                collectProjectionEntries(branch, path, entries, getSchema, visitedRefs);
+            }
+        }
+    }
+    if ((0, common_1.isObject)(schema['items'])) {
+        collectProjectionEntries(schema['items'], [...path, ARRAY_SEGMENT], entries, getSchema, visitedRefs);
+    }
+    if ((0, common_1.isObject)(schema['properties'])) {
+        for (const [key, property] of Object.entries(schema['properties'])) {
+            collectProjectionEntries(property, [...path, key], entries, getSchema, visitedRefs);
+        }
+    }
+}
+/**
+ * Records a projection entry when the schema name resolves to a resource output model. Returns whether the name
+ * denotes a resource instance schema, regardless of an entry being recorded, since resource model schemas are
+ * projected recursively and must not be walked any further.
+ *
+ * @param {string} name - The schema name (`$id` or `$ref`) to resolve to a resource output model.
+ * @param {string[]} path - Payload path at which the schema was encountered.
+ * @param {VirtualProjectionEntry[]} entries - Accumulator the entry is pushed into, unless an equal entry is already
+ * present or the resource has no projectable fields.
+ * @return {boolean} `true` when the name denotes a resource instance schema, `false` otherwise.
+ */
+function recordInstanceEntry(name, path, entries) {
+    const resourceName = resolveInstanceResourceName(name);
+    if (!resourceName) {
+        return false;
+    }
+    const exists = entries.some((entry) => entry.resourceName === resourceName &&
+        entry.path.length === path.length &&
+        entry.path.every((segment, index) => segment === path[index]));
+    if (!exists && hasProjectableFields(resourceName, new Set())) {
+        entries.push({ path, resourceName });
+    }
+    return true;
+}
+/**
+ * Resolves a schema name to the name of the resource whose output model it represents, by stripping each of the
+ * {@link INSTANCE_SUFFIXES} in turn and returning the first candidate that matches a registered model.
+ *
+ * @param {string} name - The schema name (`$id` or `$ref`) to resolve.
+ * @return {string | undefined} The resource name, or `undefined` when the schema does not belong to a registered
+ * resource model.
+ */
+function resolveInstanceResourceName(name) {
+    for (const suffix of INSTANCE_SUFFIXES) {
+        if (suffix && !name.endsWith(suffix)) {
+            continue;
+        }
+        const resourceName = suffix ? name.slice(0, -suffix.length) : name;
+        if (resourceName && (0, context_1.injectModel)(resourceName, false)) {
+            return resourceName;
+        }
+    }
+    return undefined;
+}
+/**
+ * Checks whether projecting a resource would set any values — the model defines virtual fields itself, or reaches a
+ * model with virtual fields through its relations or files.
+ *
+ * @param {string} resourceName - Name of the resource model to check.
+ * @param {Set<string>} visited - Resource names already checked along the current descent, guarding against circular
+ * relations.
+ * @return {boolean} `true` when the resource or any resource reachable through its relations or files defines virtual
+ * fields, `false` otherwise.
+ */
+function hasProjectableFields(resourceName, visited) {
+    const resourceModel = (0, context_1.injectModel)(resourceName, false);
+    if (!resourceModel || visited.has(resourceName)) {
+        return false;
+    }
+    visited.add(resourceName);
+    if (Object.keys(resourceModel.config?.virtual ?? {}).length > 0) {
+        return true;
+    }
+    for (const schema of [
+        resourceModel.relationsModel,
+        resourceModel.filesModel
+    ]) {
+        const properties = (0, common_1.extractSchemaProperties)(schema) ?? {};
+        for (const key of Object.keys(properties)) {
+            const nestedName = (0, common_1.extractResourceName)((0, common_1.extractSchemaProperties)(schema, key));
+            if (nestedName && hasProjectableFields(nestedName, visited)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Walks a payload along a projection path and projects the resource virtual fields onto every object reached at its
+ * end, mapping over array elements for each {@link ARRAY_SEGMENT} marker. Objects along the path are mutated in place,
+ * while arrays are mapped into new ones.
+ *
+ * @param {any} value - The payload node currently being walked.
+ * @param {string[]} path - Payload path segments leading to the values to project.
+ * @param {number} index - Index of the path segment to apply at this level.
+ * @param {string} resourceName - Name of the resource model whose virtual fields are projected.
+ * @return {any} The payload node with virtual fields projected, or the node unchanged when the path does not resolve.
+ */
+function applyProjection(value, path, index, resourceName) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (index === path.length) {
+        if ((0, common_1.isArray)(value)) {
+            return value.map((item) => (0, common_1.isObject)(item) ? (0, utils_1.projectVirtualFields)(item, resourceName) : item);
+        }
+        return (0, common_1.isObject)(value) ? (0, utils_1.projectVirtualFields)(value, resourceName) : value;
+    }
+    const segment = path[index];
+    if (segment === ARRAY_SEGMENT) {
+        return (0, common_1.isArray)(value)
+            ? value.map((item) => applyProjection(item, path, index + 1, resourceName))
+            : value;
+    }
+    if (!(0, common_1.isObject)(value) || value[segment] === undefined) {
+        return value;
+    }
+    value[segment] = applyProjection(value[segment], path, index + 1, resourceName);
+    return value;
+}

package/storage/file-service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileService = void 0;
+const node_stream_1 = require("node:stream");
 const common_1 = require("@appweaver/common");
 const context_1 = require("../context");
 const errors_1 = require("../errors");
@@ -169,11 +170,28 @@ class FileService {
         if ((0, utils_1.isProcessableImage)(data.mimetype)) {
             fileStream = (0, utils_1.processImage)(data.file, data.mimetype, fileConfig.image);
         }
-        const fileName = await this._storage.store(generatedName, fileStream);
+        // Tee the stream so the checksum is calculated over the exact bytes
+        // written to storage in a single pass, without buffering the file.
+        const storageStream = new node_stream_1.PassThrough();
+        const checksumStream = new node_stream_1.PassThrough();
+        fileStream.pipe(storageStream);
+        fileStream.pipe(checksumStream);
+        // pipe() does not forward source errors to destinations, so both branches
+        // must be destroyed manually to avoid hanging on a failed upload stream.
+        fileStream.on('error', (e) => {
+            common_1.logger.error(e, 'Error calculating file checksum');
+            storageStream.destroy(e);
+            checksumStream.destroy(e);
+        });
+        const [fileName, checksum] = await Promise.all([
+            this._storage.store(generatedName, storageStream),
+            (0, common_1.makeHash)(checksumStream)
+        ]);
         if (!fileName) {
             throw new errors_1.HttpError('Error saving file to storage', 500);
         }
         createFile.name = fileName;
+        createFile.checksum = checksum;
         // File size checks must come after storing a file due to bytesRead and
         // truncated fields being set only after reading the full file stream.
         const maxSizeBytes = (0, utils_1.sizeInBytes)(fileConfig.maxSize);
@@ -209,7 +227,7 @@ class FileService {
             if ((0, common_1.isArray)(result[data.fieldname])) {
                 file = result[data.fieldname].find((f) => f.name === createFile.name);
             }
-            file.url = this.buildFileUrl(file, policy);
+            file.url = (0, utils_1.buildFileUrl)(file);
             common_1.logger.debug({ file }, 'File saved');
             return file;
         }
@@ -288,7 +306,7 @@ class FileService {
             const deletedFile = (await this._db.client().file.delete({
                 where: { name: fileName }
             }));
-            deletedFile.url = this.buildFileUrl(deletedFile, policy);
+            deletedFile.url = (0, utils_1.buildFileUrl)(deletedFile);
             common_1.logger.debug({ deletedFile }, 'File deleted');
             return deletedFile;
         }
@@ -382,10 +400,6 @@ class FileService {
         return deletedFiles;
     }
     /** @internal */
-    buildFileUrl(file, policy) {
-        return `${common_1.config.APP_HOSTNAME}/files/${policy.accessType === 'public' ? 'public' : 'protected'}/${file.name}`;
-    }
-    /** @internal */
     async deleteSafe(fileName) {
         let success = true;
         try {

package/storage/resources/file/model.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const common_1 = require("@appweaver/common");
 const factory_1 = require("../../../factory");
-const context_1 = require("../../../context");
+const utils_1 = require("../../../utils");
 exports.default = (0, factory_1.createModel)({
     name: 'File',
     scalars: {
@@ -26,6 +25,11 @@ exports.default = (0, factory_1.createModel)({
             minimum: 0,
             example: 1024
         },
+        checksum: {
+            type: 'string',
+            maxLength: 128,
+            example: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
+        },
         title: {
             type: 'string',
             maxLength: 511,
@@ -62,12 +66,7 @@ exports.default = (0, factory_1.createModel)({
                 type: 'none'
             },
             output: {
-                value: (file) => {
-                    const accessType = (0, context_1.injectPolicy)(file.resourceName ?? '', false)
-                        ?.files?.[file.resourceField ?? '']?.accessType;
-                    const pathPrefix = accessType === 'public' ? 'public' : 'protected';
-                    return `${common_1.config.APP_HOSTNAME}/files/${pathPrefix}/${file.name}`;
-                }
+                value: (file) => (0, utils_1.buildFileUrl)(file)
             }
         }
     },

package/types/auth.d.ts

@@ -1,4 +1,4 @@
-import { AuthScope, AuthSource } from '@appweaver/common';
+import { AuthScope, AuthSource, AuthUser } from '@appweaver/common';
 export type JwtPayload = {
     scope: AuthScope;
     source: AuthSource;
@@ -24,8 +24,24 @@ export type TwoFactorAuthData = {
 export type OAuth2StateData = {
     redirectToUrl: string;
 };
+export type UserInfo = {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    avatarUrl?: string;
+};
+export type AvatarFile = {
+    name: string;
+    mimeType: string;
+    size: number;
+    data: Buffer;
+};
 export type UserAdditionalData = {
     firstName: string;
     lastName: string;
+    avatarUrl?: string;
+    avatarFile?: AvatarFile;
 };
 export type RegistrationDataFn<T = any> = (source: AuthSource, email: string, password?: string, additionalData?: Partial<UserAdditionalData>) => T | Promise<T>;
+export type CheckOAuth2UserFn = (source: AuthSource, userInfo: UserInfo, authUser: AuthUser | null) => void | string | Error | Promise<void | string | Error>;

package/types/generated.d.ts

@@ -139,6 +139,7 @@ export type File = {
     originalName: string;
     mimeType: string;
     sizeBytes: number;
+    checksum?: string | null;
     title?: string | null;
     description?: string | null;
     resourceField?: string | null;
@@ -155,6 +156,7 @@ export type FileSingle = {
     originalName: string;
     mimeType: string;
     sizeBytes: number;
+    checksum?: string | null;
     title?: string | null;
     description?: string | null;
     url: string;
@@ -168,6 +170,7 @@ export type FileMultiple = {
     originalName: string;
     mimeType: string;
     sizeBytes: number;
+    checksum?: string | null;
     title?: string | null;
     description?: string | null;
     url: string;
@@ -180,6 +183,7 @@ export type FileCreate = {
     originalName: string;
     mimeType: string;
     sizeBytes: number;
+    checksum?: string | null;
     title?: string | null;
     description?: string | null;
 };
@@ -188,6 +192,7 @@ export type FileUpdate = {
     originalName?: string;
     mimeType?: string;
     sizeBytes?: number;
+    checksum?: string | null;
     title?: string | null;
     description?: string | null;
 };

package/utils/file-util.d.ts

@@ -1,5 +1,14 @@
 import { FilesConfig } from '@appweaver/common';
 import { File } from '../types';
+/**
+ * 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.
+ */
+export declare function buildFileUrl(file: File): string;
 /**
  * Parses a range string and converts it into an object with start and end values.
  *

package/utils/file-util.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFileUrl = buildFileUrl;
 exports.parseRange = parseRange;
 exports.maxFileSize = maxFileSize;
 exports.sizeInBytes = sizeInBytes;
@@ -8,6 +9,21 @@ exports.generateFileName = generateFileName;
 exports.sanitizeFilename = sanitizeFilename;
 exports.aggregateFiles = aggregateFiles;
 const common_1 = require("@appweaver/common");
+const context_1 = require("../context");
+/**
+ * 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, context_1.injectPolicy)(file.resourceName ?? '', false)?.files?.[file.resourceField ?? '']?.accessType;
+    const pathPrefix = accessType === 'public' ? 'public' : 'protected';
+    const routePrefix = `/${common_1.config.STORAGE_FILES_ROUTE_PREFIX}/`.replace(/\/+/g, '/');
+    return `${common_1.config.APP_HOSTNAME}${routePrefix}${pathPrefix}/${file.name}`;
+}
 /**
  * Parses a range string and converts it into an object with start and end values.
  *

package/utils/index.d.ts

@@ -2,3 +2,4 @@ export * from './export-util';
 export * from './file-util';
 export * from './image-util';
 export * from './schema-util';
+export * from './virtual-util';

package/utils/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./export-util"), exports);
 __exportStar(require("./file-util"), exports);
 __exportStar(require("./image-util"), exports);
 __exportStar(require("./schema-util"), exports);
+__exportStar(require("./virtual-util"), exports);

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;