@appweaver/data 0.0.0-stage → 2.0.0

package/resource/resource-service.js

@@ -0,0 +1,1042 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceService = void 0;
+const common_1 = require("@appweaver/common");
+const resource_config_1 = require("./resource-config");
+const core_1 = require("@appweaver/core");
+const policy_util_1 = require("../utils/policy-util");
+const model_util_1 = require("../utils/model-util");
+const virtual_util_1 = require("../utils/virtual-util");
+const database_error_1 = require("../database/database-error");
+const file_service_1 = require("../storage/file-service");
+const delete_util_1 = require("./utils/delete-util");
+const aggregate_util_1 = require("./utils/aggregate-util");
+const relation_util_1 = require("./utils/relation-util");
+const cursor_util_1 = require("./utils/cursor-util");
+const filter_util_1 = require("./utils/filter-util");
+const sort_util_1 = require("./utils/sort-util");
+class ResourceService {
+    modelName;
+    /** @internal */
+    _db = (0, core_1.inject)(common_1.Database);
+    /** @internal */
+    _events = (0, core_1.inject)(common_1.Events);
+    /** @internal */
+    _cacheService = (0, core_1.inject)(core_1.CacheService);
+    /** @internal */
+    _modelKey;
+    /**
+     * Creates the service for the given resource model and resolves its database
+     * client from the Prisma client instance.
+     *
+     * @param {string} modelName The resource model name this service operates on,
+     * as defined by its model file (i.e. `User`, `Post`).
+     * @throws An error if no database client exists for the provided model name.
+     */
+    constructor(modelName) {
+        this.modelName = modelName;
+        this._modelKey = (0, common_1.uncapitalize)(modelName);
+        if (!this._client) {
+            throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `ResourceService initialized with invalid model name: ${modelName}`);
+        }
+    }
+    /**
+     * The underlying Prisma model delegate for this resource, useful for
+     * executing custom database operations that the service methods do not cover.
+     *
+     * @return {ResourceClient} The resource client of the model this service was
+     * created for, bound to the current transaction (see `runTransaction`).
+     */
+    get client() {
+        return this._client;
+    }
+    /**
+     * Finds a single resource by its id, applying the read restrictions and the
+     * access check of this service, and including all relation and file fields
+     * configured for output on the find action. A resource event is emitted after
+     * a successful lookup.
+     *
+     * @param {ResourceId} id The id of the resource to find.
+     * @return {Promise<Object>} The found resource with its virtual fields and
+     * relation counts projected.
+     * @throws {@link ResourceError} `RESOURCE_NOT_FOUND` if the resource does not
+     * exist or is filtered out by the read restrictions, `RESOURCE_FORBIDDEN` if
+     * the access check denies it, and a {@link DatabaseError} on a database error.
+     */
+    async find(id) {
+        const restrictions = await this.applyReadRestrictions('find', id);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'find');
+        let resource;
+        try {
+            resource = await this._client.findFirst({
+                where: { id, ...restrictions, ...(0, model_util_1.liveRecordFilter)(this._client.name) },
+                include: includeRelations
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e, id);
+        }
+        if (!resource || resource.id !== id) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceNotFound, `${this._client.name} not found`, { model: this._client.name, id });
+        }
+        const access = await this.applyAccessCheck('find', resource);
+        if (!access) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceForbidden, `${this._client.name} access is forbidden`, { model: this._client.name, action: 'find' });
+        }
+        this._events.emitResourceEvent(this._client.name, 'find', {
+            current: resource
+        });
+        return this.projectResource(resource);
+    }
+    /**
+     * Queries a page of resources matching the provided filter. The filter is
+     * mapped to a database query, combined with the optional `searchText` full
+     * text search query and the read restrictions of this service, and executed
+     * together with the total count in a single transaction. A resource event is
+     * emitted after a successful query.
+     *
+     * @param {QueryOptions} [options] The query options:
+     * - `filter` The query filter object, supporting the logical (`_and`, `_or`,
+     *   `_not`, `_nor`), comparison (`_eq`, `_ne`, `_gt`, `_gte`, `_lt`, `_lte`,
+     *   `_in`, `_nin`, `_between`, `_like`, `_ilike`, `_starts`, `_ends`,
+     *   `_contains`, `_exists`), list (`_has`, `_hasSome`, `_hasEvery`,
+     *   `_isEmpty`), and relation (`_some`, `_every`, `_none`) operators, as well
+     *   as plain field values. Its `searchText` property, if present, is passed to
+     *   {@link ResourceService.textSearchQuery} instead of being matched as a
+     *   field.
+     * - `page` The one-based page number of results to return, ignored when a
+     *   cursor is given (default: `1`).
+     * - `size` The maximum number of results per page (default: `50`).
+     * - `sort` The fields to sort by, either as a comma-separated list where a
+     *   field prefixed with `-` is sorted in descending order (i.e.
+     *   `-createdAt,id`), or as an object of field directions (i.e.
+     *   `{ createdAt: 'desc', id: 'asc' }`). Both forms support the fields of the
+     *   included to-one relations, given with a dot notation (`author.createdAt`)
+     *   or as a nested object (`{ author: { createdAt: 'desc' } }`) (default:
+     *   `-createdAt`).
+     * - `cursor` The cursor of the page to return, as issued in the `nextCursor`
+     *   or `prevCursor` of an earlier response, which also carries the direction
+     *   the page runs in. Takes precedence over `page`.
+     * - `totalCount` Whether to count all matching resources, which costs a scan
+     *   of every one of them (default: `true`).
+     * @return {Promise<QueryResponse<Object>>} The paged query response containing
+     * the returned resources, the count of the returned items, the cursors of the
+     * adjacent pages, and the total count unless it was opted out of.
+     * @throws {@link ResourceError} `RESOURCE_INVALID_SORT` if the sort input names
+     * a field that cannot be sorted by, `RESOURCE_INVALID_CURSOR` if the cursor
+     * was issued for another filter or sort order, and a {@link DatabaseError} on
+     * a database error.
+     */
+    async query(options = {}) {
+        const { filter = {}, page = 1, size = 50, sort = '-createdAt', cursor, totalCount = true } = options;
+        const query = await this.queryConditions('query', filter);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'query');
+        const orderBy = (0, sort_util_1.mapStableSortValues)(sort, this._client.name, 'query');
+        // Binding to the mapped query rather than the filter also invalidates a
+        // cursor on a changed text search or read restriction
+        const fingerprint = (0, cursor_util_1.queryFingerprint)(this._client.name, query, orderBy);
+        const decodedCursor = (0, cursor_util_1.decodeCursor)(cursor, fingerprint);
+        // One record past the page tells whether a further page exists
+        const backward = decodedCursor?.backward === true;
+        const take = size > 0 ? size + 1 : 0;
+        const findMany = this._client.findMany({
+            where: { ...query },
+            include: includeRelations,
+            // A cursor skips the record it addresses, an offset the pages before it
+            cursor: decodedCursor ? { id: decodedCursor.id } : undefined,
+            skip: decodedCursor ? 1 : (page - 1) * size,
+            take: backward ? -take : take,
+            orderBy
+        });
+        let resources;
+        let count;
+        try {
+            if (totalCount) {
+                [resources, count] = await this._db
+                    .client()
+                    .$transaction([
+                    findMany,
+                    this._client.count({ where: { ...query } })
+                ]);
+            }
+            else {
+                resources = await findMany;
+            }
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+        // The over-fetched record leads a backward page and trails a forward one
+        const hasMore = resources.length > size;
+        if (hasMore) {
+            resources = backward
+                ? resources.slice(resources.length - size)
+                : resources.slice(0, size);
+        }
+        // The page a cursor was followed from always exists
+        const hasNext = backward || hasMore;
+        const hasPrev = backward ? hasMore : !!decodedCursor || page > 1;
+        this._events.emitResourceEvent(this._client.name, 'query', {
+            current: resources
+        });
+        return {
+            resultCount: resources.length,
+            totalCount: count ?? null,
+            ...(0, cursor_util_1.pageCursors)(resources, fingerprint, hasNext, hasPrev),
+            items: resources.map((resource) => this.projectResource(resource))
+        };
+    }
+    /**
+     * Finds the first resource matching the provided filter, applying the read
+     * restrictions of the query action and the access check of the find action,
+     * and including the relation and file fields configured for output on the
+     * find action. A resource event of the find action is emitted when a resource
+     * matches.
+     *
+     * @param {Object} [filter] The query filter object, mapped the same way as in
+     * {@link ResourceService.query}.
+     * @param {QuerySort} [sort] The fields to sort the matching resources by, of
+     * which the first one is returned, in the same form as in
+     * {@link ResourceService.query} (default: `-createdAt`).
+     * @return {Promise<Object|null>} The first matching resource with its virtual
+     * fields and relation counts projected, or null when none matches.
+     * @throws {@link ResourceError} `RESOURCE_FORBIDDEN` if the access check denies
+     * the matching resource, `RESOURCE_INVALID_SORT` if the sort input names a
+     * field that cannot be sorted by, and a {@link DatabaseError} on a database
+     * error.
+     */
+    async single(filter = {}, sort = '-createdAt') {
+        const where = await this.queryConditions('query', filter);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'find');
+        const orderBy = (0, sort_util_1.mapStableSortValues)(sort, this._client.name, 'find');
+        let resource;
+        try {
+            resource = await this._client.findFirst({
+                where,
+                include: includeRelations,
+                orderBy
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+        if (!resource) {
+            return null;
+        }
+        const access = await this.applyAccessCheck('find', resource);
+        if (!access) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceForbidden, `${this._client.name} access is forbidden`, { model: this._client.name, action: 'find' });
+        }
+        this._events.emitResourceEvent(this._client.name, 'find', {
+            current: resource
+        });
+        return this.projectResource(resource);
+    }
+    /**
+     * Counts the resources matching the provided filter, applying the read
+     * restrictions of the query action.
+     *
+     * @param {Object} [filter] The query filter object, mapped the same way as in
+     * {@link ResourceService.query}.
+     * @return {Promise<number>} The number of matching resources.
+     * @throws {@link DatabaseError} On a database error.
+     */
+    async count(filter = {}) {
+        const where = await this.queryConditions('query', filter);
+        try {
+            return await this._client.count({ where });
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+    }
+    /**
+     * Checks whether any resource matches the provided filter, applying the read
+     * restrictions of the query action.
+     *
+     * @param {Object} [filter] The query filter object, mapped the same way as in
+     * {@link ResourceService.query}.
+     * @return {Promise<boolean>} True if at least one resource matches, otherwise
+     * false.
+     * @throws {@link DatabaseError} On a database error.
+     */
+    async exists(filter = {}) {
+        const where = await this.queryConditions('query', filter);
+        let resource;
+        try {
+            resource = await this._client.findFirst({ where, select: { id: true } });
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+        return resource !== null;
+    }
+    /**
+     * Aggregates resources matching the provided filter over a date range, both
+     * as a single overall result and as a series of results for the equally sized
+     * periods the range is split into. All aggregations are executed in a single
+     * transaction.
+     *
+     * @param {AggregateOptions} options The aggregation options:
+     * - `select` The aggregation operations to perform per field (i.e.
+     *   `{ views: { count: true, sum: true } }`). Only the numeric fields of the
+     *   model accept every operator, while its date fields accept `count`, `min`,
+     *   `max`, `first` and `last`. The `first` and `last` operators take the value
+     *   the earliest and the latest record of a period holds, which costs one
+     *   additional query per period and boundary, skipped for the periods holding
+     *   no record.
+     * - `filter` The query filter object, mapped the same way as in
+     *   {@link ResourceService.query}.
+     * - `dateField` The date field the range is applied on (default:
+     *   `createdAt`).
+     * - `from` The ISO date string of the range start. Defaults to seven days
+     *   before the range end.
+     * - `to` The ISO date string of the range end. Defaults to the current date
+     *   and time.
+     * - `step` The size of a single period in units of the automatically selected
+     *   time unit. If not provided, one unit is used and the unit is derived from
+     *   the range length (seconds up to a minute, minutes up to an hour, hours up
+     *   to a day, days up to a month, months up to a year, and years beyond that).
+     * - `safeIncrement` Whether the period increments use the derived time unit
+     *   and stay consistent across daylight saving time changes. When false, the
+     *   step is interpreted in seconds (default: `true`).
+     * @return {Promise<AggregateResponse<Object>>} The aggregation response with
+     * the overall total and one result per period, each labeled with the median
+     * date of its period. It is typed by the fields the selection named, not by
+     * the whole model, whenever the selection is passed as an object literal or
+     * annotated with `satisfies`.
+     * @throws {@link ResourceError} `RESOURCE_INVALID_AGGREGATE` if the selection
+     * is empty or names a field or operator that cannot be aggregated, and a
+     * {@link DatabaseError} on a database error.
+     */
+    async aggregate(options) {
+        const { select, filter = {}, dateField = 'createdAt', from, to, step, safeIncrement = true } = options;
+        const { fromDate, toDate, ranges: dateRanges } = (0, aggregate_util_1.buildAggregationPeriods)(from, to, step, safeIncrement);
+        const operations = (0, aggregate_util_1.mapAggregationSelect)(select, this._client.name);
+        (0, aggregate_util_1.checkAggregationDateField)(dateField, this._client.name);
+        const query = await this.queryConditions('aggregate', filter);
+        const rangeQuery = (rangeFrom, rangeTo) => ({
+            AND: [query, { [dateField]: { gte: rangeFrom, lt: rangeTo } }]
+        });
+        // Aggregates a single range and reads the boundary records it holds the
+        // first and last values of which the database cannot aggregate
+        const aggregateRange = async (txModel, where) => {
+            const result = await txModel.aggregate({
+                ...operations.aggregate,
+                where
+            });
+            const boundaries = await (0, aggregate_util_1.readAggregationBoundaries)(txModel, where, dateField, operations, (0, aggregate_util_1.aggregationRecordCount)(result));
+            return { ...result, ...boundaries };
+        };
+        let total = {};
+        let items = [];
+        try {
+            [total, items] = await this._db.client().$transaction(async (tx) => {
+                const txModel = tx[this._client.name];
+                const overall = await aggregateRange(txModel, rangeQuery(fromDate, toDate));
+                // Skip executing the same query if only one range value is generated
+                if (dateRanges.length === 1) {
+                    return [overall, [overall]];
+                }
+                const ranges = await Promise.all(dateRanges.map((dateRange) => aggregateRange(txModel, rangeQuery(dateRange.from, dateRange.to))));
+                return [overall, ranges];
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+        return {
+            total: (0, aggregate_util_1.mapAggregationResult)(total),
+            items: items.map((item, index) => ({
+                date: dateRanges[index].median,
+                result: (0, aggregate_util_1.mapAggregationResult)(item)
+            }))
+        };
+    }
+    /**
+     * Creates a new resource. The provided data is merged with the write
+     * restrictions, checked for access, sanitized against the model configuration
+     * and mapped to the relation write actions (connect, create, or
+     * connect-or-create) before the record is created. The `createdBy` audit
+     * relation is connected to the currently authenticated user when configured.
+     * The resource cache is invalidated and a resource event is emitted after a
+     * successful create.
+     *
+     * @param {Object} data The data of the resource to create, including any inline
+     * relation and file payloads.
+     * @return {Promise<Object>} The created resource with its virtual fields and
+     * relation counts projected.
+     * @throws {@link ResourceError} `RESOURCE_FORBIDDEN` if the access check denies
+     * the action, `RESOURCE_INVALID_RELATION` if an inline relation payload is
+     * missing required fields or the relation does not accept new records, and a
+     * {@link DatabaseError} on a database error, i.e. `DATABASE_UNIQUE_VIOLATION`.
+     */
+    async create(data) {
+        const createdBy = (0, relation_util_1.createdByConnect)(this._client.name);
+        const restrictions = await this.applyWriteRestrictions('create', data);
+        const createData = (0, common_1.removeUndefined)({
+            ...data,
+            ...restrictions
+        });
+        const access = await this.applyAccessCheck('create', createData);
+        if (!access) {
+            throw new common_1.ResourceError(common_1.ErrorCode.ResourceForbidden, `${this._client.name} create action is forbidden`, { model: this._client.name, action: 'create' });
+        }
+        const sanitizedData = this.sanitizeData('create', createData);
+        const connectRelations = (0, relation_util_1.mapRelationActions)(this._client.name, 'create', sanitizedData);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'create');
+        await (0, delete_util_1.assertLiveRelationTargets)(this._db.client(), this._client.name, connectRelations);
+        let resource;
+        try {
+            resource = await this._client.create({
+                data: {
+                    ...sanitizedData,
+                    ...connectRelations,
+                    createdBy
+                },
+                include: includeRelations
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e);
+        }
+        await this._cacheService.invalidateCache(this._client.name, 'create');
+        this._events.emitResourceEvent(this._client.name, 'create', {
+            current: resource
+        });
+        return this.projectResource(resource);
+    }
+    /**
+     * Updates an existing resource by its id. The current record is loaded with
+     * the read restrictions applied and checked for access, then updated with the
+     * data merged with the write restrictions inside a single transaction.
+     * Relations missing from the new value are disconnected, or deleted when
+     * `orphanRemoval` is configured for them, the same way a delete does. The resource cache is invalidated and a
+     * resource event carrying both the previous and the current state is emitted
+     * after a successful update.
+     *
+     * @param {ResourceId} id The id of the resource to update.
+     * @param {Object} data The partial data to update the resource with, including
+     * any inline relation and file payloads.
+     * @return {Promise<Object>} The updated resource with its virtual fields and
+     * relation counts projected.
+     * @throws {@link ResourceError} `RESOURCE_NOT_FOUND` if the resource does not
+     * exist or is filtered out by the read restrictions, `RESOURCE_FORBIDDEN` if
+     * the access check denies the action, `RESOURCE_INVALID_RELATION` if an
+     * inline relation payload is missing required fields or the relation does not
+     * accept new records, `RESOURCE_DELETE_RESTRICTED` if a live record
+     * references a soft deleted orphan through a restricting relation, and a
+     * {@link DatabaseError} on a database error, i.e. `DATABASE_UNIQUE_VIOLATION`.
+     */
+    async update(id, data) {
+        const { current } = await this.updateWithPrevious(id, data);
+        return current;
+    }
+    /**
+     * Replaces an existing resource by its id as a whole. The updatable scalar
+     * fields missing from the data are reset to their configured default value,
+     * or to null when they are optional (see
+     * {@link ResourceService.replacementData}), and the resource is then updated
+     * the same way as {@link ResourceService.update}, applying the same policies,
+     * invalidating the same cache, and emitting the same update event. The
+     * optional relations missing from the data are left untouched, and a null or
+     * an empty list clears them.
+     *
+     * @param {ResourceId} id The id of the resource to replace.
+     * @param {Object} data The new state of the resource, including any inline
+     * relation payloads.
+     * @return {Promise<Object>} The replaced resource with its virtual fields and
+     * relation counts projected.
+     * @throws The same errors as {@link ResourceService.update}.
+     */
+    async replace(id, data) {
+        const { current } = await this.updateWithPrevious(id, this.replacementData(data));
+        return current;
+    }
+    /**
+     * Deletes an existing resource by its id. The current record is loaded with
+     * the read restrictions applied and checked for access before it is deleted
+     * inside a single transaction.
+     *
+     * A model with `softDelete` enabled marks the record with the `deletedAt`
+     * and `deletedById` columns instead, soft deleting its cascade as well.
+     *
+     * The stored files of the deleted records follow the `onResourceDeleted`, or
+     * for soft deleted records the `onResourceSoftDeleted`, option of each file
+     * field: kept files are marked deleted in the transaction and no longer
+     * served, the others are removed once it commits. The cache of every affected
+     * model is invalidated and a resource event is emitted.
+     *
+     * @param {ResourceId} id The id of the resource to delete.
+     * @return {Promise<Object>} The deleted resource with its virtual fields and
+     * relation counts projected.
+     * @throws {@link ResourceError} `RESOURCE_NOT_FOUND` if the resource does not
+     * exist or is filtered out by the read restrictions, `RESOURCE_FORBIDDEN` if
+     * the access check denies it, `RESOURCE_DELETE_RESTRICTED` if a restricting
+     * relation still references a soft deleted resource, and a
+     * {@link DatabaseError} on a database error, i.e.
+     * `DATABASE_FOREIGN_KEY_VIOLATION` for a restricting relation of a removed
+     * resource.
+     */
+    async delete(id) {
+        const restrictions = await this.applyReadRestrictions('delete', id);
+        const softDelete = (0, common_1.hasSoftDelete)((0, core_1.injectModel)(this._client.name).config);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'delete');
+        let resource;
+        let deleted;
+        try {
+            [resource, deleted] = await this._db.client().$transaction(async (tx) => {
+                const txModel = tx[this._client.name];
+                // A soft deleted record is read with its relations up front, as a
+                // database delete returns them before the cascade removes them
+                const current = await txModel.findFirst({
+                    where: {
+                        id,
+                        ...restrictions,
+                        ...(0, model_util_1.liveRecordFilter)(this._client.name)
+                    },
+                    include: softDelete ? includeRelations : undefined
+                });
+                if (!current || current.id !== id) {
+                    throw new common_1.ResourceError(common_1.ErrorCode.ResourceNotFound, `${this._client.name} not found`, { model: this._client.name, id });
+                }
+                const access = await this.applyAccessCheck('delete', current);
+                if (!access) {
+                    throw new common_1.ResourceError(common_1.ErrorCode.ResourceForbidden, `${this._client.name} delete action is forbidden`, { model: this._client.name, action: 'delete' });
+                }
+                const data = (0, delete_util_1.softDeleteData)();
+                let result;
+                let records;
+                if (softDelete) {
+                    records = await (0, delete_util_1.softDeleteCascade)(tx, this._client.name, [id], data);
+                    const updated = await txModel.update({ where: { id }, data });
+                    result = { ...current, ...updated };
+                }
+                else {
+                    records = await (0, delete_util_1.cascadedRecords)(tx, this._client.name, [id]);
+                    result = await txModel.delete({
+                        where: { id },
+                        include: includeRelations
+                    });
+                }
+                // Merged rather than spread, since a self cascade holds the same model
+                (0, delete_util_1.mergeAffectedRecords)(records, { [this._client.name]: [id] });
+                const removed = softDelete
+                    ? { soft: records, hard: {} }
+                    : { soft: {}, hard: records };
+                await (0, delete_util_1.retainDeletedFiles)(tx, removed, data);
+                return [result, removed];
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e, id);
+        }
+        await this.cleanupDeletedRecords(deleted);
+        this._events.emitResourceEvent(this._client.name, 'delete', {
+            current: resource
+        });
+        return this.projectResource(resource);
+    }
+    /**
+     * Creates many resources in a single transaction, one after another the same
+     * way as {@link ResourceService.create}, so every item runs through the same
+     * policies and hooks. Either every resource is created or, when any item
+     * fails, none: the error of the failed item is thrown and the transaction is
+     * rolled back. The cache invalidation and the create resource event of every
+     * item wait for the commit, and are dropped on a rollback.
+     *
+     * @param {Object[]} items The data of every resource to create.
+     * @return {Promise<Object[]>} The created resources, in the order of the
+     * items.
+     * @throws The error of the first item that failed, the same errors as
+     * {@link ResourceService.create}.
+     */
+    async bulkCreate(items) {
+        return this.bulk(items, (item) => this.create(item));
+    }
+    /**
+     * Updates the given fields of many resources in a single transaction, one
+     * after another the same way as {@link ResourceService.update}. Either every
+     * resource is updated or none, see {@link ResourceService.bulkCreate}.
+     *
+     * @param {BulkItem[]} items The id and the partial data of every resource.
+     * @return {Promise<Object[]>} The updated resources, in the order of the
+     * items.
+     * @throws The error of the first item that failed, the same errors as
+     * {@link ResourceService.update}.
+     */
+    async bulkUpdate(items) {
+        return this.bulk(items, (item) => this.update(item.id, item.data));
+    }
+    /**
+     * Replaces many resources as a whole in a single transaction, one after
+     * another the same way as {@link ResourceService.replace}. Either every
+     * resource is replaced or none, see {@link ResourceService.bulkCreate}.
+     *
+     * @param {BulkItem[]} items The id and the new state of every resource.
+     * @return {Promise<Object[]>} The replaced resources, in the order of the
+     * items.
+     * @throws The error of the first item that failed, the same errors as
+     * {@link ResourceService.replace}.
+     */
+    async bulkReplace(items) {
+        return this.bulk(items, (item) => this.replace(item.id, item.data));
+    }
+    /**
+     * Deletes many resources in a single transaction, one after another the same
+     * way as {@link ResourceService.delete}, cascades and stored files included.
+     * Either every resource is deleted or none, see
+     * {@link ResourceService.bulkCreate}. Every id must exist up front, while an
+     * id the cascade of an earlier one already removed is skipped.
+     *
+     * @param {ResourceId[]} ids The ids of the resources to delete.
+     * @return {Promise<Object[]>} The resources deleted by their own id, in the
+     * order of the ids.
+     * @throws {@link ResourceError} `RESOURCE_NOT_FOUND` if an id does not exist,
+     * and otherwise the error of the first resource that failed, the same errors
+     * as {@link ResourceService.delete}.
+     */
+    async bulkDelete(ids) {
+        return this.bulk(ids, async (id) => (await this.liveIds([id])).length > 0 ? this.delete(id) : undefined, async () => {
+            const live = (await this.liveIds(ids)).map(String);
+            const missing = ids.find((id) => !live.includes(String(id)));
+            if (missing !== undefined) {
+                throw new common_1.ResourceError(common_1.ErrorCode.ResourceNotFound, `${this._client.name} not found`, { model: this._client.name, id: missing });
+            }
+        });
+    }
+    /**
+     * Updates an existing resource the same way as {@link ResourceService.update},
+     * returning the state the resource had before the update along with the
+     * updated one.
+     *
+     * @param {ResourceId} id The id of the resource to update.
+     * @param {Object} data The partial data to update the resource with.
+     * @return {Promise<{ previous: Object, current: Object }>} The resource before
+     * and after the update, both with their virtual fields and relation counts
+     * projected.
+     */
+    async updateWithPrevious(id, data) {
+        const readRestrictions = await this.applyReadRestrictions('update', {
+            id,
+            ...data
+        });
+        const writeRestrictions = await this.applyWriteRestrictions('update', {
+            id,
+            ...data
+        });
+        const updateData = (0, common_1.removeUndefined)({
+            ...data,
+            ...writeRestrictions
+        });
+        const sanitizedData = this.sanitizeData('update', updateData);
+        const includeRelations = (0, relation_util_1.mapRelationInclusions)(this._client.name, 'update');
+        let updateResource;
+        let resource;
+        let orphans;
+        try {
+            [updateResource, resource, orphans] = await this._db
+                .client()
+                .$transaction(async (tx) => {
+                const txModel = tx[this._client.name];
+                const current = await txModel.findFirst({
+                    where: {
+                        id,
+                        ...readRestrictions,
+                        ...(0, model_util_1.liveRecordFilter)(this._client.name)
+                    },
+                    include: includeRelations
+                });
+                if (!current || current.id !== id) {
+                    throw new common_1.ResourceError(common_1.ErrorCode.ResourceNotFound, `${this._client.name} not found`, { model: this._client.name, id });
+                }
+                const access = await this.applyAccessCheck('update', current);
+                if (!access) {
+                    throw new common_1.ResourceError(common_1.ErrorCode.ResourceForbidden, `${this._client.name} update action is forbidden`, { model: this._client.name, action: 'update' });
+                }
+                const setRelations = (0, relation_util_1.mapRelationActions)(this._client.name, 'update', sanitizedData, current);
+                await (0, delete_util_1.assertLiveRelationTargets)(tx, this._client.name, setRelations);
+                // Soft deleted orphans are marked before the update reads the
+                // relations back, so the response no longer holds them
+                const deleteData = (0, delete_util_1.softDeleteData)();
+                const removed = await (0, delete_util_1.removeOrphans)(tx, this._client.name, setRelations, deleteData);
+                await (0, delete_util_1.retainDeletedFiles)(tx, removed, deleteData);
+                const updated = await txModel.update({
+                    where: { id },
+                    include: includeRelations,
+                    data: { ...sanitizedData, ...setRelations }
+                });
+                return [current, updated, removed];
+            });
+        }
+        catch (e) {
+            throw this.databaseError(e, id);
+        }
+        await this._cacheService.invalidateCache(this._client.name, 'update');
+        await this.cleanupDeletedRecords(orphans);
+        this._events.emitResourceEvent(this._client.name, 'update', {
+            previous: updateResource,
+            current: resource
+        });
+        return {
+            previous: this.projectResource(updateResource),
+            current: this.projectResource(resource)
+        };
+    }
+    /**
+     * Completes the data of a replacement with the updatable scalar fields it
+     * leaves out: each one is set to the `default` value of its configuration,
+     * or to null when it is optional. A required field without a default value,
+     * which the request validation of the PUT route never lets a request leave
+     * out, is left untouched, and so are the hidden fields, the fields the
+     * `update` option of the model excludes, the virtual fields, and the
+     * relations.
+     *
+     * @param {Object} data The data of the replacement.
+     * @return {Object} A shallow copy of the data, with the missing fields set.
+     */
+    replacementData(data) {
+        const resourceModel = (0, core_1.injectModel)(this._client.name);
+        const scalars = resourceModel.config.scalars ?? {};
+        const fields = (0, common_1.extractSchemaProperties)(resourceModel.replaceOneModel) ?? {};
+        const replacement = { ...data };
+        for (const name of Object.keys(fields)) {
+            const scalar = scalars[name];
+            if (!scalar || replacement[name] !== undefined) {
+                continue;
+            }
+            if (scalar.default !== undefined) {
+                replacement[name] = structuredClone(scalar.default);
+            }
+            else if (scalar.required === false) {
+                replacement[name] = null;
+            }
+        }
+        return replacement;
+    }
+    /**
+     * This method should be overridden with custom logic for restricting read
+     * operations on specific data for currently logged-in user and other
+     * authorization rules. The returned object will be applied as a filter on
+     * all actions (except create action) which will prevent unwanted data access
+     * and modifications. This method can also cancel the current action by
+     * throwing an error, i.e. a {@link ResourceError} with the
+     * `RESOURCE_FORBIDDEN` code or an `ApplicationError` with a code of the
+     * application.
+     *
+     * Not called for the calls run with internal access (see `withoutPolicies`).
+     *
+     * @param {ActionType} action The called action method on this service (find,
+     * query, aggregate, update, or delete)
+     * @param {Object|ResourceId} data The passed data to the called function can be
+     * number or object. If the data is a type of number, then it represents the
+     * resource id, otherwise it depends on the action and can be one of the
+     * following:
+     *
+     * - query and aggregate -> filter object
+     * - update -> combined id and the data object (i.e. { id, ...data })
+     *
+     * For other actions (find and delete) it represents the resource id.
+     * @return {Promise<Object>} The database-level `where` conditions containing
+     * additional query restrictions. The returned object is applied directly to
+     * the database query, so it uses the native Prisma filter syntax.
+     */
+    async readRestrictions(action, data) {
+        return {};
+    }
+    /**
+     * This method should be overridden with custom logic for restricting write
+     * operations on specific data for currently logged-in users and other
+     * authorization rules. The returned object will be applied as a filter on
+     * all actions (create and update) to ensure that users can only modify
+     * data they are authorized to access. This method can also cancel the
+     * current action by throwing an error, i.e. a {@link ResourceError} with the
+     * `RESOURCE_FORBIDDEN` code or an `ApplicationError` with a code of the
+     * application.
+     *
+     * Not called for the calls run with internal access (see `withoutPolicies`).
+     *
+     * @param {'create'|'update'} action The called action method on this service
+     * (create or update)
+     * @param {Object} data The passed data to the called function, which should be
+     * an object representing the resource data to be created or updated. For
+     * update operations, this object will also include the resource ID.
+     *
+     * @return {Promise<Object>} A partial object containing additional data
+     * restrictions to be applied, or an empty object if no restrictions are
+     * necessary.
+     */
+    async writeRestrictions(action, data) {
+        return {};
+    }
+    /**
+     * This method should provide logic for checking the access permissions for
+     * the provided resource object. If the resource should not be accessible by
+     *  a currently authenticated user or other logic, this method should return
+     * false. Otherwise, it returns true and continues with the request execution.
+     *
+     * Not called for the calls run with internal access (see `withoutPolicies`).
+     *
+     * @param {ActionType} action The called action method on this service (find,
+     * query, aggregate, create, update, or delete)
+     * @param {Object} resource The resource object that is being checked for access.
+     * @return {Promise<boolean>} True if the access for resource is granted, false
+     * otherwise.
+     */
+    async checkAccess(action, resource) {
+        return true;
+    }
+    /**
+     * Constructs a query object for performing a text search on resources in the
+     * database based on the provided search text. This method will transform the
+     * search text into a format suitable for text search functionality, returning
+     * a query object that can be used to filter results.
+     *
+     * @param {string} searchText The text string used for searching resources.
+     * @return {Object} A query object that represents the conditions for the text
+     * search operation, using the native Prisma filter syntax. This will be used
+     * by the database query methods to retrieve matching resources.
+     */
+    textSearchQuery(searchText) {
+        return {};
+    }
+    /**
+     * Returns the read restrictions of {@link ResourceService.readRestrictions},
+     * or none when the call runs with internal access (see `withoutPolicies`).
+     *
+     * @internal
+     */
+    async applyReadRestrictions(action, data) {
+        return (0, policy_util_1.arePoliciesSkipped)() ? {} : this.readRestrictions(action, data);
+    }
+    /**
+     * Returns the write restrictions of {@link ResourceService.writeRestrictions},
+     * or none when the call runs with internal access (see `withoutPolicies`).
+     *
+     * @internal
+     */
+    async applyWriteRestrictions(action, data) {
+        return (0, policy_util_1.arePoliciesSkipped)() ? {} : this.writeRestrictions(action, data);
+    }
+    /**
+     * Runs the access check of {@link ResourceService.checkAccess}, which always
+     * grants the access when the call runs with internal access (see
+     * `withoutPolicies`).
+     *
+     * @internal
+     */
+    async applyAccessCheck(action, resource) {
+        return (0, policy_util_1.arePoliciesSkipped)() || this.checkAccess(action, resource);
+    }
+    /**
+     * Builds the database conditions of a query filter: the mapped filter, its
+     * text search, the read restrictions of the action, and the conditions
+     * hiding the soft deleted records.
+     *
+     * @internal
+     */
+    async queryConditions(action, filter) {
+        const restrictions = await this.applyReadRestrictions(action, filter);
+        const textSearch = this.extractTextSearchQuery(filter);
+        const mappedFilter = (0, filter_util_1.mapQueryFilter)(filter, this._client.name);
+        return {
+            AND: [mappedFilter, textSearch, restrictions, ...this.liveFilters()]
+        };
+    }
+    /**
+     * Removes the `searchText` property from the provided filter and converts it
+     * into a text search query using
+     * {@link ResourceService.textSearchQuery}. The filter object is mutated so the
+     * search text is not matched as a regular resource field.
+     *
+     * @param {Object} filter The request filter object, possibly containing a
+     * `searchText` property. The property is deleted from this object when present.
+     * @return {Object} The text search query for the extracted search text, or an
+     * empty object if the filter contains no search text.
+     */
+    extractTextSearchQuery(filter) {
+        if (filter.searchText) {
+            const searchQuery = this.textSearchQuery(filter.searchText);
+            delete filter.searchText;
+            return searchQuery;
+        }
+        return {};
+    }
+    /**
+     * Prepares a resource for the response by resolving the virtual fields of its
+     * model and flattening the Prisma `_count` aggregation into the individual
+     * relation count fields (i.e. `_count.posts` becomes `postsCount`).
+     *
+     * @param {Object} resource The resource object as returned by the database
+     * client.
+     * @return {Object} The same resource with the virtual fields resolved and, if a
+     * `_count` selection was present, with a count property per counted relation
+     * and the `_count` property removed.
+     */
+    projectResource(resource) {
+        const projectedResource = (0, virtual_util_1.projectVirtualFields)((0, delete_util_1.hideDeletedRelations)(resource, this._client.name), this._client.name);
+        if (!(0, common_1.isPlainObject)(projectedResource['_count'])) {
+            return projectedResource;
+        }
+        // Create new relation count properties on the resource object
+        for (const [key, count] of Object.entries(projectedResource['_count'])) {
+            projectedResource[(0, common_1.countFieldName)(key)] = count;
+        }
+        delete projectedResource['_count'];
+        return projectedResource;
+    }
+    /**
+     * Lists the conditions hiding the soft deleted resources from a query. It is
+     * empty for a model that deletes its records, so its query and the cursors
+     * bound to it stay the same.
+     *
+     * @return {Object[]} The `deletedAt: null` condition, or no condition.
+     */
+    liveFilters() {
+        const liveFilter = (0, model_util_1.liveRecordFilter)(this._client.name);
+        return Object.keys(liveFilter).length > 0 ? [liveFilter] : [];
+    }
+    /**
+     * Cleans up after records were deleted, once the deleting transaction
+     * commits: removes the stored files their fields do not keep, since the
+     * storage cannot take part in the transaction, and invalidates the cache of
+     * every model they belong to.
+     *
+     * @param {DeletedRecords} deleted The soft deleted and the removed records.
+     */
+    async cleanupDeletedRecords(deleted) {
+        const fileService = (0, core_1.inject)(file_service_1.FileService, false);
+        const groups = [
+            [true, deleted.soft],
+            [false, deleted.hard]
+        ];
+        for (const [softDeleted, records] of groups) {
+            for (const [modelName, ids] of Object.entries(records)) {
+                await fileService?.deleteResourcesFiles(modelName, ids, softDeleted);
+                await this._cacheService.invalidateCache(modelName, 'delete');
+            }
+        }
+    }
+    /**
+     * Prepares a write payload for the database by removing the virtual fields
+     * that have no column, filling in default values for the hidden required
+     * scalars of a create action, and recursively applying the same rules to the
+     * nested relation and file payloads. Unique key values, arrays of them and null
+     * values are left untouched, so the relation actions can still map them to the
+     * connect and disconnect operations.
+     *
+     * @param {'create'|'update'} action The write action the payload is sanitized
+     * for. Default values for the hidden required scalars are only applied on a
+     * create action.
+     * @param {Object} data The write payload to sanitize.
+     * @param {string} [resourceName] The name of the model the payload belongs to.
+     * Defaults to the model of this service and is set to the related model name
+     * when recursing into a nested relation or file payload.
+     * @return {Object} A shallow copy of the payload without the virtual fields,
+     * with the missing hidden required scalars defaulted, and with the nested
+     * payloads sanitized against their own models.
+     */
+    sanitizeData(action, data, resourceName) {
+        const sanitizedData = { ...data };
+        const resourceModel = (0, core_1.injectModel)(resourceName ?? this._client.name, false);
+        const relationsModel = resourceModel?.relationsModel;
+        const filesModel = resourceModel?.filesModel;
+        // Delete virtual fields from data object to avoid database errors
+        for (const fieldName of Object.keys(resourceModel?.config?.virtual ?? {})) {
+            delete sanitizedData[fieldName];
+        }
+        // Map default values for hidden scalars if a property is required without
+        // a provided default value, and scalar values are not set yet, this is only
+        // required for create actions
+        for (const [fieldName, scalar] of Object.entries(resourceModel?.config?.scalars ?? {})) {
+            if (action === 'create' &&
+                scalar.hidden &&
+                scalar.required !== false &&
+                scalar.default === undefined &&
+                sanitizedData[fieldName] === undefined) {
+                sanitizedData[fieldName] = (0, common_1.defaultScalarValue)(scalar);
+            }
+        }
+        // Recursively sanitize nested objects and arrays of objects
+        for (const key in sanitizedData) {
+            const value = sanitizedData[key];
+            const relationSchema = (0, common_1.extractSchemaProperties)(relationsModel, key);
+            const fileSchema = (0, common_1.extractSchemaProperties)(filesModel, key);
+            // Only nested resource payloads are sanitized. Unique key values, arrays
+            // of them and null values are left untouched, so the relation actions can
+            // still map them to connect and disconnect operations.
+            if ((0, common_1.isPlainObject)(value) || ((0, common_1.isArray)(value) && (0, common_1.isPlainObject)(value[0]))) {
+                const resourceName = (0, common_1.extractResourceName)(relationSchema ?? fileSchema);
+                if (resourceName) {
+                    sanitizedData[key] = (0, common_1.isArray)(value)
+                        ? value.map((item) => this.sanitizeData(action, item, resourceName))
+                        : this.sanitizeData(action, value, resourceName);
+                }
+            }
+        }
+        return sanitizedData;
+    }
+    /**
+     * Runs the operation of every item one after another in a single
+     * transaction, or in the current one, which rolls back on the first error.
+     *
+     * @internal
+     */
+    async bulk(items, operation, prepare) {
+        try {
+            return await this._db.client().$transaction(async () => {
+                await prepare?.();
+                const results = [];
+                for (const item of items) {
+                    const result = await operation(item);
+                    if (result !== undefined) {
+                        results.push(result);
+                    }
+                }
+                return results;
+            }, { timeout: resource_config_1.resourceConfig.BULK_TRANSACTION_TIMEOUT });
+        }
+        catch (e) {
+            // The errors of the items are translated already, which leaves the
+            // errors of the transaction itself, i.e. its timeout
+            throw this.databaseError(e);
+        }
+    }
+    /**
+     * Returns the ids of the given ones that exist and are not soft deleted,
+     * regardless of the read restrictions.
+     *
+     * @internal
+     */
+    async liveIds(ids) {
+        const records = await this._client.findMany({
+            where: { id: { in: ids }, ...(0, model_util_1.liveRecordFilter)(this._client.name) },
+            select: { id: true }
+        });
+        return records.map((record) => record.id);
+    }
+    /**
+     * The model delegate of the current transaction, or of the connection outside
+     * of one, resolved per call.
+     *
+     * @internal
+     */
+    get _client() {
+        return this._db.client()[this._modelKey];
+    }
+    /**
+     * Translates the error of a database operation, a record removed after it
+     * was read, i.e. by a concurrent delete, being one not found.
+     *
+     * @internal
+     */
+    databaseError(error, id) {
+        const translated = (0, database_error_1.toDatabaseError)(error, this._client.name);
+        if ((0, common_1.isAppweaverError)(translated) &&
+            translated.is(common_1.ErrorCode.DatabaseRecordNotFound)) {
+            return new common_1.ResourceError(common_1.ErrorCode.ResourceNotFound, `${this._client.name} not found`, { model: this._client.name, id }, { cause: translated.cause });
+        }
+        return translated;
+    }
+}
+exports.ResourceService = ResourceService;