@opra/mongodb 1.26.2 → 1.26.4

package/services/mongo-singleton-service.d.ts

@@ -5,47 +5,43 @@ import { MongoAdapter } from '../adapter/mongo-adapter.js';
 import type { MongoPatchDTO } from '../types.js';
 import { MongoEntityService } from './mongo-entity-service.js';
 /**
- *
- * @namespace MongoSingletonService
+ * Options for MongoSingletonService.
  */
 export declare namespace MongoSingletonService {
     /**
-     * The constructor options of MongoSingletonService.
-     *
-     * @interface Options
-     * @extends MongoService.Options
+     * Configuration options for MongoSingletonService.
      */
     interface Options extends MongoEntityService.Options {
+        /**
+         * The unique identifier for the singleton record.
+         */
         _id?: MongoAdapter.AnyId;
     }
 }
 /**
- * A class that provides access to a MongoDB collection, with support for singleton document operations.
- * @class MongoSingletonService
- * @extends MongoService
- * @template T - The type of document stored in the collection
+ * Service for managing a single entity record backed by a MongoDB data source.
+ *
+ * @template T - The entity type managed by this service.
  */
 export declare class MongoSingletonService<T extends mongodb.Document> extends MongoEntityService<T> {
     /**
-     * Represents a unique identifier for singleton record
-     * @type {MongoAdapter.AnyId} _id
+     * The unique identifier for the singleton record.
      */
     _id: MongoAdapter.AnyId;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {MongoSingletonService.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: Type | string, options?: MongoSingletonService.Options);
     /**
      * Create a copy of this instance with given properties and context applied.
      *
-     * @param {C | ServiceBase} context - The execution context or service base to associate with this instance.
-     * @param {Nullish<P>} [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
-     * @param {Partial<C>} [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
-     * @return {this & Required<P>} The current instance with the specified properties and context applied.
+     * @param context - The execution context or service base to associate with this instance.
+     * @param [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
+     * @param [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
+     * @returns The current instance with the specified properties and context applied.
      * @template P
      * @template C
      */
@@ -53,78 +49,85 @@ export declare class MongoSingletonService<T extends mongodb.Document> extends M
     /**
      * Asserts the existence of a resource based on the given options.
      *
-     * @param {MongoEntityService.ExistsOptions<T>} [options]
-     * @returns {Promise<void>} A Promise that resolves when the resource exists.
-     * @throws {ResourceNotAvailableError} If the resource does not exist.
+     * @param options - Optional options for checking the existence.
+     * @returns A Promise that resolves when the resource exists.
+     * @throws {@link ResourceNotAvailableError} If the resource does not exist.
      */
     assert(options?: MongoEntityService.ExistsOptions<T>): Promise<void>;
     /**
      * Creates the document in the database.
      *
-     * @param {PartialDTO<T>} input - The partial input to create the document with.
-     * @param {MongoEntityService.CreateOptions} [options] - The options for creating the document.
-     * @return {Promise<PartialDTO<T>>} A promise that resolves to the partial output of the created document.
-     * @throws {Error} Throws an error if an unknown error occurs while creating the document.
+     * @param input - The partial input to create the document with.
+     * @param options - The options for creating the document.
+     * @returns A promise that resolves to the partial output of the created document.
+     * @throws {@link Error} Throws an error if an unknown error occurs while creating the document.
      */
     create(input: PartialDTO<T>, options: RequiredSome<MongoEntityService.CreateOptions, 'projection'>): Promise<PartialDTO<T>>;
     create(input: PartialDTO<T>, options?: MongoEntityService.CreateOptions): Promise<T>;
     /**
      * Creates the document in the database.
      *
-     * @param {PartialDTO<T>} input - The partial input to create the document with.
-     * @param {MongoEntityService.CreateOptions} [options] - The options for creating the document.
-     * @returns {Promise<T>} A promise that resolves create operation result
-     * @throws {Error} Throws an error if an unknown error occurs while creating the document.
+     * @param input - The partial input to create the document with.
+     * @param options - The options for creating the document.
+     * @returns A promise that resolves to the created document.
+     * @throws {@link Error} Throws an error if an unknown error occurs while creating the document.
      */
     createOnly(input: PartialDTO<T>, options?: MongoEntityService.CreateOptions): Promise<T>;
     /**
      * Deletes a record from the database
      *
-     * @param {MongoEntityService.DeleteOptions<T>} options - The options for deleting the record
-     * @returns {Promise<number>} The number of records deleted
+     * @param options - The options for deleting the record
+     * @returns The number of records deleted
      */
     delete(options?: MongoEntityService.DeleteOptions<T>): Promise<number>;
     /**
      * Checks if the document exists in the database.
      *
-     * @param {MongoEntityService.FindOneOptions<T>} [options] - The options for finding the document.
-     * @return {Promise<boolean>} - A promise that resolves to a boolean value indicating if the document exists.
+     * @param [options] - The options for finding the document.
+     * @returns A promise that resolves to a boolean value indicating if the document exists.
      */
     exists(options?: MongoEntityService.ExistsOptions<T>): Promise<boolean>;
     /**
      * Fetches the document if it exists. Returns undefined if not found.
      *
-     * @param {MongoEntityService.FindOneOptions<T>} [options] - The options for finding the document.
-     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
+     * @param [options] - The options for finding the document.
+     * @returns A promise that resolves to the found document or undefined if not found.
      */
     find(options: RequiredSome<MongoEntityService.FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>;
     find(options?: MongoEntityService.FindOneOptions<T>): Promise<T | undefined>;
     /**
      * Fetches the document from the Mongo collection service. Throws error if not found.
      *
-     * @param {MongoEntityService.FindOneOptions<T>} options - The options to customize the query.
-     * @return {Promise<PartialDTO<T>>} - A promise that resolves to the fetched document.
-     * @throws {ResourceNotAvailableError} - If the document is not found in the collection
+     * @param options - The options to customize the query.
+     * @returns A promise that resolves to the fetched document.
+     * @throws {@link ResourceNotAvailableError} If the document is not found in the collection.
      */
     get(options: RequiredSome<MongoEntityService.FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T>>;
+    /**
+     * Fetches the document from the Mongo collection service. Throws error if not found.
+     *
+     * @param options - The options to customize the query.
+     * @returns A promise that resolves to the fetched document.
+     * @throws {@link ResourceNotAvailableError} If the document is not found in the collection.
+     */
     get(options?: MongoEntityService.FindOneOptions<T>): Promise<T>;
     /**
      * Updates a document in the MongoDB collection
      *
-     * @param {MongoPatchDTO<T>} input - The partial input to update the document.
-     * @param {MongoEntityService.UpdateOneOptions<T>} [options] - The update options.
+     * @param input - The partial input to update the document.
+     * @param [options] - The update options.
      *
-     * @return {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the updated document or undefined if not found.
+     * @returns A promise that resolves to the updated document or undefined if not found.
      */
     update(input: MongoPatchDTO<T> | UpdateFilter<T>, options: RequiredSome<MongoEntityService.UpdateOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>;
     update(input: MongoPatchDTO<T> | UpdateFilter<T>, options?: MongoEntityService.UpdateOneOptions<T>): Promise<T | undefined>;
     /**
      * Updates a document in the MongoDB collection
      *
-     * @param {MongoPatchDTO<T>} input - The partial input to update the document.
-     * @param {MongoEntityService.UpdateOneOptions<T>} [options] - The update options.
+     * @param input - The partial input to update the document.
+     * @param [options] - The update options.
      *
-     * @return {Promise<number>} - A promise that resolves to the updated document or undefined if not found.
+     * @returns A promise that resolves to the updated document or undefined if not found.
      */
     updateOnly(input: MongoPatchDTO<T> | UpdateFilter<T>, options?: MongoEntityService.UpdateOneOptions<T>): Promise<number>;
 }

package/services/mongo-singleton-service.js

@@ -4,23 +4,20 @@ import { ObjectId } from 'mongodb';
 import { MongoAdapter } from '../adapter/mongo-adapter.js';
 import { MongoEntityService } from './mongo-entity-service.js';
 /**
- * A class that provides access to a MongoDB collection, with support for singleton document operations.
- * @class MongoSingletonService
- * @extends MongoService
- * @template T - The type of document stored in the collection
+ * Service for managing a single entity record backed by a MongoDB data source.
+ *
+ * @template T - The entity type managed by this service.
  */
 export class MongoSingletonService extends MongoEntityService {
     /**
-     * Represents a unique identifier for singleton record
-     * @type {MongoAdapter.AnyId} _id
+     * The unique identifier for the singleton record.
      */
     _id;
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {MongoSingletonService.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);
@@ -29,10 +26,10 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Create a copy of this instance with given properties and context applied.
      *
-     * @param {C | ServiceBase} context - The execution context or service base to associate with this instance.
-     * @param {Nullish<P>} [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
-     * @param {Partial<C>} [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
-     * @return {this & Required<P>} The current instance with the specified properties and context applied.
+     * @param context - The execution context or service base to associate with this instance.
+     * @param [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
+     * @param [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
+     * @returns The current instance with the specified properties and context applied.
      * @template P
      * @template C
      */
@@ -42,9 +39,9 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Asserts the existence of a resource based on the given options.
      *
-     * @param {MongoEntityService.ExistsOptions<T>} [options]
-     * @returns {Promise<void>} A Promise that resolves when the resource exists.
-     * @throws {ResourceNotAvailableError} If the resource does not exist.
+     * @param options - Optional options for checking the existence.
+     * @returns A Promise that resolves when the resource exists.
+     * @throws {@link ResourceNotAvailableError} If the resource does not exist.
      */
     async assert(options) {
         if (!(await this.exists(options)))
@@ -78,10 +75,10 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Creates the document in the database.
      *
-     * @param {PartialDTO<T>} input - The partial input to create the document with.
-     * @param {MongoEntityService.CreateOptions} [options] - The options for creating the document.
-     * @returns {Promise<T>} A promise that resolves create operation result
-     * @throws {Error} Throws an error if an unknown error occurs while creating the document.
+     * @param input - The partial input to create the document with.
+     * @param options - The options for creating the document.
+     * @returns A promise that resolves to the created document.
+     * @throws {@link Error} Throws an error if an unknown error occurs while creating the document.
      */
     async createOnly(input, options) {
         const command = {
@@ -97,8 +94,8 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Deletes a record from the database
      *
-     * @param {MongoEntityService.DeleteOptions<T>} options - The options for deleting the record
-     * @returns {Promise<number>} The number of records deleted
+     * @param options - The options for deleting the record
+     * @returns The number of records deleted
      */
     async delete(options) {
         const command = {
@@ -120,8 +117,8 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Checks if the document exists in the database.
      *
-     * @param {MongoEntityService.FindOneOptions<T>} [options] - The options for finding the document.
-     * @return {Promise<boolean>} - A promise that resolves to a boolean value indicating if the document exists.
+     * @param [options] - The options for finding the document.
+     * @returns A promise that resolves to a boolean value indicating if the document exists.
      */
     async exists(options) {
         const command = {
@@ -201,10 +198,10 @@ export class MongoSingletonService extends MongoEntityService {
     /**
      * Updates a document in the MongoDB collection
      *
-     * @param {MongoPatchDTO<T>} input - The partial input to update the document.
-     * @param {MongoEntityService.UpdateOneOptions<T>} [options] - The update options.
+     * @param input - The partial input to update the document.
+     * @param [options] - The update options.
      *
-     * @return {Promise<number>} - A promise that resolves to the updated document or undefined if not found.
+     * @returns A promise that resolves to the updated document or undefined if not found.
      */
     async updateOnly(input, options) {
         const command = {

package/types.d.ts

@@ -1,19 +1,25 @@
 import type { DTO, IfNoDeepValue } from 'ts-gems';
+/**
+ * Represents a MongoDB-specific Data Transfer Object for patch operations.
+ * It extends the standard patch DTO with MongoDB-specific operators like _$push and _$pull.
+ */
 export type MongoPatchDTO<T> = _MongoPatchDTO<DTO<T>> & PatchOperators<T>;
 /**
- * Returns given type as a Data Transfer Object (DTO) interface, Removes symbol keys and function properties.
- * @template T - The type of the data being transferred.
+ * Internal type for recursive MongoDB patch DTO.
  */
 type _MongoPatchDTO<T> = {
     [K in keyof T]?: Exclude<T[K], undefined> extends (infer U)[] ? _MongoPatchDTO<U>[] | null : IfNoDeepValue<NonNullable<T[K]>> extends true ? T[K] | null : // Deep process objects
     (_MongoPatchDTO<NonNullable<T[K]>> & PatchOperators<T>) | null;
 };
 /**
- * Pick all array properties in T
+ * Utility type to pick all array properties from T.
  */
 type PickArrays<T> = {
     [K in keyof T as NonNullable<T[K]> extends any[] ? K : never]: T[K];
 };
+/**
+ * MongoDB-specific patch operators.
+ */
 type PatchOperators<T> = {
     _$push?: PickArrays<Partial<T>>;
     _$pull?: {