@appweaver/data 0.0.0-stage → 2.0.1

package/resource/resource-service.d.ts

@@ -0,0 +1,462 @@
+import { ActionType, AggregateOptions, AggregateResponse, AggregateSelect, AggregateSelected, BulkItem, IResourceService, QueryFilter, QueryOptions, QueryResponse, QuerySort, Resource, ResourceId, ResourceClient, ResourceData } from '@appweaver/common';
+export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Resource, Create = ResourceData<Resource>, Update = Partial<ResourceData<Resource>>, Query = QueryFilter<ReadOne>, Replace = Create> implements IResourceService<ReadOne, ReadMany, Create, Update, Query, Replace> {
+    readonly modelName: string;
+    /**
+     * 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: string);
+    /**
+     * 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(): ResourceClient;
+    /**
+     * 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.
+     */
+    find(id: ResourceId): Promise<ReadOne>;
+    /**
+     * 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.
+     */
+    query(options?: QueryOptions<ReadMany, Query>): Promise<QueryResponse<ReadMany>>;
+    /**
+     * 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.
+     */
+    single(filter?: Query, sort?: QuerySort<ReadOne>): Promise<ReadOne | null>;
+    /**
+     * 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.
+     */
+    count(filter?: Query): Promise<number>;
+    /**
+     * 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.
+     */
+    exists(filter?: Query): Promise<boolean>;
+    /**
+     * 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.
+     */
+    aggregate<S extends AggregateSelect<ReadOne>>(options: AggregateOptions<ReadOne, S, Query>): Promise<AggregateResponse<AggregateSelected<ReadOne, S>>>;
+    /**
+     * 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`.
+     */
+    create(data: Create): Promise<ReadOne>;
+    /**
+     * 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`.
+     */
+    update(id: ResourceId, data: Update): Promise<ReadOne>;
+    /**
+     * 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}.
+     */
+    replace(id: ResourceId, data: Replace): 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.
+     *
+     * 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.
+     */
+    delete(id: ResourceId): Promise<ReadOne>;
+    /**
+     * 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}.
+     */
+    bulkCreate(items: Create[]): Promise<ReadOne[]>;
+    /**
+     * 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}.
+     */
+    bulkUpdate(items: BulkItem<Update>[]): Promise<ReadOne[]>;
+    /**
+     * 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}.
+     */
+    bulkReplace(items: BulkItem<Replace>[]): Promise<ReadOne[]>;
+    /**
+     * 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}.
+     */
+    bulkDelete(ids: ResourceId[]): Promise<ReadOne[]>;
+    /**
+     * 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.
+     */
+    protected updateWithPrevious(id: ResourceId, data: Update): Promise<{
+        previous: ReadOne;
+        current: ReadOne;
+    }>;
+    /**
+     * 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.
+     */
+    protected replacementData(data: Replace): Update;
+    /**
+     * 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.
+     */
+    protected readRestrictions(action: Exclude<ActionType, 'create'>, data: any): Promise<any>;
+    /**
+     * 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.
+     */
+    protected writeRestrictions(action: 'create' | 'update', data: any): Promise<Partial<Create & Update>>;
+    /**
+     * 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.
+     */
+    protected checkAccess(action: ActionType, resource: ReadOne): Promise<boolean>;
+    /**
+     * 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.
+     */
+    protected textSearchQuery(searchText: string): any;
+    /**
+     * 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.
+     */
+    private extractTextSearchQuery;
+    /**
+     * 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.
+     */
+    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.
+     *
+     * @return {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
+     * 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.
+     */
+    private sanitizeData;
+}