@bedrockio/model 0.4.2 → 0.5.0

package/README.md

@@ -756,13 +756,7 @@ complex situations this can easily be a lot of overhead. The include module
 attempts to streamline this process by adding an `include` method to queries:
 
 ```js
-const product = await Product.findById(id).include([
-  'name',
-  'shop.email',
-  'shop.user.name',
-  'shop.user.address.line1',
-  'shop.customers.tags',
-]);
+const product = await Product.findById(id).include('shop.user.customers');
 ```
 
 This method accepts a string or array of strings that will map to a `populate`
@@ -771,20 +765,21 @@ call that can be far more complex:
 ```js
 const product = await Product.findById(id).populate([
   {
-    select: ['name'],
+    select: [],
     populate: [
       {
         path: 'shop',
-        select: ['email'],
+        select: [],
         populate: [
           {
             path: 'user',
-            select: ['name', 'address.line1'],
+            select: [],
             populate: [],
           },
           {
             path: 'customers',
-            select: ['tags'],
+            select: [],
+            populate: [],
           },
         ],
       },
@@ -794,11 +789,131 @@ const product = await Product.findById(id).populate([
 ```
 
 In addition to brevity, one major advantage of using `include` is that the
-caller does not need to know whether the documents are subdocuments or foreign
+caller does not need to know whether the path contains subdocuments or foreign
 references. As Bedrock has knowledge of the schemas, it is able to build the
 appropriate call to `populate` for you.
 
-#### Excluding Fields
+#### Exclusive Fields
+
+By default, arguments to `include` are for population. However often field
+projection (selection) is also desired to avoid excessive data transfer. The `^`
+token can be used here to build the `select` option to populates:
+
+```js
+const product = await Product.findById(id).include([
+  '^name',
+  '^shop.name',
+  '^shop.user.name',
+]);
+```
+
+This will map to a selective inclusion of fields in the `populate` call:
+
+```js
+const product = await Product.findById(id).populate([
+  {
+    select: ['name', 'shop'],
+    populate: [
+      {
+        path: 'shop',
+        select: ['name', 'user'],
+        populate: [
+          {
+            path: 'user',
+            select: ['name'],
+            populate: [],
+          },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+The resulting data will include only the specified fields:
+
+```json
+{
+  "name": "Product Name",
+  "shop": {
+    "name": "Shop Name",
+    "user": {
+      "name": "User Name"
+    }
+  }
+}
+```
+
+Note that the exclusive operator can be used anywhere in the path. The exclusion
+(select) will be applied at the depth in which it is specified:
+
+Example 1:
+
+- Top level exclusion
+- Only exact field returned.
+
+```js
+await Product.findById(id).include('^shop.user.name').
+```
+
+```json
+{
+  "shop": {
+    "user": {
+      "name": "User Name"
+    }
+  }
+}
+```
+
+Example 2:
+
+- Mid-level exclusion.
+- Top level fields included, mid-level begins exclusion.
+
+```js
+await Product.findById(id).include('shop.^user.name').
+```
+
+```json
+{
+  "name": "Product Name",
+  "cost": 10,
+  // etc
+  "shop": {
+    "user": {
+      "name": "User Name"
+    }
+  }
+}
+```
+
+Example 3:
+
+- Final level exclusion.
+- All fields returned except in final `user` population.
+
+```js
+await Product.findById(id).include('shop.user.^name').
+```
+
+```json
+{
+  "name": "Product Name",
+  "cost": 10,
+  // etc
+  "shop": {
+    "name": "Shop Name",
+    "rating": 5,
+    // etc
+    "user": {
+      "name": "User Name"
+    }
+  }
+}
+```
+
+#### Excluded Fields
 
 Fields can be excluded rather than included using `-`:
 
@@ -813,6 +928,7 @@ The above will return all fields except `profile`. Note that:
 - An excluded field on a foreign reference will implicitly be populated. This
   means that passing `-profile.name` where `profile` is a foreign field will
   populate `profile` but exclude `name`.
+- Note that `-` can only be used at the beginning of the path.
 
 #### Wildcards
 
@@ -820,35 +936,43 @@ Multiple fields can be selected using wildcards:
 
 - `*` - Matches anything except `.`.
 - `**` - Matches anything including `.`.
+- Note that the use of wildcards implies that other fields are excluded.
+
+Example 1: Single wildcard
 
 ```js
