@andrewscwei/mongodb-odm - npm Package Compare versions

Comparing version 0.77.0 to 0.78.0

build/core/aggregation/lookup.d.ts

@@ -10,25 +10,53 @@ import { AnyProps } from '../../types';
 /**
- * Defines fields to perform lookup on used by `lookupStageFactory`. These fields must be references
- * (i.e. model name as foreign keys) to another model. The fields are represented by the keys in
- * this object. The accepted values of the keys are `true` or another object for recursive lookup of
- * the reference model's foreign keys. If the value is simply `true`, lookup will only be performed
- * on the immediate foreign key, all of its inner foreign keys will be ignored. Specs can be nested.
- * `$unwind` is immediately followed after the generated `$lookup`.
+ * Defines fields to perform lookup on in the `lookupStageFactory` method. These fields, as
+ * represented by the keys, must be references (i.e. model names as foreign keys) to other models.
+ * The accepted values of the keys are `true` or a `LookupStageSingleFieldFactorySpecs` object that
+ * specifies custom parameters for the `$lookup` stage. If the value is simply `true`, the `$lookup`
+ * stage will use default parameters.
+ *
+ * @see {@link LookupStageSingleFieldFactorySpecs}
  */
 export declare type LookupStageFactorySpecs = {
-    [refField: string]: boolean | LookupStageFactorySpecs;
+    [refField: string]: boolean | LookupStageSingleFieldFactorySpecs;
 };
+/**
+ * Specifies parameters that define how the `$lookup` stage should be generated for a single field.
+ */
+export declare type LookupStageSingleFieldFactorySpecs = {
+    /**
+     * Specifies the `foreignField` parameter of the `$lookup` stage, which is the field of the target
+     * collection to perform the lookup on. If unspecified, this defaults to `_id`.
+     */
+    foreign?: string;
+    /**
+     * Specifies if the looked up field should be an array. Set this to `false` to generate an
+     * `$unwind` stage following the `$lookup` stage in order to convert the results array to a single
+     * result.
+     */
+    isArray?: boolean;
+    /**
+     * Specifies the `LookupStageFactorySpecs` to apply to this field after the immediate  is
+     * complete, to further look up nested reference fields.
+     *
+     * @see {@link LookupStageFactorySpecs}
+     */
+    lookup?: LookupStageFactorySpecs;
+    /**
+     * Specifies the `as` parameter of the `$lookup` stage.
+     */
+    as?: string;
+};
 export declare type LookupStageFactoryOptions = {
     /**
-    * Prefix for current attributes to look up.
-    */
+     * Prefix to prepend fields before the lookup.
+     */
     fromPrefix?: string;
     /**
-    * Prefix for looked up attributes to save to.
-    */
+     * Prefix to preprend fields after the lookup.
+     */
     toPrefix?: string;
 };
 /**
- * Generates a series of `$lookup` and `$unwind` stages for a collection to be used in an
- * aggregation pipeline. The `specs` define which fields to look up. Each field will be unwinded
+ * Generates a series of `$lookup` and (if needed) `$unwind` stages for a collection to be used in
+ * an aggregation pipeline. The `specs` define which fields to look up. Each field will be unwinded
  * accordingly so the result of the new field is the looked up document(s) itself.
@@ -41,4 +69,4 @@ *
  *
- * @returns An abstract aggregation pipeline containing the generated series of `$lookup` and
- *          `$unwind` stages.
+ * @returns An abstract aggregation pipeline containing the generated series of `$lookup` and (if
+ *          needed) `$unwind` stages.
  *
@@ -71,2 +99,2 @@ * @example
  */
-export declare function lookupStageFactory<P extends AnyProps = AnyProps>(schema: Schema<P>, specs: LookupStageFactorySpecs, { fromPrefix, toPrefix, }?: LookupStageFactoryOptions): (LookupStage | UnwindStage)[];
+export declare function lookupStageFactory<P extends AnyProps = AnyProps>(schema: Schema<P>, specs: LookupStageFactorySpecs, options?: LookupStageFactoryOptions): (LookupStage | UnwindStage)[];

build/core/aggregation/lookup.js

@@ -26,3 +26,2 @@ "use strict";
 exports.lookupStageFactory = void 0;
-const lodash_1 = __importDefault(require("lodash"));
 const db = __importStar(require("../.."));
@@ -32,4 +31,4 @@ const fieldPath_1 = __importDefault(require("../../utils/fieldPath"));
 /**
- * Generates a series of `$lookup` and `$unwind` stages for a collection to be used in an
- * aggregation pipeline. The `specs` define which fields to look up. Each field will be unwinded
+ * Generates a series of `$lookup` and (if needed) `$unwind` stages for a collection to be used in
+ * an aggregation pipeline. The `specs` define which fields to look up. Each field will be unwinded
  * accordingly so the result of the new field is the looked up document(s) itself.
@@ -42,4 +41,4 @@ *
  *
- * @returns An abstract aggregation pipeline containing the generated series of `$lookup` and
- *          `$unwind` stages.
+ * @returns An abstract aggregation pipeline containing the generated series of `$lookup` and (if
+ *          needed) `$unwind` stages.
  *
@@ -72,48 +71,53 @@ * @example
  */
