@opra/sqb 1.26.2 → 1.26.4

package/sqb-collection-service.js

@@ -2,33 +2,32 @@ import { ResourceNotAvailableError } from '@opra/common';
 import { SQBAdapter } from './sqb-adapter.js';
 import { SqbEntityService } from './sqb-entity-service.js';
 /**
- * @class SqbCollectionService
- * @template T - The data type class type of the resource
+ * Service for managing a collection of entities backed by an SQB data source.
+ *
+ * @typeParam T - The entity type managed by this service
  */
 export class SqbCollectionService extends SqbEntityService {
     /**
-     * Represents default limit for findMany operation
+     * Default maximum number of records returned by `findMany`.
      */
     defaultLimit;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {SqbCollectionService.Options} [options] - The options for the array service.
-     * @constructor
+     * @param dataType - The data type of the collection elements.
+     * @param options - Options for the collection service.
      */
     constructor(dataType, options) {
         super(dataType, options);
         this.defaultLimit = options?.defaultLimit || 100;
     }
     /**
-     * Asserts the existence of a resource with the given ID.
-     * Throws a ResourceNotFoundError if the resource does not exist.
+     * Asserts that a resource with the given ID exists.
+     * Throws {@link ResourceNotAvailableError} if it does not.
      *
-     * @param {SQBAdapter.IdOrIds} id - The ID of the resource to assert.
-     * @param {SqbCollectionService.ExistsOptions} [options] - Optional options for checking the existence.
-     * @returns {Promise<void>} - A Promise that resolves when the resource exists.
-     * @throws {ResourceNotAvailableError} - If the resource does not exist.
+     * @param id - The ID of the resource to check.
+     * @param options - Optional existence check options.
+     * @throws {@link ResourceNotAvailableError} If the resource does not exist.
      */
     async assert(id, options) {
         if (!(await this.exists(id, options)))
@@ -45,12 +44,10 @@ export class SqbCollectionService extends SqbEntityService {
         return this._executeCommand(command, () => this._create(command));
     }
     /**
-     * Creates a new resource
+     * Creates a new resource without returning it.
      *
-     * @param {PartialDTO<T>} input - The input data
-     * @param {SqbCollectionService.CreateOptions} [options] - The options object
-     * @returns {Promise<void>} A promise that resolves create operation result
-     * @throws {Error} if an unknown error occurs while creating the resource
+     * @param input - The input data for the new resource.
+     * @param options - Optional create options.
      */
     async createOnly(input, options) {
         const command = {
@@ -63,10 +60,10 @@ export class SqbCollectionService extends SqbEntityService {
         return this._executeCommand(command, () => this._createOnly(command));
     }
     /**
-     * Returns the count of records based on the provided options
+     * Returns the number of records matching the given options.
      *
-     * @param {SqbCollectionService.CountOptions} options - The options for the count operation.
-     * @return {Promise<number>} - A promise that resolves to the count of records
+     * @param options - Options for the count operation.
+     * @returns The number of matching records.
      */
     async count(options) {
         const command = {
@@ -76,7 +73,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -85,11 +82,11 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Deletes a record from the collection.
+     * Deletes the record with the given ID.
      *
-     * @param {SQBAdapter.IdOrIds} id - The ID of the document to delete.
-     * @param {SqbCollectionService.DeleteOptions} [options] - Optional delete options.
-     * @return {Promise<number>} - A Promise that resolves to the number of documents deleted.
+     * @param id - The ID of the record to delete.
+     * @param options - Optional delete options.
+     * @returns The number of records deleted.
      */
     async delete(id, options) {
         const command = {
@@ -100,7 +97,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -109,10 +106,10 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Deletes multiple documents from the collection that meet the specified filter criteria.
+     * Deletes all records matching the given options.
      *
-     * @param {SqbCollectionService.DeleteManyOptions} options - The options for the delete operation.
-     * @return {Promise<number>} - A promise that resolves to the number of documents deleted.
+     * @param options - Options including filter criteria.
+     * @returns The number of records deleted.
      */
     async deleteMany(options) {
         const command = {
@@ -122,7 +119,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -131,11 +128,11 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Checks if a record with the given id exists.
+     * Checks whether a record with the given ID exists.
      *
-     * @param {SQBAdapter.IdOrIds} id - The id of the object to check.
-     * @param {SqbCollectionService.ExistsOptions} [options] - The options for the query (optional).
-     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the record exists or not.
+     * @param id - The ID to check.
+     * @param options - Optional query options.
+     * @returns `true` if the record exists, `false` otherwise.
      */
     async exists(id, options) {
         const command = {
@@ -146,7 +143,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -155,10 +152,10 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Checks if a record with the given arguments exists.
+     * Checks whether any record matching the given options exists.
      *
-     * @param {SqbCollectionService.ExistsOneOptions} [options] - The options for the query (optional).
-     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the record exists or not.
+     * @param options - Optional query options.
+     * @returns `true` if at least one matching record exists, `false` otherwise.
      */
     async existsOne(options) {
         const command = {
@@ -168,7 +165,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -176,13 +173,6 @@ export class SqbCollectionService extends SqbEntityService {
             return this._existsOne(command);
         });
     }
-    /**
-     * Finds a record by ID.
-     *
-     * @param {SQBAdapter.IdOrIds} id - The ID of the record.
-     * @param {SqbCollectionService.FindOneOptions} [options] - The options for the find query.
-     * @return {Promise<PartialDTO<T | undefined>>} - A promise resolving to the found document, or undefined if not found.
-     */
     async findById(id, options) {
         const command = {
             crud: 'read',
@@ -193,7 +183,7 @@ export class SqbCollectionService extends SqbEntityService {
         };
         return this._executeCommand(command, async () => {
             const documentFilter = await this._getCommonFilter(command);
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 documentFilter,
                 command.options?.filter,
             ]);
@@ -201,12 +191,6 @@ export class SqbCollectionService extends SqbEntityService {
             return this._findById(command);
         });
     }
-    /**
-     * Finds a record in the collection that matches the specified options.
-     *
-     * @param {SqbCollectionService.FindOneOptions} options - The options for the query.
-     * @return {Promise<PartialDTO<T> | undefined>} A promise that resolves with the found document or undefined if no document is found.
-     */
     async findOne(options) {
         const command = {
             crud: 'read',
@@ -215,7 +199,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -223,12 +207,6 @@ export class SqbCollectionService extends SqbEntityService {
             return this._findOne(command);
         });
     }
-    /**
-     * Finds multiple records in collection.
-     *
-     * @param {SqbCollectionService.FindManyOptions} options - The options for the find operation.
-     * @return A Promise that resolves to an array of partial outputs of type T.
-     */
     async findMany(options) {
         const command = {
             crud: 'read',
@@ -237,7 +215,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -246,13 +224,6 @@ export class SqbCollectionService extends SqbEntityService {
             return this._findMany(command);
         });
     }
-    /**
-     * Finds multiple records in the collection and returns both records (max limit)
-     * and total count that matched the given criteria
-     *
-     * @param {SqbCollectionService.FindManyOptions} options - The options for the find operation.
-     * @return A Promise that resolves to an array of partial outputs of type T and total count.
-     */
     async findManyWithCount(options) {
         const [items, count] = await Promise.all([
             this.findMany(options),
@@ -260,30 +231,12 @@ export class SqbCollectionService extends SqbEntityService {
         ]);
         return { count, items };
     }
-    /**
-     * Retrieves a records from the collection by its ID. Throws error if not found.
-     *
-     * @param {SQBAdapter.IdOrIds} id - The ID of the document to retrieve.
-     * @param {SqbCollectionService.FindOneOptions} [options] - Optional options for the findOne operation.
-     * @returns {Promise<PartialDTO<T>>} - A promise that resolves to the retrieved document,
-     *    or rejects with a ResourceNotFoundError if the document does not exist.
-     * @throws {ResourceNotAvailableError} - If the document with the specified ID does not exist.
-     */
     async get(id, options) {
         const out = await this.findById(id, options);
         if (!out)
             throw new ResourceNotAvailableError(this.getResourceName(), id);
         return out;
     }
-    /**
-     * Updates a record with the given id in the collection.
-     *
-     * @param {SQBAdapter.IdOrIds} id - The id of the document to update.
-     * @param {PatchDTO<T>} input - The partial input object containing the fields to update.
-     * @param {SqbCollectionService.UpdateOptions} [options] - The options for the update operation.
-     * @returns {Promise<PartialDTO<T> | undefined>} A promise that resolves to the updated document or
-     * undefined if the document was not found.
-     */
     async update(id, input, options) {
         const command = {
             crud: 'update',
@@ -294,7 +247,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -303,12 +256,12 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Updates a record in the collection with the specified ID and returns updated record count
+     * Updates a record by ID without returning it.
      *
-     * @param {any} id - The ID of the document to update.
-     * @param {PatchDTO<T>} input - The partial input data to update the document with.
-     * @param {SqbCollectionService.UpdateOptions} options - The options for updating the document.
-     * @returns {Promise<number>} - A promise that resolves to the number of documents modified.
+     * @param id - The ID of the record to update.
+     * @param input - The fields to update.
+     * @param options - Optional update options.
+     * @returns The number of records modified.
      */
     async updateOnly(id, input, options) {
         const command = {
@@ -320,7 +273,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -329,11 +282,11 @@ export class SqbCollectionService extends SqbEntityService {
         });
     }
     /**
-     * Updates multiple records in the collection based on the specified input and options.
+     * Updates all records matching the given options.
      *
-     * @param {PatchDTO<T>} input - The partial input to update the documents with.
-     * @param {SqbCollectionService.UpdateManyOptions} options - The options for updating the documents.
-     * @return {Promise<number>} - A promise that resolves to the number of documents matched and modified.
+     * @param input - The fields to update.
+     * @param options - Options including filter criteria.
+     * @returns The number of records modified.
      */
     async updateMany(input, options) {
         const command = {
@@ -344,7 +297,7 @@ export class SqbCollectionService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);