-// Assuming a schema of:
-// {
-//   "firstName": "String"
-//   "lastName": "String"
-// }
 const user = await User.findById(id).include('*Name');
 ```
 
-The example above will select both `firstName` and `lastName`.
+```json
+{
+  "firstName": "Frank",
+  "lastName": "Reynolds"
+  // Other fields excluded.
+}
+```
+
+Example 2: Double wildcard
 
 ```js
-// Assuming a schema of:
-// {
-//   "profile1": {
-//     "address": {
-//       "phone": "String"
-//     }
-//   },
-//   "profile2": {
-//     "address": {
-//       "phone": "String"
-//     }
-//   }
-// }
 const user = await User.findById(id).include('**.phone');
 ```
 
+```json
+{
+  "profile1": {
+    "address": {
+      "phone": "String"
+    }
+  },
+  "profile2": {
+    "address": {
+      "phone": "String"
+    }
+  }
+}
+```
+
 This example above will select both `profile1.address.phone` and
 `profile2.address.phone`. Compare this to `*` which will not match here.
 

package/dist/cjs/include.js

@@ -186,13 +186,19 @@ function nodeToPopulates(node) {
   const select = [];
   const populate = [];
   for (let [key, value] of Object.entries(node)) {
+    if (key.startsWith('-')) {
+      select.push(key);
+      continue;
+    }
+    if (key.startsWith('^')) {
+      key = key.slice(1);
+      select.push(key);
+    }
     if (value) {
       populate.push({
         path: key,
         ...nodeToPopulates(value)
       });
-    } else {
-      select.push(key);
     }
   }
   return {
@@ -212,24 +218,17 @@ function pathsToNode(paths, modelName) {
     if (typeof str !== 'string') {
       throw new Error('Provided include path was not as string.');
     }
-    let exclude = false;
-    if (str.startsWith('-')) {
-      exclude = true;
-      str = str.slice(1);
-    }
     setNodePath(node, {
       path: str.split('.'),
-      modelName,
-      exclude
+      modelName
     });
   }
   return node;
 }
 function setNodePath(node, options) {
   const {
-    path,
     modelName,
-    exclude,
+    path: fullPath,
     depth = 0
   } = options;
   if (depth > _const.POPULATE_MAX_DEPTH) {
@@ -239,50 +238,104 @@ function setNodePath(node, options) {
   if (!schema) {
     throw new Error(`Could not derive schema for ${modelName}.`);
   }
+  let {
+    excluded = false,
+    exclusive = false
+  } = options;
   const parts = [];
-  for (let part of path) {
+  for (let part of fullPath) {
+    if (part.startsWith('-')) {
+      // Field is excluded. Note that this occurs only at
+      // top level and should take precedence:
+      // -name      -> "name" is excluded
+      // -user.name -> "user" is populated but "name" is
+      //               excluded
+      excluded = true;
+      part = part.slice(1);
+    } else if (!excluded && part.startsWith('^')) {
+      // Field is exclusive. Note that this can happen at
+      // any part of the path:
+      // ^name      -> "name" is exclusively selected
+      // user.^name -> "user" is populated with "name"
+      //                exclusively selected within
+      // ^user.name -> "user" is exclusively selected
+      //               ("name" is redundant)
+      exclusive = true;
+      part = part.slice(1);
+    } else if (!excluded && part.includes('*')) {
+      // Wildcards in field implies exclusion, but only
+      // if path is not already excluded:
+      // *name       -> "firstName" and "lastName" are exclusively
+      //                selected
+      // user.*name  -> "user" is populated, "user.firstName"
+      //                and "user.lastName" are exclusively selected
+      // -*name      -> "firstName" and "lastName" are excluded
+      // -user.*name -> "user" is populated but "user.firstName"
+      //                and "user.lastName" are excluded
+      exclusive = true;
+    }
     parts.push(part);
-    const str = parts.join('.');
-    const isExact = parts.length === path.length;
+    const isExact = parts.length === fullPath.length;
     let halt = false;
-    for (let [key, type] of resolvePaths(schema, str)) {
+    for (let [path, type] of resolvePaths(schema, parts.join('.'))) {
+      // The exclusive key.
+      const eKey = '^' + path;
+      // The negative (excluded) key.
+      const nKey = '-' + path;
+      let key = path;
+      if (exclusive && !node[key]) {
+        // Add the exclusive flag if the node
+        // has not already been included.
+        key = eKey;
+      } else if (!exclusive && node[eKey]) {
+        // If the node has already been marked exclusive
+        // and another include overrides it, then we need
+        // to move that node over to be inclusive. This
+        // step is needed as includes should always take
+        // priority over exclusion regardless of the order.
+        node[key] = node[eKey];
+        delete node[eKey];
+      } else if (excluded && isExact) {
+        // Only flag the node as excluded if the path is an
+        // exact match:
+        // -name      -> Exclude "name" field.
+        // -user.name -> Exclude "user.name" field, however this
+        //               implies that we must populate "user" so
+        //               continue traversing and flag for include.
+        key = nKey;
+      }
       if (type === 'real') {
-        const field = (0, _utils.getInnerField)(schema.obj, key);
-        // Only exclude the field if the match is exact, ie:
-        // -name - Exclude "name"
-        // -user.name - Implies population of "user" but exclude "user.name",
-        //  so continue traversing into object when part is "user".
-        if (isExact && exclude) {
-          node['-' + key] = LEAF_NODE;
-        } else if (field.ref) {
+        const field = (0, _utils.getInnerField)(schema.obj, path);
+        if (field.ref) {
           node[key] ||= {};
           setNodePath(node[key], {
             modelName: field.ref,
-            path: path.slice(parts.length),
+            path: fullPath.slice(parts.length),
             depth: depth + 1,
-            exclude
+            excluded,
+            exclusive
           });
           halt = true;
         } else if ((0, _utils.isSchemaTypedef)(field)) {
           node[key] = LEAF_NODE;
         }
       } else if (type === 'virtual') {
-        const virtual = schema.virtual(key);
+        const virtual = schema.virtual(path);
         // @ts-ignore
         const ref = virtual.options.ref;
         if (ref) {
           node[key] ||= {};
           setNodePath(node[key], {
-            // @ts-ignore
             modelName: ref,
-            path: path.slice(parts.length),
+            path: fullPath.slice(parts.length),
             depth: depth + 1,
-            exclude
+            excluded,
+            exclusive
           });
         }
         halt = true;
       } else if (type !== 'nested') {
-        throw new Error(`Unknown path on ${modelName}: ${key}.`);
+        throw new Error(`Unknown path on ${modelName}: ${path}.`);
       }
     }
     if (halt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrockio/model",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {

package/src/include.js

@@ -175,13 +175,19 @@ function nodeToPopulates(node) {
   const select = [];
   const populate = [];
   for (let [key, value] of Object.entries(node)) {
+    if (key.startsWith('-')) {
+      select.push(key);
+      continue;
+    }
+    if (key.startsWith('^')) {
+      key = key.slice(1);
+      select.push(key);
+    }
     if (value) {
       populate.push({
         path: key,
         ...nodeToPopulates(value),
       });
-    } else {
-      select.push(key);
     }
   }
   return {
@@ -202,75 +208,127 @@ function pathsToNode(paths, modelName) {
     if (typeof str !== 'string') {
       throw new Error('Provided include path was not as string.');
     }
-    let exclude = false;
-    if (str.startsWith('-')) {
-      exclude = true;
-      str = str.slice(1);
-    }
     setNodePath(node, {
       path: str.split('.'),
       modelName,
-      exclude,
     });
   }
   return node;
 }
 
 function setNodePath(node, options) {
-  const { path, modelName, exclude, depth = 0 } = options;
+  const { modelName, path: fullPath, depth = 0 } = options;
   if (depth > POPULATE_MAX_DEPTH) {
     throw new Error(`Cannot populate more than ${POPULATE_MAX_DEPTH} levels.`);
   }
+
   const schema = mongoose.models[modelName]?.schema;
   if (!schema) {
     throw new Error(`Could not derive schema for ${modelName}.`);
   }
+
+  let { excluded = false, exclusive = false } = options;
+
   const parts = [];
-  for (let part of path) {
+  for (let part of fullPath) {
+    if (part.startsWith('-')) {
+      // Field is excluded. Note that this occurs only at
+      // top level and should take precedence:
+      // -name      -> "name" is excluded
+      // -user.name -> "user" is populated but "name" is
+      //               excluded
+      excluded = true;
+      part = part.slice(1);
+    } else if (!excluded && part.startsWith('^')) {
+      // Field is exclusive. Note that this can happen at
+      // any part of the path:
+      // ^name      -> "name" is exclusively selected
+      // user.^name -> "user" is populated with "name"
+      //                exclusively selected within
+      // ^user.name -> "user" is exclusively selected
+      //               ("name" is redundant)
+      exclusive = true;
+      part = part.slice(1);
+    } else if (!excluded && part.includes('*')) {
+      // Wildcards in field implies exclusion, but only
+      // if path is not already excluded:
+      // *name       -> "firstName" and "lastName" are exclusively
+      //                selected
+      // user.*name  -> "user" is populated, "user.firstName"
+      //                and "user.lastName" are exclusively selected
+      // -*name      -> "firstName" and "lastName" are excluded
+      // -user.*name -> "user" is populated but "user.firstName"
+      //                and "user.lastName" are excluded
+      exclusive = true;
+    }
+
     parts.push(part);
-    const str = parts.join('.');
-    const isExact = parts.length === path.length;
+    const isExact = parts.length === fullPath.length;
+
     let halt = false;
 
-    for (let [key, type] of resolvePaths(schema, str)) {
+    for (let [path, type] of resolvePaths(schema, parts.join('.'))) {
+      // The exclusive key.
+      const eKey = '^' + path;
+      // The negative (excluded) key.
+      const nKey = '-' + path;
+
+      let key = path;
+      if (exclusive && !node[key]) {
+        // Add the exclusive flag if the node
+        // has not already been included.
+        key = eKey;
+      } else if (!exclusive && node[eKey]) {
+        // If the node has already been marked exclusive
+        // and another include overrides it, then we need
+        // to move that node over to be inclusive. This
+        // step is needed as includes should always take
+        // priority over exclusion regardless of the order.
+        node[key] = node[eKey];
+        delete node[eKey];
+      } else if (excluded && isExact) {
+        // Only flag the node as excluded if the path is an
+        // exact match:
+        // -name      -> Exclude "name" field.
+        // -user.name -> Exclude "user.name" field, however this
+        //               implies that we must populate "user" so
+        //               continue traversing and flag for include.
+        key = nKey;
+      }
+
       if (type === 'real') {
-        const field = getInnerField(schema.obj, key);
-        // Only exclude the field if the match is exact, ie:
-        // -name - Exclude "name"
-        // -user.name - Implies population of "user" but exclude "user.name",
-        //  so continue traversing into object when part is "user".
-        if (isExact && exclude) {
-          node['-' + key] = LEAF_NODE;
-        } else if (field.ref) {
+        const field = getInnerField(schema.obj, path);
+        if (field.ref) {
           node[key] ||= {};
           setNodePath(node[key], {
             modelName: field.ref,
-            path: path.slice(parts.length),
+            path: fullPath.slice(parts.length),
             depth: depth + 1,
-            exclude,
+            excluded,
+            exclusive,
           });
           halt = true;
         } else if (isSchemaTypedef(field)) {
           node[key] = LEAF_NODE;
         }
       } else if (type === 'virtual') {
-        const virtual = schema.virtual(key);
+        const virtual = schema.virtual(path);
         // @ts-ignore
         const ref = virtual.options.ref;
 
         if (ref) {
           node[key] ||= {};
           setNodePath(node[key], {
-            // @ts-ignore
             modelName: ref,
-            path: path.slice(parts.length),
+            path: fullPath.slice(parts.length),
             depth: depth + 1,
-            exclude,
+            excluded,
+            exclusive,
           });
         }
         halt = true;
       } else if (type !== 'nested') {
-        throw new Error(`Unknown path on ${modelName}: ${key}.`);
+        throw new Error(`Unknown path on ${modelName}: ${path}.`);
       }
     }