-function lookupStageFactory(schema, specs, { fromPrefix = '', toPrefix = '', } = {}) {
-    const fields = schema.fields;
-    let pipe = [];
-    for (const key in specs) {
-        if (!specs.hasOwnProperty(key))
+function lookupStageFactory(schema, specs, options = {}) {
+    let out = [];
+    for (const field in specs) {
+        if (!specs.hasOwnProperty(field))
             continue;
-        const spec = specs[key];
-        const isShallowLookup = lodash_1.default.isBoolean(spec);
-        const isDeepLookup = lodash_1.default.isPlainObject(spec);
-        if (!isShallowLookup && !isDeepLookup)
-            throw new TypeError(`[lookup(${schema}, ${specs}, ${{ fromPrefix, toPrefix }})] Invalid populate properties.`);
+        const spec = specs[field];
         if (spec === false)
             continue;
-        const targetModel = fields[key] && fields[key].ref;
-        if (!targetModel)
-            throw new Error(`[lookup(${schema}, ${specs}, ${{ fromPrefix, toPrefix }})] The field to populate does not have a reference model specified in the schema.`);
-        const targetSchema = db.getModel(targetModel).schema;
-        if (!targetSchema)
-            throw new Error(`[lookup(${schema}, ${specs}, ${{ fromPrefix, toPrefix }})] Unable to find the model schema corresponding to the field to populate.`);
-        // Look up the reference field.
-        pipe.push({
-            $lookup: {
-                from: `${targetSchema.collection}`,
-                localField: (0, prefixed_1.default)(key, fromPrefix),
-                foreignField: '_id',
-                as: (0, prefixed_1.default)(key, toPrefix),
-            },
-        });
-        // Unwind the results of the lookup.
-        pipe.push({
+        out = out.concat(lookupStageSingleFieldFactory(schema, field, spec === true ? undefined : spec, options));
+    }
+    return out;
+}
+exports.lookupStageFactory = lookupStageFactory;
+function lookupStageSingleFieldFactory(schema, field, { as, foreign, isArray, lookup, } = {}, { fromPrefix = '', toPrefix = '', } = {}) {
+    let out = [];
+    const fieldDescriptor = schema.fields[field];
+    if (!fieldDescriptor)
+        throw new Error(`Failed to generate $lookup stage: the field "${field}" does not exist in the schema for collection "${schema.collection}"`);
+    const targetModel = fieldDescriptor.ref;
+    if (!targetModel)
+        throw new Error(`Failed to generate $lookup stage: the field "${field}" does not have a reference model specified in the schema for collection "${schema.collection}"`);
+    const targetSchema = db.getModel(targetModel).schema;
+    if (!targetSchema)
+        throw new Error(`Failed to generate $lookup stage: unable to find the schema for to the reference model ${targetModel}.`);
+    // Look up the reference field.
+    out.push({
+        $lookup: {
+            as: (0, prefixed_1.default)(as !== null && as !== void 0 ? as : field, toPrefix),
+            foreignField: foreign !== null && foreign !== void 0 ? foreign : '_id',
+            from: `${targetSchema.collection}`,
+            localField: (0, prefixed_1.default)(field, fromPrefix),
+        },
+    });
+    // Unwind the results of the lookup if applicable.
+    if (isArray !== true) {
+        out.push({
             $unwind: {
-                path: (0, fieldPath_1.default)(key, toPrefix),
+                path: (0, fieldPath_1.default)(as !== null && as !== void 0 ? as : field, toPrefix),
                 preserveNullAndEmptyArrays: true,
             },
         });
-        // Recursively look up reference fields.
-        if (isDeepLookup) {
-            pipe = pipe.concat(lookupStageFactory(targetSchema, spec, {
-                fromPrefix: (0, prefixed_1.default)(key, toPrefix),
-                toPrefix: (0, prefixed_1.default)(key, toPrefix),
-            }));
-        }
     }
-    return pipe;
+    // Recursively look up reference fields.
+    if (lookup) {
+        out = out.concat(lookupStageFactory(targetSchema, lookup, {
+            fromPrefix: (0, prefixed_1.default)(field, toPrefix),
+            toPrefix: (0, prefixed_1.default)(field, toPrefix),
+        }));
+    }
+    return out;
 }
-exports.lookupStageFactory = lookupStageFactory;
 //# sourceMappingURL=lookup.js.map

build/core/modelFactory.js

@@ -699,5 +699,7 @@ "use strict";
         },
-        /** @inheritdoc */
+        /** @see {@link Model.schema} */
         _a.schema = schema,
-        /** @inheritdoc */
+        /**
+         * Dictionary of random value generators for this model's props.
+         */
         _a.randomProps = {},
@@ -704,0 +706,0 @@ /** @inheritdoc */

package.json

 {
   "name": "@andrewscwei/mongodb-odm",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "ODM for MongoDB",
@@ -47,3 +47,3 @@ "main": "build/index.js",
     "dotenv": "^10.0.0",
-    "eslint": "^8.4.1",
+    "eslint": "^8.5.0",
     "faker": "^5.5.3",
@@ -50,0 +50,0 @@ "mocha": "^9.1.3",

README.md

 # mongodb-odm [![npm](https://img.shields.io/npm/v/@andrewscwei/mongodb-odm.svg)](https://www.npmjs.com/package/@andrewscwei/mongodb-odm) [![CI](https://github.com/andrewscwei/node-mongodb-odm/workflows/CI/badge.svg)](https://github.com/andrewscwei/node-mongodb-odm/actions?query=workflow%3ACI) [![CD](https://github.com/andrewscwei/node-mongodb-odm/workflows/CD/badge.svg)](https://github.com/andrewscwei/node-mongodb-odm/actions?query=workflow%3ACD)
 
-Simple MonogDB ODM library written in TypeScript. This module is opinionated, has limited features and has an ever-changing API. Use with caution.
+Simple MonogDB ODM library written in TypeScript.
 
@@ -12,1 +12,5 @@ ## Features
 - CRUD event hooks
+
+## Disclaimer
+
+Features of this module are driven by personal projects and are expected to have timely changes to their API. Use with caution.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

371274

increased by0.77%

Lines of code

4002

increased by0.86%

Number of lines in readme file

16

increased by33.33%

No dependency changes