@opra/sqb 1.26.3 → 1.27.0

package/sqb-entity-service.js

@@ -1,12 +1,13 @@
 import { InternalServerError } from '@opra/common';
-import { op } from '@sqb/builder';
+import { sql } from '@sqb/builder';
 import { EntityMetadata } from '@sqb/connect';
 import { isNotNullish } from 'valgen';
 import { SQBAdapter } from './sqb-adapter.js';
 import { SqbServiceBase } from './sqb-service-base.js';
 /**
- * @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 class SqbEntityService extends SqbServiceBase {
     _dataTypeScope;
@@ -17,33 +18,32 @@ export class SqbEntityService extends SqbServiceBase {
     _inputCodecs = {};
     _outputCodecs = {};
     /**
-     * Defines comma-delimited scopes for the api document
+     * Comma-delimited scopes used to filter the API document.
      */
     scope;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * 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, options) {
         super(options);
@@ -53,9 +53,9 @@ export class SqbEntityService extends SqbServiceBase {
         this.interceptor = options?.interceptor;
     }
     /**
-     * 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() {
         if (this._dataType && this._dataTypeScope !== this.scope)
@@ -66,9 +66,9 @@ export class SqbEntityService extends SqbServiceBase {
         return this._dataType;
     }
     /**
-     * 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() {
         if (!this._dataTypeClass)
@@ -76,9 +76,9 @@ export class SqbEntityService extends SqbServiceBase {
         return this._dataTypeClass;
     }
     /**
-     * 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() {
         if (!this._entityMetadata) {
@@ -104,10 +104,9 @@ export class SqbEntityService extends SqbServiceBase {
         return super.for(context, overwriteProperties, overwriteContext);
     }
     /**
-     * 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() {
         const out = typeof this.resourceName === 'function'
@@ -118,11 +117,12 @@ export class SqbEntityService extends SqbServiceBase {
         throw new Error('resourceName is not defined');
     }
     /**
-     * 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) {
+        const dataType = this.dataType;
         const cacheKey = operation + (this._dataTypeScope ? ':' + this._dataTypeScope : '');
         let validator = this._inputCodecs[cacheKey];
         if (validator)
@@ -133,15 +133,17 @@ export class SqbEntityService extends SqbServiceBase {
         };
         if (operation === 'update')
             options.partial = 'deep';
-        const dataType = this.dataType;
         validator = dataType.generateCodec('decode', options);
         this._inputCodecs[cacheKey] = validator;
         return validator;
     }
     /**
-     * Retrieves the codec.
+     * Returns the output codec for the given operation.
+     *
+     * @param operation - The operation name.
      */
     getOutputCodec(operation) {
+        const dataType = this.dataType;
         const cacheKey = operation + (this._dataTypeScope ? ':' + this._dataTypeScope : '');
         let validator = this._outputCodecs[cacheKey];
         if (validator)
@@ -151,16 +153,15 @@ export class SqbEntityService extends SqbServiceBase {
             partial: 'deep',
             scope: this._dataTypeScope,
         };
-        const dataType = this.dataType;
         validator = dataType.generateCodec('decode', options);
         this._outputCodecs[cacheKey] = validator;
         return validator;
     }
     /**
-     * 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
      */
     async _create(command) {
@@ -177,10 +178,9 @@ export class SqbEntityService extends SqbServiceBase {
         throw new InternalServerError(`Unknown error while creating document for "${this.getResourceName()}"`);
     }
     /**
-     * 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
      */
     async _createOnly(command) {
@@ -193,55 +193,54 @@ export class SqbEntityService extends SqbServiceBase {
         return await repo.createOnly(data, options);
     }
     /**
-     * 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
      */
     async _count(command) {
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return this._dbCount({ ...command.options, filter });
     }
     /**
-     * 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
      */
     async _delete(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return this._dbDelete(command.documentId, { ...command.options, filter });
     }
     /**
-     * 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
      */
     async _deleteMany(command) {
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return await this._dbDeleteMany({ ...command.options, filter });
     }
     /**
-     * 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
      */
     async _exists(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return await this._dbExists(command.documentId, {
             ...command.options,
@@ -249,30 +248,29 @@ export class SqbEntityService extends SqbServiceBase {
         });
     }
     /**
-     * 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
      */
     async _existsOne(command) {
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return await this._dbExistsOne({ ...command.options, filter });
     }
     /**
-     * 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
      */
     async _findById(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
         const decode = this.getOutputCodec('find');
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         const out = await this._dbFindById(command.documentId, {
             ...command.options,
@@ -281,31 +279,31 @@ export class SqbEntityService extends SqbServiceBase {
         return out ? decode(out) : 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
      */
     async _findOne(command) {
         const decode = this.getOutputCodec('find');
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         const out = await this._dbFindOne({ ...command.options, filter });
         return out ? decode(out) : 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
      */
     async _findMany(command) {
         const decode = this.getOutputCodec('find');
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         const out = await this._dbFindMany({ ...command.options, filter });
         if (out?.length) {
@@ -314,10 +312,10 @@ export class SqbEntityService extends SqbServiceBase {
         return out;
     }
     /**
-     * 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
      */
     async _update(command) {
@@ -327,7 +325,7 @@ export class SqbEntityService extends SqbServiceBase {
         const inputCodec = this.getInputCodec('update');
         const data = inputCodec(input);
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         const out = await this._dbUpdate(documentId, data, { ...options, filter });
         const outputCodec = this.getOutputCodec('update');
@@ -335,10 +333,10 @@ export class SqbEntityService extends SqbServiceBase {
             return outputCodec(out);
     }
     /**
-     * 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
      */
     async _updateOnly(command) {
@@ -348,15 +346,15 @@ export class SqbEntityService extends SqbServiceBase {
         const inputCodec = this.getInputCodec('update');
         const data = inputCodec(input);
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return await this._dbUpdateOnly(documentId, data, { ...options, filter });
     }
     /**
-     * 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
      */
     async _updateMany(command) {
@@ -364,15 +362,15 @@ export class SqbEntityService extends SqbServiceBase {
         const inputCodec = this.getInputCodec('update');
         const data = inputCodec(command.input);
         const filter = command.options?.filter
-            ? SQBAdapter.parseFilter(command.options.filter)
+            ? SQBAdapter.prepareFilter(command.options.filter)
             : undefined;
         return await this._dbUpdateMany(data, { ...command.options, filter });
     }
     /**
-     * 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
      */
     async _dbCreate(input, options) {
@@ -381,170 +379,169 @@ export class SqbEntityService extends SqbServiceBase {
         return await repo.create(input, options);
     }
     /**
-     * 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
      */
     async _dbCount(options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.count(options);
     }
     /**
-     * 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
      */
     async _dbDelete(id, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return (await repo.delete(id, options)) ? 1 : 0;
     }
     /**
-     * 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
      */
     async _dbDeleteMany(options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.deleteMany(options);
     }
     /**
-     * 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
      */
     async _dbExists(id, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.exists(id, options);
     }
     /**
-     * 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
      */
     async _dbExistsOne(options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.existsOne(options);
     }
     /**
-     * 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
      */
     async _dbFindById(id, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.findById(id, options);
     }
     /**
-     * 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
      */
     async _dbFindOne(options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.findOne({ ...options, offset: options?.skip });
     }
     /**
-     * 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
      */
     async _dbFindMany(options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.findMany({ ...options, offset: options?.skip });
     }
     /**
-     * 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
      */
     async _dbUpdate(id, data, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.update(id, data, options);
     }
     /**
-     * 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
      */
     async _dbUpdateOnly(id, data, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return (await repo.updateOnly(id, data, options)) ? 1 : 0;
     }
     /**
-     * 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
      */
     async _dbUpdateMany(data, options) {
         const conn = await this.getConnection();
         const repo = conn.getRepository(this.dataTypeClass);
         if (options?.filter)
-            options.filter = SQBAdapter.parseFilter(options.filter);
+            options.filter = SQBAdapter.prepareFilter(options.filter);
         return await repo.updateMany(data, options);
     }
     /**
-     * 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.
      */
     _getCommonFilter(command) {
         const commonFilter = Array.isArray(this.commonFilter)
             ? this.commonFilter
             : [this.commonFilter];
         const mapped = commonFilter.map(f => typeof f === 'function' ? f(command, this) : f);
-        return mapped.length > 1 ? op.and(...mapped) : mapped[0];
+        return mapped.length > 1 ? sql.And(...mapped) : mapped[0];
     }
     async _executeCommand(command, commandFn) {
         let proto;
@@ -559,7 +556,7 @@ export class SqbEntityService extends SqbServiceBase {
                 if (!(proto instanceof SqbEntityService))
                     break;
             }
-            /** Call before[X] hooks */
+            /* Call before[X] hooks */
             if (command.crud === 'create')
                 await this._beforeCreate(command);
             else if (command.crud === 'update' && command.byId) {
@@ -574,12 +571,12 @@ export class SqbEntityService extends SqbServiceBase {
             else if (command.crud === 'delete' && !command.byId) {
                 await this._beforeDeleteMany(command);
             }
-            /** Call command function */
+            /* Call command function */
             return commandFn();
         };
         try {
             const result = await next();
-            /** Call after[X] hooks */
+            /* Call after[X] hooks */
             if (command.crud === 'create')
                 await this._afterCreate(command, result);
             else if (command.crud === 'update' && command.byId) {
@@ -598,7 +595,7 @@ export class SqbEntityService extends SqbServiceBase {
         }
         catch (e) {
             Error.captureStackTrace(e, this._executeCommand);
-            await this.onError?.(e, this);
+            await this.onError?.(e, command, this);
             throw e;
         }
     }