@opra/mongodb 1.26.2 → 1.26.4

package/README.md

@@ -1,3 +1,26 @@
 # @opra/mongodb
 
-OPRA MongoDB package.
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+- node >= 20.x
+
+
+## License
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/mongodb
+[npm-url]: https://npmjs.org/package/@opra/mongodb
+[downloads-image]: https://img.shields.io/npm/dm/@opra/mongodb.svg
+[downloads-url]: https://npmjs.org/package/@opra/mongodb
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/adapter/mongo-adapter.d.ts

@@ -5,18 +5,63 @@ import _prepareFilter from './prepare-filter.js';
 import _prepareKeyValues from './prepare-key-values.js';
 import _prepareProjection from './prepare-projection.js';
 import _prepareSort from './prepare-sort.js';
+/**
+ * MongoAdapter namespace provides types and utility functions for integrating MongoDB with Opra.
+ */
 export declare namespace MongoAdapter {
+    /**
+     * Represents any type of identifier that can be used in MongoDB.
+     */
     type AnyId = string | number | ObjectId;
+    /**
+     * Represents the input for a filter, which can be an Opra filter expression,
+     * a MongoDB filter object, a string, or undefined.
+     */
     type FilterInput<T = any> = OpraFilter.Expression | mongodb.Filter<T> | string | undefined;
+    /**
+     * Prepares the given filter input into a MongoDB filter expression.
+     */
     const prepareFilter: typeof _prepareFilter;
+    /**
+     * Prepares the given key values into a MongoDB compatible format.
+     */
     const prepareKeyValues: typeof _prepareKeyValues;
+    /**
+     * Prepares the given projection into a MongoDB compatible format.
+     */
     const prepareProjection: typeof _prepareProjection;
+    /**
+     * Prepares the given sort into a MongoDB compatible format.
+     */
     const prepareSort: typeof _prepareSort;
+    /**
+     * Represents a request that has been transformed for MongoDB operations.
+     */
     interface TransformedRequest {
+        /**
+         * The operation method name.
+         */
         method: 'create' | 'delete' | 'deleteMany' | 'get' | 'findMany' | 'replace' | 'update' | 'updateMany';
+        /**
+         * The primary key for the operation, if applicable.
+         */
         key?: any;
+        /**
+         * The data object for create or update operations.
+         */
         data?: any;
+        /**
+         * Additional options for the MongoDB operation.
+         */
         options: any;
     }
+    /**
+     * Parses an execution context and transforms it into a MongoDB-compatible request.
+     *
+     * @param context - The execution context to parse.
+     * @returns A promise that resolves to the transformed request.
+     * @throws {@link TypeError} If the context transport is not 'http'.
+     * @throws {@link Error} If the operation is not compatible with MongoDB Adapter.
+     */
     function parseRequest(context: ExecutionContext): Promise<TransformedRequest>;
 }

package/adapter/mongo-adapter.js

@@ -2,12 +2,35 @@ import _prepareFilter from './prepare-filter.js';
 import _prepareKeyValues from './prepare-key-values.js';
 import _prepareProjection from './prepare-projection.js';
 import _prepareSort from './prepare-sort.js';
