@appweaver/core 1.1.5 → 1.2.0

package/resource/resource-service.d.ts

@@ -1,36 +1,179 @@
-import { ActionType, AggregateResponse, AggregateSelect, IResourceService, QueryResponse, Resource, ResourceClient, ResourceData } from '@appweaver/common';
-export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Resource, Create = ResourceData<Resource>, Update = Partial<ResourceData<Resource>>, Query = any> implements IResourceService<ReadOne, ReadMany, Create, Update, Query> {
+import { ActionType, AggregateResponse, AggregateSelect, IResourceService, QueryFilter, QueryResponse, QuerySort, Resource, ResourceClient, ResourceData } from '@appweaver/common';
+export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Resource, Create = ResourceData<Resource>, Update = Partial<ResourceData<Resource>>, Query = QueryFilter<ReadOne>> implements IResourceService<ReadOne, ReadMany, Create, Update, Query> {
     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.
+     *
+     * @returns {ResourceClient} The resource client of the model this service was
+     * created for.
+     */
     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 {number} id The id of the resource to find.
+     * @returns {Promise<Object>} The found 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 it, and 500 on
+     * a database error.
+     */
     find(id: number): Promise<ReadOne>;
-    query(filter?: Query, page?: number, size?: number, sort?: string): Promise<QueryResponse<ReadMany>>;
+    /**
+     * 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 {Object} [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.
+     * @param {number} [page] The one-based page number of results to return.
+     * @param {number} [size] The maximum number of results per page.
+     * @param {QuerySort} [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' } }`).
+     * @returns {Promise<QueryResponse<Object>>} The paged query response containing
+     * the returned resources, the count of the returned items and the total count
+     * of matching resources.
+     * @throws {@link HttpError} 400 if the sort input names a field that cannot be
+     * sorted by, and 500 on a database error.
+     */
+    query(filter?: Query, page?: number, size?: number, sort?: QuerySort<ReadMany>): Promise<QueryResponse<ReadMany>>;
+    /**
+     * 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 {Object} [filter] The query filter object, mapped the same way as in
+     * {@link ResourceService.query}.
+     * @param {AggregateSelect<Object>} 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.
+     * @param {string} [dateField] The date field the range is applied on.
+     * @param {string} [from] The ISO date string of the range start. Defaults to
+     * seven days before the range end.
+     * @param {string} [to] The ISO date string of the range end. Defaults to the
+     * current date and time.
+     * @param {number} [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).
+     * @param {boolean} [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.
+     * @returns {Promise<AggregateResponse<Object>>} The aggregation response with
+     * the overall total and one result per period, each labeled with the median
+     * date of its period.
+     * @throws {@link HttpError} 400 if the selection is empty or names a field or
+     * operator that cannot be aggregated, and 500 on a database error.
+     */
     aggregate(filter: Query | undefined, select: AggregateSelect<ReadOne>, dateField?: string, from?: string, to?: string, step?: number, safeIncrement?: boolean): Promise<AggregateResponse<ReadOne>>;
+    /**
+     * 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.
+     * @returns {Promise<Object>} The created resource with its virtual fields and
+     * relation counts projected.
+     * @throws {@link HttpError} 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.
+     */
     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 resource cache is invalidated
+     * and a resource event carrying both the previous and the current state is
+     * emitted after a successful update.
+     *
+     * @param {number} 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.
+     * @returns {Promise<Object>} The updated 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, 400
+     * if an inline relation payload is missing required fields or the relation
+     * does not accept new records, and 500 on a database error.
+     */
     update(id: number, 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.
+     *
+     * @param {number} 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.
+     */
     delete(id: number): Promise<ReadOne>;
     /**
      * 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 current action by throwing
-     * an error, recommended is {@link HttpError } with appropriate HTTP error
-     * code.
+     * and modifications. This method can also cancel the current action by
+     * throwing an error, recommended is {@link HttpError } with appropriate HTTP
+     * error code.
      *
-     * @param action The called action method on this service (find, query,
-     * aggregate, update, or delete)
-     * @param 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:
+     * @param {ActionType} action The called action method on this service (find,
+     * query, aggregate, update, or delete)
+     * @param {Object|number} 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 The filter containing additional query restrictions.
+     * @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<Query>;
+    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
@@ -40,13 +183,15 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * current action by throwing an error, with the recommended type being
      * {@link HttpError} with the appropriate HTTP error code.
      *
-     * @param action The called action method on this service (create or update)
-     * @param data The passed data to the called function, which should be an
-     * object representing the resource data to be created or updated. For
+     * @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 A partial object containing additional data restrictions to be
-     * applied, or an empty object if no restrictions are necessary.
+     * @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>>;
     /**
@@ -55,10 +200,11 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      *  a currently authenticated user or other logic, this method should return
      * false. Otherwise, it returns true and continues with the request execution.
      *
-     * @param action The called action method on this service (find, query,
-     * aggregate, create, update, or delete)
-     * @param resource The resource object that is being check for access.
-     * @returns True if the access for resource is granted, false otherwise.
+     * @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.
+     * @returns {Promise<boolean>} True if the access for resource is granted, false
+     * otherwise.
      */
     protected checkAccess(action: ActionType, resource: ReadOne): Promise<boolean>;
     /**
@@ -67,22 +213,54 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
      * search text into a format suitable for text search functionality, returning
      * a query object that can be used to filter results.
      *
-     * @param searchText The text string used for searching resources.
-     * @returns A query object that represents the conditions for the text
-     * search operation. This will be used by the database query methods to
-     * retrieve matching resources.
+     * @param {string} searchText The text string used for searching resources.
+     * @returns {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.
+     * @returns {Object} The text search query for the extracted search text, or an
+     * empty object if the filter contains no search text.
      */
-    protected textSearchQuery(searchText: string): Query;
     private extractTextSearchQuery;
-    private mapSortValues;
-    private mapAggregationValues;
-    private makeAggregationIterator;
+    /**
+     * 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.
+     * @returns {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;
+    /**
+     * 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.
+     * @returns {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;
-    private mapQueryFilter;
-    private mapRelationInclusions;
-    private buildNestedInclusion;
-    private shouldIncludeRelation;
-    private mapRelationActions;
-    private createdByConnect;
 }