@opra/sqb 1.26.3 → 1.27.0

package/sqb-entity-service.d.ts

@@ -6,17 +6,41 @@ import { type vg } from 'valgen';
 import { SQBAdapter } from './sqb-adapter.js';
 import { SqbServiceBase } from './sqb-service-base.js';
 /**
- * @namespace SqbEntityService
+ * Namespace containing types and options for SqbEntityService.
  */
 export declare namespace SqbEntityService {
+    /**
+     * Configuration options for SqbEntityService.
+     */
     interface Options extends SqbServiceBase.Options {
+        /**
+         * The name of the resource managed by this service.
+         */
         resourceName?: SqbEntityService<any>['resourceName'];
+        /**
+         * Optional error handler.
+         */
         onError?: SqbEntityService<any>['onError'];
+        /**
+         * Optional common filter applied to all read/write operations.
+         */
         commonFilter?: SqbEntityService<any>['commonFilter'];
+        /**
+         * Optional interceptor for the service operations.
+         */
         interceptor?: SqbEntityService<any>['interceptor'];
+        /**
+         * Optional scope for the service.
+         */
         scope?: SqbEntityService<any>['scope'];
     }
+    /**
+     * Represents the CRUD operation types.
+     */
     type CrudOp = 'create' | 'read' | 'update' | 'delete';
+    /**
+     * Information about the command being executed.
+     */
     interface CommandInfo {
         crud: SqbEntityService.CrudOp;
         method: string;
@@ -25,77 +49,35 @@ export declare namespace SqbEntityService {
         input?: Record<string, any>;
         options?: Record<string, any>;
     }
-    type CommonFilter = SQBAdapter.FilterInput | ((args: SqbEntityService.CommandInfo, _this: SqbEntityService<any>) => SQBAdapter.FilterInput | Promise<SQBAdapter.FilterInput> | undefined);
     /**
-     * Represents options for "create" operation
-     *
-     * @interface
+     * Type definition for a common filter.
      */
+    type CommonFilter = SQBAdapter.FilterInput | ((args: SqbEntityService.CommandInfo, _this: SqbEntityService<any>) => SQBAdapter.FilterInput | Promise<SQBAdapter.FilterInput> | undefined);
     interface CreateOptions extends Repository.CreateOptions {
     }
-    /**
-     * Represents options for "count" operation
-     *
-     * @interface
-     */
     interface CountOptions extends StrictOmit<Repository.CountOptions, 'filter'> {
         filter?: Repository.CountOptions['filter'] | string;
     }
-    /**
-     * Represents options for "delete" operation
-     *
-     * @interface
-     */
     interface DeleteOptions extends StrictOmit<Repository.DeleteOptions, 'filter'> {
         filter?: Repository.DeleteOptions['filter'] | string;
     }
-    /**
-     * Represents options for "deleteMany" operation
-     *
-     * @interface
-     */
     interface DeleteManyOptions extends StrictOmit<Repository.DeleteManyOptions, 'filter'> {
         filter?: Repository.DeleteManyOptions['filter'] | string;
     }
-    /**
-     * Represents options for "exists" operation
-     *
-     * @interface
-     */
     interface ExistsOptions extends StrictOmit<Repository.ExistsOptions, 'filter'> {
         filter?: Repository.ExistsOptions['filter'] | string;
     }
-    /**
-     * Represents options for "findOne" operation
-     *
-     * @interface
-     */
     interface FindOneOptions extends StrictOmit<Repository.FindOneOptions, 'filter' | 'offset'> {
         filter?: Repository.FindOneOptions['filter'] | string;
         skip?: number;
     }
-    /**
-     * Represents options for "findMany" operation
-     *
-     * @interface
-     */
     interface FindManyOptions extends StrictOmit<Repository.FindManyOptions, 'filter' | 'offset'> {
         filter?: Repository.FindManyOptions['filter'] | string;
         skip?: number;
     }
-    /**
-     * Represents options for "update" operation
-     *
-     * @interface
-     */
     interface UpdateOneOptions extends StrictOmit<Repository.UpdateOptions, 'filter'> {
         filter?: Repository.UpdateOptions['filter'] | string;
     }
-    /**
-     * Represents options for "updateMany" operation
-     *
-     * @interface
-     */
     interface UpdateManyOptions extends StrictOmit<Repository.UpdateManyOptions, 'filter'> {
         filter?: Repository.UpdateManyOptions['filter'] | string;
     }
@@ -141,18 +123,19 @@ export declare namespace SqbEntityService {
 }
 export interface SqbEntityService {
     /**
-     * Interceptor function for handling callback execution with provided arguments.
-     * @type Function
-     * @param next - The callback function to be intercepted.
-     * @param {SqbEntityService.CommandInfo} command - The arguments object containing the following properties:
-     * @param _this - The reference to the current object.
-     * @returns - The promise that resolves to the result of the callback execution.
+     * Optional interceptor that wraps every command execution.
+     *
+     * @param next - Calls the next interceptor or the actual command handler.
+     * @param command - Metadata describing the current operation.
+     * @param _this - Reference to the service instance.
+     * @returns The result of the command execution.
      */
     interceptor?(next: () => any, command: SqbEntityService.CommandInfo, _this: any): Promise<any>;
 }
 /**
- * @class SqbEntityService
- * @template T - The data type class type of the resource
+ * Base service providing CRUD operations over an SQB entity.
+ *
+ * @typeParam T - The entity type managed by this service
  */
 export declare class SqbEntityService<T extends object = object> extends SqbServiceBase {
     protected _dataTypeScope?: string;
@@ -163,278 +146,274 @@ export declare class SqbEntityService<T extends object = object> extends SqbServ
     protected _inputCodecs: Record<string, vg.isObject.Validator<T>>;
     protected _outputCodecs: Record<string, vg.isObject.Validator<T>>;
     /**
-     * Defines comma-delimited scopes for the api document
+     * Comma-delimited scopes used to filter the API document.
      */
     scope?: string;
     /**
-     * Represents the name of a resource.
-     * @type {string}
+     * Override for the resource name exposed in error messages and API metadata.
+     * Accepts a static string or a function that returns one.
      */
     resourceName?: string | ((_this: this) => string);
     /**
-     * Represents a common filter function for a service.
-     *
-     * @type {SqbEntityService.Filter | Function}
+     * Filter(s) automatically applied to every query for this service.
+     * Useful for multi-tenant isolation or other cross-cutting constraints.
      */
     commonFilter?: SqbEntityService.CommonFilter | SqbEntityService.CommonFilter[];
     /**
-     * Callback function for handling errors.
+     * Called whenever a command throws. Useful for logging or transforming errors.
      *
-     * @param {unknown} error - The error object.
-     * @param {SqbEntityService} _this - The context object.
+     * @param error - The thrown error.
+     * @param command - The service command during which the error was thrown.
+     * @param _this - The service instance.
      */
-    onError?: (error: unknown, _this: any) => void | Promise<void>;
+    onError?: (error: unknown, command: SqbEntityService.CommandInfo, _this: any) => void | Promise<void>;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param dataType - The data type of the returning results
-     * @param [options] - The options for the service.
-     * @constructor
+     * @param dataType - The entity class or its registered name.
+     * @param options - Options for the service.
      */
     constructor(dataType: Type<T> | string, options?: SqbEntityService.Options);
     /**
-     * Retrieves the OPRA data type
+     * Returns the resolved OPRA `ComplexType` for this service's entity.
      *
-     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     * @throws If the data type is not registered as a `ComplexType`.
      */
     get dataType(): ComplexType;
     /**
-     * Retrieves the Class of the data type
+     * Returns the constructor class of the entity data type.
      *
-     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     * @throws If the data type is not registered as a `ComplexType`.
      */
     get dataTypeClass(): Type;
     /**
-     * Retrieves the SQB entity metadata object
+     * Returns the SQB `EntityMetadata` for the entity class.
      *
-     * @throws {TypeError} If metadata is not available
+     * @throws If the class is not decorated with `@Entity()`.
      */
     get entityMetadata(): EntityMetadata;
     for<C extends ExecutionContext, P extends Partial<this>>(context: C | ServiceBase, overwriteProperties?: Nullish<P>, overwriteContext?: Partial<C>): this & Required<P>;
     /**
-     * Retrieves the resource name.
+     * Returns the resource name used in error messages and API metadata.
      *
-     * @returns {string} The resource name.
-     * @throws {Error} If the collection name is not defined.
+     * @throws If neither `resourceName` nor the data type name is available.
      */
     getResourceName(): string;
     /**
-     * Retrieves the codec for the specified operation.
+     * Returns the input codec for the given operation (e.g. `'create'`, `'update'`).
      *
-     * @param operation - The operation to retrieve the encoder for. Valid values are 'create' and 'update'.
+     * @param operation - The operation name.
      */
     getInputCodec(operation: string): vg.isObject.Validator<T>;
     /**
-     * Retrieves the codec.
+     * Returns the output codec for the given operation.
+     *
+     * @param operation - The operation name.
      */
     getOutputCodec(operation: string): vg.isObject.Validator<T>;
     /**
-     * Insert a new record into database
+     * Inserts a new record into the database and returns the created document.
      *
-     * @param command
-     * @returns - A promise that resolves to the created resource
+     * @param command - The create command.
+     * @returns The created document.
      * @protected
      */
     protected _create(command: SqbEntityService.CreateCommand<T>): Promise<PartialDTO<T>>;
     /**
-     * Insert a new record into database
+     * Inserts a new record into the database without returning it.
      *
-     * @param command
-     * @returns - A promise that resolves to the created resource
+     * @param command - The create command.
      * @protected
      */
     protected _createOnly(command: SqbEntityService.CreateCommand<T>): Promise<any>;
     /**
-     * Returns the count of records based on the provided options
+     * Returns the count of records matching the command options.
      *
-     * @param command
-     * @return - A promise that resolves to the count of records
+     * @param command - The count command.
      * @protected
      */
     protected _count(command: SqbEntityService.CountCommand): Promise<number>;
     /**
-     * Deletes a record from the collection.
+     * Deletes the record identified by `command.documentId`.
      *
-     * @param command
-     * @return - A Promise that resolves to the number of documents deleted.
+     * @param command - The delete command.
+     * @returns The number of records deleted.
      * @protected
      */
     protected _delete(command: SqbEntityService.DeleteOneCommand): Promise<number>;
     /**
-     * Deletes multiple documents from the collection that meet the specified filter criteria.
+     * Deletes all records matching the command filter.
      *
-     * @param command
-     * @return - A promise that resolves to the number of documents deleted.
+     * @param command - The deleteMany command.
+     * @returns The number of records deleted.
      * @protected
      */
     protected _deleteMany(command: SqbEntityService.DeleteManyCommand): Promise<number>;
     /**
-     * Checks if a record with the given id exists.
+     * Checks whether the record identified by `command.documentId` exists.
      *
-     * @param command
+     * @param command - The exists command.
      * @protected
      */
     protected _exists(command: SqbEntityService.ExistsCommand): Promise<boolean>;
     /**
-     * Checks if a record with the given arguments exists.
+     * Checks whether any record matching the command filter exists.
      *
-     * @param command
-     * @return - A Promise that resolves to a boolean indicating whether the record exists or not.
+     * @param command - The existsOne command.
      * @protected
      */
     protected _existsOne(command: SqbEntityService.ExistsCommand): Promise<boolean>;
     /**
-     * Finds a record by ID.
+     * Finds the record identified by `command.documentId`.
      *
-     * @param command
-     * @return - A promise resolving to the found document, or undefined if not found.
+     * @param command - The findById command.
+     * @returns The found record, or `undefined` if not found.
      * @protected
      */
     protected _findById(command: SqbEntityService.FindOneCommand): Promise<PartialDTO<T> | undefined>;
     /**
-     * Finds a record in the collection that matches the specified options.
+     * Finds the first record matching the command filter.
      *
-     * @param command
-     * @return - A promise that resolves with the found document or undefined if no document is found.
+     * @param command - The findOne command.
+     * @returns The found record, or `undefined` if not found.
      * @protected
      */
     protected _findOne(command: SqbEntityService.FindOneCommand): Promise<PartialDTO<T> | undefined>;
     /**
-     * Finds multiple records in collection.
+     * Finds all records matching the command filter.
      *
-     * @param command
-     * @return - A Promise that resolves to an array of partial outputs of type T.
+     * @param command - The findMany command.
+     * @returns An array of matching records.
      * @protected
      */
     protected _findMany(command: SqbEntityService.FindManyCommand): Promise<PartialDTO<T>[]>;
     /**
-     * Updates a record with the given id in the collection.
+     * Updates the record identified by `command.documentId` and returns it.
      *
-     * @param command
-     * @returns  A promise that resolves to the updated document or undefined if the document was not found.
+     * @param command - The update command.
+     * @returns The updated record, or `undefined` if not found.
      * @protected
      */
     protected _update(command: SqbEntityService.UpdateOneCommand<T>): Promise<PartialDTO<T> | undefined>;
     /**
-     * Updates a record in the collection with the specified ID and returns updated record count
+     * Updates the record identified by `command.documentId` without returning it.
      *
-     * @param command
-     * @returns - A promise that resolves to the number of documents modified.
+     * @param command - The updateOnly command.
+     * @returns The number of records modified.
      * @protected
      */
     protected _updateOnly(command: SqbEntityService.UpdateOneCommand<T>): Promise<number>;
     /**
-     * Updates multiple records in the collection based on the specified input and options.
+     * Updates all records matching the command filter.
      *
-     * @param command
-     * @return - A promise that resolves to the number of documents matched and modified.
+     * @param command - The updateMany command.
+     * @returns The number of records modified.
      * @protected
      */
     protected _updateMany(command: SqbEntityService.UpdateOneCommand<T>): Promise<number>;
     /**
-     * Acquires a connection and performs Repository.create operation
+     * Acquires a connection and performs `Repository.create`.
      *
-     * @param input - The document to insert
-     * @param options - Optional settings for the command
+     * @param input - The document to insert.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbCreate(input: PartialDTO<T>, options?: Repository.CreateOptions): Promise<PartialDTO<T>>;
     /**
-     * Acquires a connection and performs Repository.count operation
+     * Acquires a connection and performs `Repository.count`.
      *
-     * @param options - The options for counting documents.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbCount(options?: Repository.CountOptions): Promise<number>;
     /**
-     * Acquires a connection and performs Repository.delete operation
+     * Acquires a connection and performs `Repository.delete`.
      *
-     * @param id - Value of the key field used to select the record
-     * @param options - Optional settings for the command
+     * @param id - The key field value identifying the record.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbDelete(id: SQBAdapter.IdOrIds, options?: Repository.DeleteOptions): Promise<number>;
     /**
-     * Acquires a connection and performs Repository.deleteMany operation
+     * Acquires a connection and performs `Repository.deleteMany`.
      *
-     * @param options - Optional settings for the command
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbDeleteMany(options?: Repository.DeleteManyOptions): Promise<number>;
     /**
-     * Acquires a connection and performs Repository.exists operation
+     * Acquires a connection and performs `Repository.exists`.
      *
-     * @param id - Value of the key field used to select the record
-     * @param options - Optional settings for the command
+     * @param id - The key field value identifying the record.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbExists(id: SQBAdapter.IdOrIds, options?: Repository.ExistsOptions): Promise<boolean>;
     /**
-     * Acquires a connection and performs Repository.existsOne operation
+     * Acquires a connection and performs `Repository.existsOne`.
      *
-     * @param options - Optional settings for the command
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbExistsOne(options?: Repository.ExistsOptions): Promise<boolean>;
     /**
-     * Acquires a connection and performs Repository.findById operation
+     * Acquires a connection and performs `Repository.findById`.
      *
-     * @param id - Value of the key field used to select the record
-     * @param options - Optional settings for the command
+     * @param id - The key field value identifying the record.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbFindById(id: SQBAdapter.IdOrIds, options?: Repository.FindOptions): Promise<PartialDTO<T> | undefined>;
     /**
-     * Acquires a connection and performs Repository.findOne operation
+     * Acquires a connection and performs `Repository.findOne`.
      *
-     * @param options - Optional settings for the command
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbFindOne(options?: StrictOmit<Repository.FindOneOptions, 'offset'> & {
         skip?: number;
     }): Promise<PartialDTO<T> | undefined>;
     /**
-     * Acquires a connection and performs Repository.findMany operation
+     * Acquires a connection and performs `Repository.findMany`.
      *
-     * @param options - Optional settings for the command
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbFindMany(options?: StrictOmit<Repository.FindManyOptions, 'offset'> & {
         skip?: number;
     }): Promise<PartialDTO<T>[]>;
     /**
-     * Acquires a connection and performs Repository.update operation
+     * Acquires a connection and performs `Repository.update`.
      *
-     * @param id - Value of the key field used to select the record
-     * @param data - The update values to be applied to the document
-     * @param options - Optional settings for the command
+     * @param id - The key field value identifying the record.
+     * @param data - The update values.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbUpdate(id: SQBAdapter.IdOrIds, data: PatchDTO<T>, options?: Repository.UpdateOptions): Promise<PartialDTO<T> | undefined>;
     /**
-     * Acquires a connection and performs Repository.updateOnly operation
+     * Acquires a connection and performs `Repository.updateOnly`.
      *
-     * @param id - Value of the key field used to select the record
-     * @param data - The update values to be applied to the document
-     * @param options - Optional settings for the command
+     * @param id - The key field value identifying the record.
+     * @param data - The update values.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbUpdateOnly(id: SQBAdapter.IdOrIds, data: PatchDTO<T>, options?: Repository.UpdateOptions): Promise<number>;
     /**
-     * Acquires a connection and performs Repository.updateMany operation
+     * Acquires a connection and performs `Repository.updateMany`.
      *
-     * @param data - The update values to be applied to the document
-     * @param options - Optional settings for the command
+     * @param data - The update values.
+     * @param options - Optional settings.
      * @protected
      */
     protected _dbUpdateMany(data: PatchDTO<T>, options?: Repository.UpdateManyOptions): Promise<number>;
     /**
-     * Retrieves the common filter used for querying documents.
-     * This method is mostly used for security issues like securing multi-tenant applications.
+     * Builds the common filter for the given command.
+     * Used primarily for multi-tenant isolation and similar cross-cutting concerns.
      *
      * @protected
-     * @returns {FilterInput | Promise<FilterInput> | undefined} The common filter or a Promise
-     * that resolves to the common filter, or undefined if not available.
+     * @returns The resolved filter input, or `undefined` if none is configured.
      */
     protected _getCommonFilter(command: SqbEntityService.CommandInfo): SQBAdapter.FilterInput | Promise<SQBAdapter.FilterInput> | undefined;
     protected _executeCommand(command: SqbEntityService.CommandInfo, commandFn: () => any): Promise<any>;