@opra/sqb 1.26.3 → 1.26.4

package/sqb-service-base.js

@@ -2,45 +2,45 @@ import { ServiceBase } from '@opra/core';
 import { SqbConnection } from '@sqb/connect';
 const transactionKey = Symbol.for('transaction');
 /**
- * @class SqbServiceBase
- * @template T - The data type class type of the resource
+ * Base class for services using SQB (SQL Builder) for database operations.
  */
 export class SqbServiceBase extends ServiceBase {
     /**
-     * Represents an SqbClient or SqbConnection object
+     * The SQB client or connection used by this service.
      */
     db;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param [options] - The options for the service.
-     * @constructor
+     * @param options - Options for the service.
      */
     constructor(options) {
-        super();
+        super(options);
         this.db = options?.db;
     }
     /**
-     * Executes the provided function within a transaction.
+     * Executes the provided callback within a database transaction.
+     * If a transaction is already active in the current context, the callback
+     * joins it rather than starting a new one.
      *
-     * @param callback - The function to be executed within the transaction.
+     * @param callback - The function to execute within the transaction.
      */
     async withTransaction(callback) {
         const ctx = this.context;
         let closeSessionOnFinish = false;
         let connection = ctx[transactionKey];
         if (!connection) {
-            /** Determine the SqbClient or SqbConnection instance */
+            /* Determine the SqbClient or SqbConnection instance */
             const db = await this.getConnection();
             if (db instanceof SqbConnection) {
                 connection = db;
             }
             else {
-                /** Acquire a connection. New connection should be at the end */
+                /* Acquire a connection. New connection should be at the end */
                 connection = await db.acquire({ autoCommit: false });
                 closeSessionOnFinish = true;
             }
-            /** Store transaction connection in current context */
+            /* Store transaction connection in current context */
             ctx[transactionKey] = connection;
         }
         const oldInTransaction = connection.inTransaction;
@@ -60,7 +60,7 @@ export class SqbServiceBase extends ServiceBase {
         }
         finally {
             delete ctx[transactionKey];
-            /** Release connection */
+            /* Release connection */
             if (closeSessionOnFinish) {
                 await connection.close();
             }
@@ -69,11 +69,9 @@ export class SqbServiceBase extends ServiceBase {
         }
     }
     /**
-     * Retrieves the database connection.
+     * Returns the active database connection for the current context.
      *
-     * @protected
-     *
-     * @throws {Error} If the context or database is not set.
+     * @throws If no database connection is configured.
      */
     getConnection() {
         const ctx = this.context;

package/sqb-singleton-service.d.ts

@@ -2,138 +2,128 @@ import type { PartialDTO, PatchDTO, RequiredSome, Type } from 'ts-gems';
 import { SQBAdapter } from './sqb-adapter.js';
 import { SqbEntityService } from './sqb-entity-service.js';
 /**
- * @namespace SqbSingletonService
+ * Options for SqbSingletonService.
  */
 export declare namespace SqbSingletonService {
-    interface Options extends SqbEntityService.Options {
-        id?: SqbSingletonService<any>['id'];
-    }
     /**
-     * Represents options for "create" operation
-     *
-     * @interface
+     * Configuration options for SqbSingletonService.
      */
-    interface CreateOptions extends SqbEntityService.CreateOptions {
+    interface Options extends SqbEntityService.Options {
+        /**
+         * The identifier used to locate the singleton record.
+         */
+        id?: SqbSingletonService<any>['id'];
     }
+}
+/**
+ * Service for managing a single entity record backed by an SQB data source.
+ *
+ * @typeParam T - The entity type managed by this service
+ */
+export declare class SqbSingletonService<T extends object = object> extends SqbEntityService<T> {
     /**
-     * Represents options for "delete" operation
-     *
-     * @interface
+     * The identifier used to locate the singleton record.
      */
-    interface DeleteOptions extends SqbEntityService.DeleteOptions {
-    }
+    id: SQBAdapter.IdOrIds;
     /**
-     * Represents options for "exists" operation
+     * Constructs a new instance.
      *
-     * @interface
+     * @param dataType - The entity class or its registered name.
+     * @param options - Options for the singleton service.
      */
-    interface ExistsOptions extends SqbEntityService.ExistsOptions {
-    }
+    constructor(dataType: Type<T> | string, options?: SqbSingletonService.Options);
     /**
-     * Represents options for "find" operation
+     * Asserts that the singleton record exists.
+     * Throws {@link ResourceNotAvailableError} if it does not.
      *
-     * @interface
+     * @param options - Optional existence check options.
+     * @throws {@link ResourceNotAvailableError} If the record does not exist.
      */
-    interface FindOptions extends SqbEntityService.FindOneOptions {
-    }
+    assert(options?: SqbEntityService.ExistsOptions): Promise<void>;
     /**
-     * Represents options for "update" operation
+     * Creates the singleton record and returns it with the requested projection.
      *
-     * @interface
+     * @param input - The input data for the new record.
+     * @param options - Options including a required `projection`.
+     * @returns The created record as a partial DTO.
      */
-    interface UpdateOptions extends SqbEntityService.UpdateOneOptions {
-    }
+    create(input: PartialDTO<T>, options: RequiredSome<SqbEntityService.CreateOptions, 'projection'>): Promise<PartialDTO<T>>;
     /**
-     * Represents options for "updateOnly" operation
+     * Creates the singleton record and returns the full DTO.
      *
-     * @interface
+     * @param input - The input data for the new record.
+     * @param options - Optional create options.
+     * @returns The created record as a full DTO.
      */
-    interface UpdateOnlyOptions extends SqbEntityService.UpdateOneOptions {
-    }
-}
-/**
- * @class SqbSingletonService
- * @template T - The data type class type of the resource
- */
-export declare class SqbSingletonService<T extends object = object> extends SqbEntityService<T> {
-    /**
-     * Represents a unique identifier for singleton record
-     * @property {SQBAdapter.IdOrIds}
-     */
-    id: SQBAdapter.IdOrIds;
+    create(input: PartialDTO<T>, options?: SqbEntityService.CreateOptions): Promise<T>;
     /**
-     * Constructs a new instance
+     * Deletes the singleton record.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {SqbSingletonService.Options} [options] - The options for the array service.
-     * @constructor
+     * @param options - Optional delete options.
+     * @returns The number of records deleted.
      */
-    constructor(dataType: Type<T> | string, options?: SqbSingletonService.Options);
+    delete(options?: SqbEntityService.DeleteOptions): Promise<number>;
     /**
-     * Asserts the existence of a resource based on the given options.
+     * Checks whether the singleton record exists.
      *
-     * @returns {Promise<void>} A Promise that resolves when the resource exists.
-     * @throws {ResourceNotAvailableError} If the resource does not exist.
+     * @param options - Optional query options.
+     * @returns `true` if the record exists, `false` otherwise.
      */
-    assert(options?: SqbSingletonService.ExistsOptions): Promise<void>;
+    exists(options?: SqbEntityService.ExistsOptions): Promise<boolean>;
     /**
-     * Inserts a single record into the database.
+     * Finds the singleton record with the requested projection.
+     * Returns `undefined` if it does not exist.
      *
-     * @param {PartialDTO<T>} input - The input data
-     * @param {SqbSingletonService.CreateOptions} [options] - The options object
-     * @returns {Promise<PartialDTO<T>>} A promise that resolves to the created resource
-     * @throws {Error} if an unknown error occurs while creating the resource
+     * @param options - Options including a required `projection`.
+     * @returns The record as a partial DTO, or `undefined`.
      */
-    create(input: PartialDTO<T>, options: RequiredSome<SqbSingletonService.CreateOptions, 'projection'>): Promise<PartialDTO<T>>;
-    create(input: PartialDTO<T>, options?: SqbSingletonService.CreateOptions): Promise<T>;
+    find(options: RequiredSome<SqbEntityService.FindOneOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
     /**
-     * Deletes the singleton record
+     * Finds the singleton record. Returns `undefined` if it does not exist.
      *
-     * @param {SqbSingletonService.DeleteOptions} [options] - The options object
-     * @return {Promise<number>} - A Promise that resolves to the number of records deleted
+     * @param options - Optional query options.
+     * @returns The record as a full DTO, or `undefined`.
      */
-    delete(options?: SqbSingletonService.DeleteOptions): Promise<number>;
+    find(options?: SqbEntityService.FindOneOptions): Promise<T | undefined>;
     /**
-     * Checks if the singleton record exists.
+     * Retrieves the singleton record with the requested projection.
+     * Throws if the record does not exist.
      *
-     * @param {SqbSingletonService.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 options - Options including a required `projection`.
+     * @returns The record as a partial DTO.
+     * @throws {@link ResourceNotAvailableError} If the record does not exist.
      */
-    exists(options?: SqbSingletonService.ExistsOptions): Promise<boolean>;
+    get(options: RequiredSome<SqbEntityService.FindOneOptions, 'projection'>): Promise<PartialDTO<T>>;
     /**
-     * Finds the singleton record. Returns `undefined` if not found
+     * Retrieves the singleton record. Throws if it does not exist.
      *
-     * @param {SqbSingletonService.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.
+     * @param options - Optional query options.
+     * @returns The record as a full DTO.
+     * @throws {@link ResourceNotAvailableError} If the record does not exist.
      */
-    find(options: RequiredSome<SqbSingletonService.FindOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
-    find(options?: SqbSingletonService.FindOptions): Promise<T | undefined>;
+    get(options?: SqbEntityService.FindOneOptions): Promise<T>;
     /**
-     * Retrieves the singleton record. Throws error if not found.
+     * Updates the singleton record and returns it with the requested projection.
      *
-     * @param {SqbSingletonService.FindOptions} [options] - Optional options for the `find` 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 does not exist.
+     * @param input - The fields to update.
+     * @param options - Options including a required `projection`.
+     * @returns The updated record as a partial DTO, or `undefined` if not found.
      */
-    get(options: RequiredSome<SqbSingletonService.FindOptions, 'projection'>): Promise<PartialDTO<T>>;
-    get(options?: SqbSingletonService.FindOptions): Promise<T>;
+    update(input: PatchDTO<T>, options: RequiredSome<SqbEntityService.UpdateOneOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
     /**
-     * Updates the singleton.
+     * Updates the singleton record and returns the full DTO.
      *
-     * @param {PatchDTO<T>} input - The partial input object containing the fields to update.
-     * @param {SqbSingletonService.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.
+     * @param input - The fields to update.
+     * @param options - Optional update options.
+     * @returns The updated record as a full DTO, or `undefined` if not found.
      */
-    update(input: PatchDTO<T>, options: RequiredSome<SqbSingletonService.UpdateOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
-    update(input: PatchDTO<T>, options?: SqbSingletonService.UpdateOptions): Promise<T | undefined>;
+    update(input: PatchDTO<T>, options?: SqbEntityService.UpdateOneOptions): Promise<T | undefined>;
     /**
-     * Updates the singleton and  returns updated record count
+     * Updates the singleton record without returning it.
      *
-     * @param {PatchDTO<T>} input - The partial input data to update the document with.
-     * @param {SqbSingletonService.UpdateOptions} options - The options for updating the document.
-     * @returns {Promise<number>} - A promise that resolves to the number of documents modified.
+     * @param input - The fields to update.
+     * @param options - Optional update options.
+     * @returns The number of records modified.
      */
-    updateOnly(input: PatchDTO<T>, options?: SqbSingletonService.UpdateOnlyOptions): Promise<number>;
+    updateOnly(input: PatchDTO<T>, options?: SqbEntityService.UpdateOneOptions): Promise<number>;
 }

package/sqb-singleton-service.js

@@ -3,31 +3,31 @@ import { EntityMetadata } from '@sqb/connect';
 import { SQBAdapter } from './sqb-adapter.js';
 import { SqbEntityService } from './sqb-entity-service.js';
 /**
- * @class SqbSingletonService
- * @template T - The data type class type of the resource
+ * Service for managing a single entity record backed by an SQB data source.
+ *
+ * @typeParam T - The entity type managed by this service
  */
 export class SqbSingletonService extends SqbEntityService {
     /**
-     * Represents a unique identifier for singleton record
-     * @property {SQBAdapter.IdOrIds}
+     * The identifier used to locate the singleton record.
      */
     id;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {SqbSingletonService.Options} [options] - The options for the array service.
-     * @constructor
+     * @param dataType - The entity class or its registered name.
+     * @param options - Options for the singleton service.
      */
     constructor(dataType, options) {
         super(dataType, options);
         this.id = options?.id || 1;
     }
     /**
-     * Asserts the existence of a resource based on the given options.
+     * Asserts that the singleton record exists.
+     * Throws {@link ResourceNotAvailableError} if it does not.
      *
-     * @returns {Promise<void>} A Promise that resolves when the resource exists.
-     * @throws {ResourceNotAvailableError} If the resource does not exist.
+     * @param options - Optional existence check options.
+     * @throws {@link ResourceNotAvailableError} If the record does not exist.
      */
     async assert(options) {
         if (!(await this.exists(options)))
@@ -59,10 +59,10 @@ export class SqbSingletonService extends SqbEntityService {
         });
     }
     /**
-     * Deletes the singleton record
+     * Deletes the singleton record.
      *
-     * @param {SqbSingletonService.DeleteOptions} [options] - The options object
-     * @return {Promise<number>} - A Promise that resolves to the number of records deleted
+     * @param options - Optional delete options.
+     * @returns The number of records deleted.
      */
     async delete(options) {
         const command = {
@@ -73,7 +73,7 @@ export class SqbSingletonService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -82,10 +82,10 @@ export class SqbSingletonService extends SqbEntityService {
         });
     }
     /**
-     * Checks if the singleton record exists.
+     * Checks whether the singleton record exists.
      *
-     * @param {SqbSingletonService.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 options - Optional query options.
+     * @returns `true` if the record exists, `false` otherwise.
      */
     async exists(options) {
         const command = {
@@ -96,7 +96,7 @@ export class SqbSingletonService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -113,7 +113,7 @@ export class SqbSingletonService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -137,7 +137,7 @@ export class SqbSingletonService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);
@@ -146,11 +146,11 @@ export class SqbSingletonService extends SqbEntityService {
         });
     }
     /**
-     * Updates the singleton and  returns updated record count
+     * Updates the singleton record without returning it.
      *
-     * @param {PatchDTO<T>} input - The partial input data to update the document with.
-     * @param {SqbSingletonService.UpdateOptions} options - The options for updating the document.
-     * @returns {Promise<number>} - A promise that resolves to the number of documents modified.
+     * @param input - The fields to update.
+     * @param options - Optional update options.
+     * @returns The number of records modified.
      */
     async updateOnly(input, options) {
         const command = {
@@ -162,7 +162,7 @@ export class SqbSingletonService extends SqbEntityService {
             options,
         };
         return this._executeCommand(command, async () => {
-            const filter = SQBAdapter.parseFilter([
+            const filter = SQBAdapter.prepareFilter([
                 await this._getCommonFilter(command),
                 command.options?.filter,
             ]);