+/**
+ * MongoAdapter namespace provides types and utility functions for integrating MongoDB with Opra.
+ */
 export var MongoAdapter;
 (function (MongoAdapter) {
+    /**
+     * Prepares the given filter input into a MongoDB filter expression.
+     */
     MongoAdapter.prepareFilter = _prepareFilter;
+    /**
+     * Prepares the given key values into a MongoDB compatible format.
+     */
     MongoAdapter.prepareKeyValues = _prepareKeyValues;
+    /**
+     * Prepares the given projection into a MongoDB compatible format.
+     */
     MongoAdapter.prepareProjection = _prepareProjection;
+    /**
+     * Prepares the given sort into a MongoDB compatible format.
+     */
     MongoAdapter.prepareSort = _prepareSort;
+    /**
+     * Parses an execution context and transforms it into a MongoDB-compatible request.
+     *
+     * @param context - The execution context to parse.
+     * @returns A promise that resolves to the transformed request.
+     * @throws {@link TypeError} If the context transport is not 'http'.
+     * @throws {@link Error} If the operation is not compatible with MongoDB Adapter.
+     */
     async function parseRequest(context) {
         if (context.transport !== 'http') {
             throw new TypeError('MongoAdapter can parse only HttpContext');

package/adapter/mongo-patch-generator.d.ts

@@ -9,7 +9,19 @@ interface Context {
     arrayFilters?: Record<string, any>[];
     initArrayFields?: string[];
 }
+/**
+ * MongoPatchGenerator is responsible for generating MongoDB update patches from DTO objects.
+ * It handles nested objects, array operations ($push, $pull), and field unsetting.
+ */
 export declare class MongoPatchGenerator {
+    /**
+     * Generates a MongoDB update patch for the given data type and document.
+     *
+     * @param dataType - The data type of the entity being updated.
+     * @param doc - The patch DTO containing the updates.
+     * @param options - Optional configuration for patch generation.
+     * @returns An object containing the MongoDB update filter, array filters, and any array fields to initialize.
+     */
     generatePatch<T extends object>(dataType: ComplexType, doc: PatchDTO<T>, options?: MongoPatchGenerator.Options): {
         update: UpdateFilter<T>;
         arrayFilters?: Record<string, any>[];

package/adapter/mongo-patch-generator.js

@@ -1,6 +1,18 @@
 import { ComplexType } from '@opra/common';
 const FIELD_NAME_PATTERN = /^([-><*:])?(.+)$/;
+/**
+ * MongoPatchGenerator is responsible for generating MongoDB update patches from DTO objects.
+ * It handles nested objects, array operations ($push, $pull), and field unsetting.
+ */
 export class MongoPatchGenerator {
+    /**
+     * Generates a MongoDB update patch for the given data type and document.
+     *
+     * @param dataType - The data type of the entity being updated.
+     * @param doc - The patch DTO containing the updates.
+     * @param options - Optional configuration for patch generation.
+     * @returns An object containing the MongoDB update filter, array filters, and any array fields to initialize.
+     */
     generatePatch(dataType, doc, options) {
         const ctx = {};
         this._processComplexType(ctx, dataType, options?.currentPath || '', doc, options?.scope);
@@ -49,9 +61,9 @@ export class MongoPatchGenerator {
             field = dataType.findField(key, scope);
             if (field && !field.inScope(scope))
                 continue;
-            /** Field not found */
+            /* Field not found */
             if (!field) {
-                /** Additional fields will be updated */
+                /* Additional fields will be updated */
                 if (dataType.additionalFields) {
                     if (value === null) {
                         ctx.$unset = ctx.$unset || {};
@@ -61,7 +73,7 @@ export class MongoPatchGenerator {
                     else {
                         ctx.$set = ctx.$set || {};
                         if (dataType.additionalFields instanceof ComplexType) {
-                            /** Process nested object */
+                            /* Process nested object */
                             if (this._processComplexType(ctx, dataType.additionalFields, pathDot + key, value, scope)) {
                                 result = true;
                             }
@@ -73,7 +85,7 @@ export class MongoPatchGenerator {
                 }
                 continue;
             }
-            /** Unset field value if null */
+            /* Unset field value if null */
             if (value === null) {
                 ctx.$unset = ctx.$unset || {};
                 ctx.$unset[pathDot + field.name] = 1;
@@ -92,19 +104,19 @@ export class MongoPatchGenerator {
                         keyField = field.keyField || field.type.keyField;
                         if (keyField) {
                             for (let v of value) {
-                                /** Increase arrayIndex and determine a new name for array filter  */
+                                /* Increase arrayIndex and determine a new name for array filter  */
                                 arrayFilterName = 'f' + String(++arrayIndex);
-                                /** Extract key value from object */
+                                /* Extract key value from object */
                                 keyValue = v[keyField];
                                 if (keyValue == null)
                                     continue;
                                 v = { ...v };
-                                /** Remove key field from object */
+                                /* Remove key field from object */
                                 delete v[keyField];
-                                /** Process each object in array */
+                                /* Process each object in array */
                                 if (this._processComplexType(ctx, field.type, pathDot + field.name + `.$[${arrayFilterName}]`, v, scope)) {
                                     result = true;
-                                    /** Add array filter */
+                                    /* Add array filter */
                                     ctx.arrayFilters = ctx.arrayFilters || [];
                                     ctx.arrayFilters.unshift({
                                         [`${arrayFilterName}.${keyField}`]: keyValue,
@@ -118,7 +130,7 @@ export class MongoPatchGenerator {
                 else {
                     if (!(typeof value === 'object'))
                         continue;
-                    /** Process nested object */
+                    /* Process nested object */
                     if (this._processComplexType(ctx, field.type, pathDot + field.name, value, scope)) {
                         result = true;
                     }

package/adapter/prepare-filter.d.ts

@@ -1,13 +1,11 @@
 import mongodb from 'mongodb';
 import type { MongoAdapter } from './mongo-adapter.js';
 /**
- * Prepare the MongoDB filter based on the provided filters and options.
+ * Prepares the MongoDB filter based on the provided filters and options.
  *
- * @param {FilterInput|FilterInput[]} filters - The filter(s) to be applied.
- * @param {Object} [options] - Additional options.
- * @param {string} [options.fieldPrefix] - The prefix to be added to field names.
- *
- * @returns {mongodb.Filter<any>} - The prepared MongoDB filter.
+ * @param filters - The filter(s) to be applied. Can be a single filter or an array of filters.
+ * @param options - Additional options.
+ * @returns The prepared MongoDB filter, or `undefined` if no filters are provided.
  */
 export default function prepareFilter<T = any>(filters: MongoAdapter.FilterInput<T> | MongoAdapter.FilterInput<T>[], options?: {
     fieldPrefix?: string;

package/adapter/prepare-filter.js

@@ -10,13 +10,11 @@ const opMap = {
     '!in': '$nin',
 };
 /**
- * Prepare the MongoDB filter based on the provided filters and options.
+ * Prepares the MongoDB filter based on the provided filters and options.
  *
- * @param {FilterInput|FilterInput[]} filters - The filter(s) to be applied.
- * @param {Object} [options] - Additional options.
- * @param {string} [options.fieldPrefix] - The prefix to be added to field names.
- *
- * @returns {mongodb.Filter<any>} - The prepared MongoDB filter.
+ * @param filters - The filter(s) to be applied. Can be a single filter or an array of filters.
+ * @param options - Additional options.
+ * @returns The prepared MongoDB filter, or `undefined` if no filters are provided.
  */
 export default function prepareFilter(filters, options) {
     const filtersArray = Array.isArray(filters) ? filters : [filters];

package/adapter/prepare-key-values.d.ts

@@ -1 +1,10 @@
+/**
+ * Prepares the MongoDB primary key query object from the given key values.
+ *
+ * @param keyValue - The value of the primary key, or an object containing multiple key values.
+ * @param primaryKey - An optional array of field names that form the primary key. Defaults to ['_id'].
+ * @returns A record object representing the MongoDB primary key query.
+ * @throws {@link TypeError} If a composite key is required but an object is not provided.
+ * @throws {@link Error} If a required key field is missing in the input object.
+ */
 export default function prepareKeyValues(keyValue: any, primaryKey?: string[]): Record<string, any>;

package/adapter/prepare-key-values.js

@@ -1,5 +1,14 @@
 import { isPlainObject } from '@jsopen/objects';
 const defaultPrimaryKey = ['_id'];
+/**
+ * Prepares the MongoDB primary key query object from the given key values.
+ *
+ * @param keyValue - The value of the primary key, or an object containing multiple key values.
+ * @param primaryKey - An optional array of field names that form the primary key. Defaults to ['_id'].
+ * @returns A record object representing the MongoDB primary key query.
+ * @throws {@link TypeError} If a composite key is required but an object is not provided.
+ * @throws {@link Error} If a required key field is missing in the input object.
+ */
 export default function prepareKeyValues(keyValue, primaryKey) {
     primaryKey = primaryKey || defaultPrimaryKey;
     const b = isPlainObject(keyValue);

package/adapter/prepare-projection.d.ts

@@ -1,4 +1,12 @@
 import { ComplexType, FieldsProjection } from '@opra/common';
 import mongodb, { type Document } from 'mongodb';
+/**
+ * Prepares the MongoDB projection object based on the data type and requested projection.
+ *
+ * @param dataType - The data type of the entity.
+ * @param projection - The requested projection (string, array of strings, Document, or '*').
+ * @param scope - Optional scope for field visibility.
+ * @returns The prepared MongoDB projection document, or `undefined`.
+ */
 export default function prepareProjection(dataType: ComplexType, projection?: string | string[] | Document | '*', scope?: string): mongodb.Document | undefined;
 export declare function prepare(dataType: ComplexType, target: mongodb.Document, projection?: FieldsProjection, scope?: string): void;

package/adapter/prepare-projection.js

@@ -1,4 +1,12 @@
 import { ComplexType, parseFieldsProjection, } from '@opra/common';
+/**
+ * Prepares the MongoDB projection object based on the data type and requested projection.
+ *
+ * @param dataType - The data type of the entity.
+ * @param projection - The requested projection (string, array of strings, Document, or '*').
+ * @param scope - Optional scope for field visibility.
+ * @returns The prepared MongoDB projection document, or `undefined`.
+ */
 export default function prepareProjection(dataType, projection, scope) {
     if (projection === '*')
         return undefined;
@@ -20,18 +28,18 @@ export function prepare(dataType, target, projection, scope) {
     let fieldName;
     let field;
     let k;
-    /** Add fields from data type */
+    /* Add fields from data type */
     for (field of dataType.fields(scope)) {
         fieldName = field.name;
         k = fieldName.toLowerCase();
         projectionKeysSet.delete(k);
         const p = projection?.[k];
         if (
-        /** Ignore if field is omitted */
+        /* Ignore if field is omitted */
         p?.sign === '-' ||
-            /** Ignore if defaultFields is false and field is not in projection */
+            /* Ignore if defaultFields is false and field is not in projection */
             (!defaultFields && !p) ||
-            /** Ignore if defaultFields is true and fields is exclusive */
+            /* Ignore if defaultFields is true and fields is exclusive */
             (defaultFields && field.exclusive && !p)) {
             continue;
         }
@@ -43,7 +51,7 @@ export function prepare(dataType, target, projection, scope) {
         }
         target[fieldName] = 1;
     }
-    /** Add additional fields */
+    /* Add additional fields */
     if (dataType.additionalFields) {
         for (k of projectionKeysSet.values()) {
             const n = projection?.[k];

package/adapter/prepare-sort.d.ts

@@ -1,2 +1,8 @@
 import mongodb from 'mongodb';
+/**
+ * Prepares the MongoDB sort object from an array of sort strings.
+ *
+ * @param sort - An array of strings representing the sort order (e.g., ['+name', '-age']).
+ * @returns The prepared MongoDB sort object, or `undefined` if no sort is provided.
+ */
 export default function prepareSort(sort?: string[]): mongodb.Sort | undefined;

package/adapter/prepare-sort.js

@@ -1,3 +1,9 @@
+/**
+ * Prepares the MongoDB sort object from an array of sort strings.
+ *
+ * @param sort - An array of strings representing the sort order (e.g., ['+name', '-age']).
+ * @returns The prepared MongoDB sort object, or `undefined` if no sort is provided.
+ */
 export default function prepareSort(sort) {
     if (!(sort && sort.length))
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/mongodb",
-  "version": "1.26.2",
+  "version": "1.26.4",
   "description": "Opra MongoDB adapter package",
   "author": "Panates",
   "license": "MIT",
@@ -10,9 +10,9 @@
     "valgen": "^6.0.3"
   },
   "peerDependencies": {
-    "@opra/common": "^1.26.2",
-    "@opra/core": "^1.26.2",
-    "@opra/http": "^1.26.2",
+    "@opra/common": "^1.26.4",
+    "@opra/core": "^1.26.4",
+    "@opra/http": "^1.26.4",
     "mongodb": "^7.0.0"
   },
   "exports": {