@appweaver/core 1.4.0 → 1.5.0

package/resource/resource-service.d.ts

@@ -129,9 +129,9 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * 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 resource cache is invalidated
-     * and a resource event carrying both the previous and the current state is
-     * emitted after a successful update.
+     * `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
@@ -141,21 +141,31 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
      * out by the read restrictions, 403 if the access check denies the action, 400
      * if an inline relation payload is missing required fields or the relation
-     * does not accept new records, and 500 on a database error.
+     * does not accept new records, 409 if a live record references a soft
+     * deleted orphan through a restricting relation, and 500 on a database error.
      */
     update(id: ResourceId, data: Update): Promise<ReadOne>;
     /**
      * 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. The resource cache is invalidated and a
-     * resource event is emitted after a successful delete.
+     * 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.
      * @returns {Promise<Object>} The deleted resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
-     * out by the read restrictions, 403 if the access check denies the action, and
-     * 500 on a database error.
+     * out by the read restrictions, 403 if the access check denies it, 409 if a
+     * restricting relation still references a soft deleted resource, and 500 on a
+     * database error, a restricting relation of a removed resource included.
      */
     delete(id: ResourceId): Promise<ReadOne>;
     /**
@@ -252,6 +262,23 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * and the `_count` property removed.
      */
     private projectResource;
+    /**
+     * 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.
+     *
+     * @returns {Object[]} The `deletedAt: null` condition, or no condition.
+     */
+    private liveFilters;
+    /**
+     * 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.
+     */
+    private cleanupDeletedRecords;
     /**
      * Prepares a write payload for the database by removing the virtual fields
      * that have no column, filling in default values for the hidden required

package/resource/resource-service.js

@@ -6,6 +6,7 @@ const context_1 = require("../context");
 const utils_1 = require("../utils");
 const cache_1 = require("../cache");
 const errors_1 = require("../errors");
+const storage_1 = require("../storage");
 const utils_2 = require("./utils");
 class ResourceService {
     modelName;
@@ -61,7 +62,7 @@ class ResourceService {
         let resource;
         try {
             resource = await this._client.findFirst({
-                where: { id, ...restrictions },
+                where: { id, ...restrictions, ...(0, utils_1.liveRecordFilter)(this._client.name) },
                 include: includeRelations
             });
         }
@@ -120,7 +121,9 @@ class ResourceService {
         const restrictions = await this.readRestrictions('query', filter);
         const textSearch = this.extractTextSearchQuery(filter);
         const mappedFilter = (0, utils_2.mapQueryFilter)(filter, this._client.name);
-        const query = { AND: [mappedFilter, textSearch, restrictions] };
+        const query = {
+            AND: [mappedFilter, textSearch, restrictions, ...this.liveFilters()]
+        };
         const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'query');
         const orderBy = (0, utils_2.mapStableSortValues)(sort, this._client.name, 'query');
         // Binding to the mapped query rather than the filter also invalidates a
@@ -220,7 +223,9 @@ class ResourceService {
         const restrictions = await this.readRestrictions('aggregate', filter);
         const textSearch = this.extractTextSearchQuery(filter);
         const mappedFilter = (0, utils_2.mapQueryFilter)(filter, this._client.name);
-        const query = { AND: [mappedFilter, textSearch, restrictions] };
+        const query = {
+            AND: [mappedFilter, textSearch, restrictions, ...this.liveFilters()]
+        };
         const rangeQuery = (rangeFrom, rangeTo) => ({
             AND: [query, { [dateField]: { gte: rangeFrom, lt: rangeTo } }]
         });
@@ -290,6 +295,7 @@ class ResourceService {
         const sanitizedData = this.sanitizeData('create', createData);
         const connectRelations = (0, utils_2.mapRelationActions)(this._client.name, 'create', sanitizedData);
         const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'create');
+        await (0, utils_2.assertLiveRelationTargets)(this._db.client(), this._client.name, connectRelations);
         let resource;
         try {
             resource = await this._client.create({
@@ -315,9 +321,9 @@ class ResourceService {
      * 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 resource cache is invalidated
-     * and a resource event carrying both the previous and the current state is
-     * emitted after a successful update.
+     * `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
@@ -327,7 +333,8 @@ class ResourceService {
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
      * out by the read restrictions, 403 if the access check denies the action, 400
      * if an inline relation payload is missing required fields or the relation
-     * does not accept new records, and 500 on a database error.
+     * does not accept new records, 409 if a live record references a soft
+     * deleted orphan through a restricting relation, and 500 on a database error.
      */
     async update(id, data) {
         const readRestrictions = await this.readRestrictions('update', {
@@ -346,13 +353,18 @@ class ResourceService {
         const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'update');
         let updateResource;
         let resource;
+        let orphans;
         try {
-            [updateResource, resource] = await this._db
+            [updateResource, resource, orphans] = await this._db
                 .client()
                 .$transaction(async (tx) => {
                 const txModel = tx[this._client.name];
                 const current = await txModel.findFirst({
-                    where: { id, ...readRestrictions },
+                    where: {
+                        id,
+                        ...readRestrictions,
+                        ...(0, utils_1.liveRecordFilter)(this._client.name)
+                    },
                     include: includeRelations
                 });
                 if (!current || current.id !== id) {
@@ -363,12 +375,18 @@ class ResourceService {
                     throw new errors_1.HttpError(`${this._client.name} update action is forbidden`, 403);
                 }
                 const setRelations = (0, utils_2.mapRelationActions)(this._client.name, 'update', sanitizedData, current);
+                await (0, utils_2.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, utils_2.softDeleteData)();
+                const removed = await (0, utils_2.removeOrphans)(tx, this._client.name, setRelations, deleteData);
+                await (0, utils_2.retainDeletedFiles)(tx, removed, deleteData);
                 const updated = await txModel.update({
                     where: { id },
                     include: includeRelations,
                     data: { ...sanitizedData, ...setRelations }
                 });
-                return [current, updated];
+                return [current, updated, removed];
             });
         }
         catch (e) {
@@ -378,6 +396,7 @@ class ResourceService {
             throw new errors_1.HttpError(`${this._client.name} update error`, 500, e);
         }
         await this._cacheService.invalidateCache(this._client.name, 'update');
+        await this.cleanupDeletedRecords(orphans);
         this._events.emitResourceEvent(this._client.name, 'update', {
             previous: updateResource,
             current: resource
@@ -387,24 +406,43 @@ class ResourceService {
     /**
      * 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. The resource cache is invalidated and a
-     * resource event is emitted after a successful delete.
+     * 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.
      * @returns {Promise<Object>} The deleted resource with its virtual fields and
      * relation counts projected.
      * @throws {@link HttpError} 404 if the resource does not exist or is filtered
-     * out by the read restrictions, 403 if the access check denies the action, and
-     * 500 on a database error.
+     * out by the read restrictions, 403 if the access check denies it, 409 if a
+     * restricting relation still references a soft deleted resource, and 500 on a
+     * database error, a restricting relation of a removed resource included.
      */
     async delete(id) {
         const restrictions = await this.readRestrictions('delete', id);
+        const softDelete = (0, common_1.hasSoftDelete)((0, context_1.injectModel)(this._client.name).config);
+        const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'delete');
         let resource;
+        let deleted;
         try {
-            resource = await this._db.client().$transaction(async (tx) => {
+            [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 }
+                    where: {
+                        id,
+                        ...restrictions,
+                        ...(0, utils_1.liveRecordFilter)(this._client.name)
+                    },
+                    include: softDelete ? includeRelations : undefined
                 });
                 if (!current || current.id !== id) {
                     throw new errors_1.HttpError(`${this._client.name} data not found`, 404);
@@ -413,11 +451,28 @@ class ResourceService {
                 if (!access) {
                     throw new errors_1.HttpError(`${this._client.name} delete action is forbidden`, 403);
                 }
-                const includeRelations = (0, utils_2.mapRelationInclusions)(this._client.name, 'delete');
-                return await txModel.delete({
-                    where: { id },
-                    include: includeRelations
-                });
+                const data = (0, utils_2.softDeleteData)();
+                let result;
+                let records;
+                if (softDelete) {
+                    records = await (0, utils_2.softDeleteCascade)(tx, this._client.name, [id], data);
+                    const updated = await txModel.update({ where: { id }, data });
+                    result = { ...current, ...updated };
+                }
+                else {
+                    records = await (0, utils_2.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, utils_2.mergeAffectedRecords)(records, { [this._client.name]: [id] });
+                const removed = softDelete
+                    ? { soft: records, hard: {} }
+                    : { soft: {}, hard: records };
+                await (0, utils_2.retainDeletedFiles)(tx, removed, data);
+                return [result, removed];
             });
         }
         catch (e) {
@@ -426,7 +481,7 @@ class ResourceService {
             }
             throw new errors_1.HttpError(`${this._client.name} delete error`, 500, e);
         }
-        await this._cacheService.invalidateCache(this._client.name, 'delete');
+        await this.cleanupDeletedRecords(deleted);
         this._events.emitResourceEvent(this._client.name, 'delete', {
             current: resource
         });
@@ -541,7 +596,7 @@ class ResourceService {
      * and the `_count` property removed.
      */
     projectResource(resource) {
-        const projectedResource = (0, utils_1.projectVirtualFields)(resource, this._client.name);
+        const projectedResource = (0, utils_1.projectVirtualFields)((0, utils_2.hideDeletedRelations)(resource, this._client.name), this._client.name);
         if (!(0, common_1.isPlainObject)(projectedResource['_count'])) {
             return projectedResource;
         }
@@ -552,6 +607,38 @@ class ResourceService {
         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.
+     *
+     * @returns {Object[]} The `deletedAt: null` condition, or no condition.
+     */
+    liveFilters() {
+        const liveFilter = (0, utils_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, context_1.inject)(storage_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

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

@@ -0,0 +1,120 @@
+import { ResourceId } from '@appweaver/common';
+import type { RelationActions } from './relation-util';
+/** The records of every model affected by a delete, keyed by model name. */
+export type AffectedRecords = Record<string, ResourceId[]>;
+/** The records deleted by one action, split by how they were deleted. */
+export type DeletedRecords = {
+    /** Records marked with the soft delete columns */
+    soft: AffectedRecords;
+    /** Records removed from the database */
+    hard: AffectedRecords;
+};
+/** The columns marking a record as soft deleted. */
+export type SoftDeleteData = {
+    deletedAt: Date;
+    deletedById?: ResourceId | null;
+};
+/**
+ * Restricts a mapped relation filter to the related records that are not soft deleted, so a filter never matches
+ * through a deleted record, and a null check treats a deleted related record as missing.
+ *
+ * @param {*} condition - The mapped database condition of the relation field.
+ * @param {string} resourceName - The name of the related model.
+ * @param {boolean} isArrayType - Whether the relation is a list (to-many) relation.
+ * @return {*} The condition restricted to the live related records, or unchanged if the related model does not soft
+ * delete its records.
+ */
+export declare function liveRelationFilter(condition: any, resourceName: string, isArrayType: boolean): any;
+/**
+ * Builds the inclusion filter of a list relation, so only the related records that are not soft deleted are read.
+ *
+ * @param {string} [resourceName] - The name of the related model.
+ * @return {Object|undefined} The `where` clause of the inclusion, or undefined if the related model does not soft
+ * delete its records.
+ */
+export declare function liveInclusionFilter(resourceName?: string): {
+    where: Record<string, any>;
+} | undefined;
+/**
+ * Replaces the soft deleted records in the single relations of a resource with null, recursively. Unlike the list
+ * relations, a single relation cannot be filtered when it is read.
+ *
+ * @param {Object} resource - The resource as returned by the database client.
+ * @param {string} resourceName - The name of the model describing the resource.
+ * @return {Object} A copy of the resource without the soft deleted related records, or the resource itself if it
+ * holds no relations.
+ */
+export declare function hideDeletedRelations<T>(resource: T, resourceName: string): T;
+/**
+ * Builds the column values marking a record as soft deleted now by the current user, who is only recorded when the
+ * application defines an auth model.
+ *
+ * @return {SoftDeleteData} The soft delete column values.
+ */
+export declare function softDeleteData(): SoftDeleteData;
+/**
+ * Mirrors the referential actions of a database delete for soft deleted records: cascading records are soft deleted
+ * with the same column values, level by level, a restricting relation aborts the delete, and references set to null on
+ * delete are kept for a manual restore. The records themselves are not updated.
+ *
+ * @param {Object} tx - The transaction client the delete runs in.
+ * @param {string} resourceName - The name of the model of the deleted records.
+ * @param {ResourceId[]} ids - The ids of the deleted records.
+ * @param {SoftDeleteData} data - The soft delete column values applied to the cascaded records.
+ * @return {Promise<AffectedRecords>} The ids of the soft deleted records per model, excluding the records themselves.
+ * @throws {HttpError} 409 if a live record references a deleted record through a restricting relation.
+ */
+export declare function softDeleteCascade(tx: any, resourceName: string, ids: ResourceId[], data: SoftDeleteData): Promise<AffectedRecords>;
+/**
+ * Collects the records the database cascade removes together with deleted records, so their files and caches can be
+ * cleaned up once the delete commits.
+ *
+ * @param {Object} tx - The transaction client the delete runs in.
+ * @param {string} resourceName - The name of the model of the deleted records.
+ * @param {ResourceId[]} ids - The ids of the deleted records.
+ * @return {Promise<AffectedRecords>} The ids of the cascaded records per model, excluding the records themselves.
+ */
+export declare function cascadedRecords(tx: any, resourceName: string, ids: ResourceId[]): Promise<AffectedRecords>;
+/**
+ * Removes the orphans an update maps to a nested `delete` action (`orphanRemoval`). Orphans of a soft deleted model are
+ * soft deleted with their cascade and keep their references, so their `delete` action is dropped; the others are left
+ * to the `delete` action, collecting the records its cascade removes.
+ *
+ * @param {Object} tx - The transaction client the update runs in.
+ * @param {string} resourceName - The name of the model the relation actions belong to.
+ * @param {RelationActions} relationActions - The mapped relation write actions, from which the nested `delete` actions
+ * of the soft deleted orphans are removed.
+ * @param {SoftDeleteData} data - The soft delete column values applied to the soft deleted orphans.
+ * @return {Promise<DeletedRecords>} The ids of the soft deleted and the removed records per model.
+ * @throws {HttpError} 409 if a live record references a soft deleted orphan through a restricting relation.
+ */
+export declare function removeOrphans(tx: any, resourceName: string, relationActions: RelationActions, data: SoftDeleteData): Promise<DeletedRecords>;
+/**
+ * Marks the file rows of the files the deleted records keep (`onResourceDeleted` / `onResourceSoftDeleted: 'keep'`) as
+ * deleted with the values of the delete, so they stay stored, e.g. for audit, but are no longer served.
+ *
+ * @param {Object} tx - The transaction client the delete runs in.
+ * @param {DeletedRecords} deleted - The soft deleted and the removed records.
+ * @param {SoftDeleteData} data - The soft delete column values of the delete.
+ * @return {Promise<void>} Resolves when the kept files are marked deleted.
+ */
+export declare function retainDeletedFiles(tx: any, deleted: DeletedRecords, data: SoftDeleteData): Promise<void>;
+/**
+ * Merges the affected records of several deletes into the target, keeping the ids of every model unique.
+ *
+ * @param {AffectedRecords} target - The affected records merged into.
+ * @param {AffectedRecords[]} sources - The affected records to add.
+ * @return {AffectedRecords} The target holding the ids of every source.
+ */
+export declare function mergeAffectedRecords(target: AffectedRecords, ...sources: AffectedRecords[]): AffectedRecords;
+/**
+ * Rejects the relation write actions pointing at soft deleted records, which the database would otherwise connect or
+ * update, since it does not know the record is deleted.
+ *
+ * @param {Object} client - The database client, or the transaction client the write runs in.
+ * @param {string} resourceName - The name of the model the relation actions belong to.
+ * @param {RelationActions} relationActions - The mapped relation write actions.
+ * @return {Promise<void>} Resolves when no action points at a soft deleted record.
+ * @throws {HttpError} 400 if a connect, update or connect-or-create action matches a soft deleted record.
+ */
+export declare function assertLiveRelationTargets(client: any, resourceName: string, relationActions: RelationActions): Promise<void>;