@bedrockio/model 0.2.17 → 0.2.19

package/README.md

@@ -11,7 +11,7 @@ Bedrock utilities for model creation.
   - [Scopes](#scopes)
   - [Tuples](#tuples)
   - [Array Extensions](#array-extensions)
-- [Features](#features)
+- [Modules](#modules)
   - [Soft Delete](#soft-delete)
   - [Validation](#validation)
   - [Search](#search)
@@ -352,7 +352,7 @@ unfortunately cannot be disambiguated in this case.
 
 This will manually create a new nested subschema.
 
-## Features
+## Modules
 
 ### Soft Delete
 
@@ -531,8 +531,6 @@ The method takes the following options:
 - `include` - Allows [include](#includes) based population.
 - `keyword` - A keyword to perform a [keyword search](#keyword-search).
 - `ids` - An array of document ids to search on.
-- `fields` - Used by [keyword search](#keyword-search). Generally for internal
-  use.
 
 Any other fields passed in will be forwarded to `find`. The return value
 contains the found documents in `data` and `meta` which contains metadata about
@@ -603,8 +601,8 @@ this feature a `fields` key must be present on the model definition:
 }
 ```
 
-This will use the `$or` operator to search on multiple fields. If `fields` is
-not defined then a Mongo text query will be attempted:
+This will use the `$or` operator to search on multiple fields. If the model has
+a text index applied, then a Mongo text query will be attempted:
 
 ```
 {
@@ -614,7 +612,118 @@ not defined then a Mongo text query will be attempted:
 }
 ```
 
-Note that this will fail unless a text index is defined on the model.
+#### Keyword Field Caching
+
+A common problem with search is filtering on fields belonging to foreign models.
+The search module helps to alleviate this issue by allowing a simple way to
+cache foreign fields on the model to allow filtering on them.
+
+```json
+{
+  "attributes": {
+    "user": {
+      "type": "ObjectId",
+      "ref": "User"
+    }
+  },
+  "search": {
+    "cache": {
+      "cachedUserName": {
+        "type": "String",
+        "path": "user.name"
+      }
+    },
+    "fields": ["cachedUserName"]
+  }
+}
+```
+
+The above example is equivalent to creating a field called `cachedUserName` and
+updating it when a document is saved:
+
+```js
+schema.add({
+  cachedUserName: 'String',
+});
+schema.pre('save', function () {
+  await this.populate('user');
+  this.cachedUserName = this.user.name;
+});
+```
+
+Specifying a foreign path in `fields` serves as a shortcut to manually defining
+the cached fields:
+
+```json
+// Equivalent to the above example.
+{
+  "attributes": {
+    "user": {
+      "type": "ObjectId",
+      "ref": "User"
+    }
+  },
+  "search": {
+    "fields": ["user.name"]
+  }
+}
+```
+
+##### Syncing Search Fields
+
+When first applying or making changes to defined cached search fields, existing
+documents will be out of sync. The static method `syncSearchFields` is provided
+to synchronize them:
+
+```js
+// Find and update any documents that do not have
+// existing cached fields. Generally called when
+// adding a cached field.
+await Model.syncSearchFields();
+
+// Force an update on ALL documents to resync their
+// cached fields. Generally called to force a cache
+// refresh.
+await Model.syncSearchFields({
+  force: true,
+});
+```
+
+##### Lazy Cached Fields
+
+Cached fields can be made lazy:
+
+```json
+{
+  "attributes": {
+    "user": {
+      "type": "ObjectId",
+      "ref": "User"
+    }
+  },
+  "search": {
+    "cache": {
+      "cachedUserName": {
+        "lazy": true,
+        "path": "user.name"
+      }
+    },
+    "fields": ["user.name"]
+  }
+}
+```
+
+Lazy cached fields will not update themselves once set. They can only be updated
+by forcing a sync:
+
+```js
+await Model.syncSearchFields({
+  force: true,
+});
+```
+
+Making fields lazy alleviates performance impact on writes and allows caches to
+be updated at another time (such as a background job).
 
 #### Search Validation
 
@@ -1019,12 +1128,15 @@ deletion. They are defined in the `onDelete` field of the model definition file:
     }
   },
   "onDelete": {
-    "clean": {
-      "local": "profile",
-      "foreign": {
-        "Shop": "owner"
+    "clean": [
+      {
+        "path": "profile"
+      },
+      {
+        "ref": "Shop",
+        "path": "owner"
       }
-    },
+    ],
     "errorOnReferenced": {
       "except": ["AuditEntry"]
     }
@@ -1035,12 +1147,13 @@ deletion. They are defined in the `onDelete` field of the model definition file:
 #### Clean
 
 `clean` determines other associated documents that will be deleted when the main
-document is deleted.
+document is deleted. It is defined as an array of operations that will be
+performed in order. Operations must contain either `path` or `paths`.
 
 #### Local References
 
-`clean.local` specifies local refs to delete. It may be a string or array of
-strings. In the above example:
+Operations that do not specify a `ref` are treated as local paths. In the above
+example:
 
 ```js
 user.delete();
@@ -1050,26 +1163,110 @@ await user.populate('profile');
 await user.profile.delete();
 ```
 
-#### Foreign Reference Cleanup
+#### Foreign References
 
-`clean.foreign` specifies foreign refs to delete. It is defined as an object
-that maps foreign `ref` names to their referencing field. In the above example:
+Operations that specify a `ref` are treated as foreign references. In the above
+example:
 
 ```js
 user.delete();
 
 // Will implicitly run:
-const shop = await Shop.find({
+const shops = await Shop.find({
   owner: user,
 });
-await shop.delete();
+for (let shop of shops) {
+  await shop.delete();
+}
+```
+
+#### Additional Filters
+
+Operations may filter on additional fields with `query`:
+
+```json
+// user.json
+{
+  "onDelete": {
+    "clean": [
+      {
+        "ref": "Shop",
+        "path": "owner",
+        "query": {
+          "status": "active"
+        }
+      }
+    ]
+  }
+}
+```
+
+In this example:
+
+```js
+user.delete();
+
+// Will implicitly run:
+const shops = await Shop.find({
+  status: 'active',
+  owner: user,
+});
+for (let shop of shops) {
+  await shop.delete();
+}
 ```
 
+Any query that can be serliazed as JSON is valid, however top-level `$or`
+operators have special behavior with multiple paths (see note below).
+
+#### Multiple Paths
+
+An operation that specified an array of `paths` will implicitly run an `$or`
+query:
+
+```json
+// user.json
+{
+  "onDelete": {
+    "clean": [
+      {
+        "ref": "Shop",
+        "path": ["owner", "administrator"]
+      }
+    ]
+  }
+}
+```
+
+In this example:
+
+```js
+user.delete();
+
+// Will implicitly run:
+const shops = await Shop.find({
+  $or: [
+    {
+      owner: user,
+    },
+    {
+      administrator: user,
+    },
+  ],
+});
+for (let shop of shops) {
+  await shop.delete();
+}
+```
+
+> [!WARNING] The ability to run an `$and` query with multiple paths is currently
+> not implemented.
+
 #### Erroring on Delete
 
 The `errorOnReferenced` field helps to prevent orphaned references by defining
 if and how the `delete` method will error if it is being referenced by another
-foreign document. In the above example:
+foreign document. In the top example:
 
 ```js
 user.delete();
@@ -1149,7 +1346,6 @@ const { createTestModel } = require('@bedrockio/model');
 const User = createTestModel({
   name: 'String',
 });
-mk;
 ```
 
 Note that a unique model name will be generated to prevent clashing with other

package/dist/cjs/delete-hooks.js

@@ -19,9 +19,8 @@ function applyDeleteHooks(schema, definition) {
   if (!deleteHooks) {
     return;
   }
-  const cleanLocal = validateCleanLocal(deleteHooks, schema);
-  const cleanForeign = validateCleanForeign(deleteHooks);
   const errorHook = validateError(deleteHooks);
+  const cleanHooks = validateCleanHooks(deleteHooks, schema);
   let references;
   const deleteFn = schema.methods.delete;
   const restoreFn = schema.methods.restore;
@@ -30,23 +29,20 @@ function applyDeleteHooks(schema, definition) {
       references ||= getAllReferences(this);
       await errorOnForeignReferences(this, {
         errorHook,
-        cleanForeign,
+        cleanHooks,
         references
       });
     }
     try {
-      await deleteLocalReferences(this, cleanLocal);
-      await deleteForeignReferences(this, cleanForeign);
+      await deleteReferences(this, cleanHooks);
     } catch (error) {
-      await restoreLocalReferences(this, cleanLocal);
-      await restoreForeignReferences(this);
+      await restoreReferences(this, cleanHooks);
       throw error;
     }
     await deleteFn.apply(this, arguments);
   });
   schema.method('restore', async function () {
-    await restoreLocalReferences(this, cleanLocal);
-    await restoreForeignReferences(this);
+    await restoreReferences(this, cleanHooks);
     await restoreFn.apply(this, arguments);
   });
   schema.add({
@@ -59,49 +55,58 @@ function applyDeleteHooks(schema, definition) {
 
 // Clean Hook
 
-function validateCleanLocal(deleteHooks, schema) {
-  let {
-    local
-  } = deleteHooks.clean || {};
-  if (!local) {
-    return;
+function validateCleanHooks(deleteHooks, schema) {
+  const {
+    clean
+  } = deleteHooks;
+  if (!clean) {
+    return [];
   }
-  if (typeof local !== 'string' && !Array.isArray(local)) {
-    throw new Error('Local delete hook must be an array.');
+  if (!Array.isArray(clean)) {
+    throw new Error('Delete clean hook must be an array.');
   }
-  if (typeof local === 'string') {
-    local = [local];
+  for (let hook of clean) {
+    const {
+      ref,
+      path,
+      paths
+    } = hook;
+    if (path && typeof path !== 'string') {
+      throw new Error('Clean hook path must be a string.');
+    } else if (paths && !Array.isArray(paths)) {
+      throw new Error('Clean hook paths must be an array.');
+    } else if (!path && !paths) {
+      throw new Error('Clean hook must define either "path" or "paths".');
+    } else if (path && paths) {
+      throw new Error('Clean hook may not define both "path" or "paths".');
+    } else if (ref && typeof ref !== 'string') {
+      throw new Error('Clean hook ref must be a string.');
+    } else if (!ref) {
+      validateLocalCleanHook(hook, schema);
+    }
   }
-  for (let name of local) {
-    const pathType = schema.pathType(name);
-    if (pathType !== 'real') {
-      throw new Error(`Delete hook has invalid local reference "${name}".`);
+  return clean;
+}
+function validateLocalCleanHook(hook, schema) {
+  const paths = getHookPaths(hook);
+  for (let path of paths) {
+    if (schema.pathType(path) !== 'real') {
+      throw new Error(`Invalid reference in local delete hook: "${path}".`);
     }
   }
-  return local;
 }
-function validateCleanForeign(deleteHooks) {
+function getHookPaths(hook) {
   const {
-    foreign
-  } = deleteHooks.clean || {};
-  if (!foreign) {
-    return;
-  }
-  if (typeof foreign !== 'object') {
-    throw new Error('Foreign delete hook must be an object.');
-  }
-  for (let [modelName, arg] of Object.entries(foreign)) {
-    if (typeof arg === 'object') {
-      const {
-        $and,
-        $or
-      } = arg;
-      if ($and && $or) {
-        throw new Error(`Cannot define both $or and $and in a delete hook for model ${modelName}.`);
-      }
-    }
+    path,
+    paths
+  } = hook;
+  if (path) {
+    return [path];
+  } else if (paths) {
+    return paths;
+  } else {
+    return [];
   }
-  return foreign;
 }
 function validateError(deleteHooks) {
   let {
@@ -173,15 +178,21 @@ async function errorOnForeignReferences(doc, options) {
 }
 function referenceIsAllowed(model, options) {
   const {
-    cleanForeign = {}
+    modelName
+  } = model;
+  const {
+    cleanHooks
   } = options;
+  const hasCleanHook = cleanHooks.some(hook => {
+    return hook.ref === modelName;
+  });
+  if (hasCleanHook) {
+    return true;
+  }
   const {
     only,
     except
   } = options?.errorHook || {};
-  if (model.modelName in cleanForeign) {
-    return true;
-  }
   if (only) {
     return !only.includes(model.modelName);
   } else if (except) {
@@ -235,58 +246,61 @@ function getModelReferences(model, targetName) {
   return paths;
 }
 
-// Deletion
+// Delete
 
-async function deleteLocalReferences(doc, arr) {
-  if (!arr) {
-    return;
-  }
-  for (let name of arr) {
-    await doc.populate(name);
-    const value = doc.get(name);
-    if (!value) {
-      continue;
-    }
-    const arr = Array.isArray(value) ? value : [value];
-    for (let sub of arr) {
-      await sub.delete();
+async function deleteReferences(doc, hooks) {
+  for (let hook of hooks) {
+    if (hook.ref) {
+      await deleteForeignReferences(doc, hook);
+    } else {
+      await deleteLocalReferences(doc, hook);
     }
   }
 }
-async function deleteForeignReferences(doc, refs) {
-  if (!refs) {
-    return;
-  }
+async function deleteForeignReferences(doc, hook) {
+  const {
+    ref,
+    path,
+    paths,
+    query
+  } = hook;
   const {
     id
   } = doc;
   if (!id) {
     throw new Error(`Refusing to apply delete hook to document without id.`);
   }
-  for (let [modelName, arg] of Object.entries(refs)) {
-    const Model = _mongoose.default.models[modelName];
-    if (typeof arg === 'string') {
-      await runDeletes(Model, doc, {
-        [arg]: id
-      });
-    } else if (Array.isArray(arg)) {
-      await runDeletes(Model, doc, {
-        $or: mapArrayQuery(arg, id)
-      });
-    } else {
-      const {
-        $and,
-        $or
-      } = arg;
-      if ($and) {
-        await runDeletes(Model, doc, {
-          $and: mapArrayQuery($and, id)
-        });
-      } else if ($or) {
-        await runDeletes(Model, doc, {
-          $or: mapArrayQuery($or, id)
-        });
-      }
+  const Model = _mongoose.default.models[ref];
+  if (!Model) {
+    throw new Error(`Unknown model: "${ref}".`);
+  }
+  if (path) {
+    await runDeletes(Model, doc, {
+      ...query,
+      [path]: id
+    });
+  } else if (paths) {
+    await runDeletes(Model, doc, {
+      $or: paths.map(refName => {
+        return {
+          ...query,
+          [refName]: id
+        };
+      })
+    });
+  }
+}
+async function deleteLocalReferences(doc, hook) {
+  const paths = getHookPaths(hook);
+  await doc.populate(paths);
+  for (let path of paths) {
+    const value = doc.get(path);
+    if (!value) {
+      continue;
+    }
+    const arr = Array.isArray(value) ? value : [value];
+    for (let sub of arr) {
+      await sub.delete();
     }
   }
 }
@@ -300,27 +314,25 @@ async function runDeletes(Model, refDoc, query) {
     });
   }
 }
-function mapArrayQuery(arr, id) {
-  return arr.map(refName => {
-    return {
-      [refName]: id
-    };
-  });
-}
 
 // Restore
 
-async function restoreLocalReferences(refDoc, arr) {
-  if (!arr) {
-    return;
+async function restoreReferences(doc, hooks) {
+  for (let hook of hooks) {
+    if (hook.ref) {
+      await restoreForeignReferences(doc);
+    } else {
+      await restoreLocalReferences(doc, hook);
+    }
   }
-  for (let name of arr) {
-    const {
-      ref
-    } = (0, _utils.getInnerField)(refDoc.constructor.schema.obj, name);
-    const value = refDoc.get(name);
-    const ids = Array.isArray(value) ? value : [value];
-    const Model = _mongoose.default.models[ref];
+}
+async function restoreForeignReferences(refDoc) {
+  const grouped = (0, _lodash.groupBy)(refDoc.deletedRefs, 'ref');
+  for (let [modelName, refs] of Object.entries(grouped)) {
+    const ids = refs.map(ref => {
+      return ref._id;
+    });
+    const Model = _mongoose.default.models[modelName];
 
     // @ts-ignore
     const docs = await Model.findDeleted({
@@ -332,14 +344,17 @@ async function restoreLocalReferences(refDoc, arr) {
       await doc.restore();
     }
   }
+  refDoc.deletedRefs = [];
 }
-async function restoreForeignReferences(refDoc) {
-  const grouped = (0, _lodash.groupBy)(refDoc.deletedRefs, 'ref');
-  for (let [modelName, refs] of Object.entries(grouped)) {
-    const ids = refs.map(ref => {
-      return ref._id;
-    });
-    const Model = _mongoose.default.models[modelName];
+async function restoreLocalReferences(refDoc, hook) {
+  const paths = getHookPaths(hook);
+  for (let path of paths) {
+    const {
+      ref
+    } = (0, _utils.getInnerField)(refDoc.constructor.schema.obj, path);
+    const value = refDoc.get(path);
+    const ids = Array.isArray(value) ? value : [value];
+    const Model = _mongoose.default.models[ref];
 
     // @ts-ignore
     const docs = await Model.findDeleted({
@@ -351,5 +366,4 @@ async function restoreForeignReferences(refDoc) {
       await doc.restore();
     }
   }
-  refDoc.deletedRefs = [];
 }

package/dist/cjs/include.js

@@ -242,15 +242,19 @@ function setNodePath(node, options) {
           node[key] = null;
         }
       } else if (type === 'virtual') {
-        node[key] ||= {};
         const virtual = schema.virtual(key);
-        setNodePath(node[key], {
-          // @ts-ignore
-          modelName: virtual.options.ref,
-          path: path.slice(parts.length),
-          depth: depth + 1,
-          exclude
-        });
+        // @ts-ignore
+        const ref = virtual.options.ref;
+        if (ref) {
+          node[key] ||= {};
+          setNodePath(node[key], {
+            // @ts-ignore
+            modelName: ref,
+            path: path.slice(parts.length),
+            depth: depth + 1,
+            exclude
+          });
+        }
         halt = true;
       } else if (type !== 'nested') {
         throw new Error(`Unknown path on ${modelName}: ${key}.`);