@bedrockio/model 0.2.16 → 0.2.18

package/README.md

@@ -1019,12 +1019,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 +1038,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 +1054,110 @@ await user.populate('profile');
 await user.profile.delete();
 ```
 
-#### Foreign Reference Cleanup
+#### Foreign References
+
+Operations that specify a `ref` are treated as foreign references. In the above
+example:
+
+```js
+user.delete();
+
+// Will implicitly run:
+const shops = await Shop.find({
+  owner: user,
+});
+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"
+        }
+      }
+    ]
+  }
+}
+```
 
-`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:
+In this example:
 
 ```js
 user.delete();
 
 // Will implicitly run:
-const shop = await Shop.find({
+const shops = await Shop.find({
+  status: 'active',
   owner: user,
 });
-await shop.delete();
+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 +1237,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/serialization.js

@@ -26,6 +26,23 @@ function transformField(obj, field, options) {
   } else if ((0, _lodash.isPlainObject)(obj)) {
     for (let [key, val] of Object.entries(obj)) {
       if (!isAllowedField(key, field, options)) {
+        // Although the "id" field is automatically added for most
+        // documents, this doesn't appear to be the case for mongoose
+        // schemas with a "type" field that is an array. For example:
+        //
+        // "type": [
+        //   {
+        //     "name": "String"
+        //   }
+        // ]
+        //
+        // This may be a mongoose bug.
+        // The "type": "Array" extended syntax wraps this behavior, so
+        // to keep consistency with other array field declaration types,
+        // force the "id" field to be set here.
+        if (key === '_id') {
+          obj.id = val.toString();
+        }
         delete obj[key];
       } else {
         transformField(val, (0, _utils.getInnerField)(field, key), options);

package/package.json

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

package/src/delete-hooks.js

@@ -13,9 +13,8 @@ export function applyDeleteHooks(schema, definition) {
     return;
   }
 
-  const cleanLocal = validateCleanLocal(deleteHooks, schema);
-  const cleanForeign = validateCleanForeign(deleteHooks);
   const errorHook = validateError(deleteHooks);
+  const cleanHooks = validateCleanHooks(deleteHooks, schema);
 
   let references;
 
@@ -27,24 +26,21 @@ export 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);
   });
 
@@ -60,45 +56,53 @@ export function applyDeleteHooks(schema, definition) {
 
 // Clean Hook
 
-function validateCleanLocal(deleteHooks, schema) {
-  let { local } = deleteHooks.clean || {};
-  if (!local) {
-    return;
-  }
-  if (typeof local !== 'string' && !Array.isArray(local)) {
-    throw new Error('Local delete hook must be an array.');
+function validateCleanHooks(deleteHooks, schema) {
+  const { clean } = deleteHooks;
+  if (!clean) {
+    return [];
   }
-  if (typeof local === 'string') {
-    local = [local];
+  if (!Array.isArray(clean)) {
+    throw new Error('Delete clean hook must be an array.');
   }
-  for (let name of local) {
-    const pathType = schema.pathType(name);
-    if (pathType !== 'real') {
-      throw new Error(`Delete hook has invalid local reference "${name}".`);
+
+  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);
     }
   }
-  return local;
+
+  return clean;
 }
 
-function validateCleanForeign(deleteHooks) {
-  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}.`
-        );
-      }
+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 foreign;
+}
+
+function getHookPaths(hook) {
+  const { path, paths } = hook;
+  if (path) {
+    return [path];
+  } else if (paths) {
+    return paths;
+  } else {
+    return [];
+  }
 }
 
 function validateError(deleteHooks) {
@@ -170,11 +174,17 @@ async function errorOnForeignReferences(doc, options) {
 }
 
 function referenceIsAllowed(model, options) {
-  const { cleanForeign = {} } = options;
-  const { only, except } = options?.errorHook || {};
-  if (model.modelName in cleanForeign) {
+  const { modelName } = model;
+  const { cleanHooks } = options;
+
+  const hasCleanHook = cleanHooks.some((hook) => {
+    return hook.ref === modelName;
+  });
+  if (hasCleanHook) {
     return true;
   }
+
+  const { only, except } = options?.errorHook || {};
   if (only) {
     return !only.includes(model.modelName);
   } else if (except) {
@@ -227,16 +237,54 @@ function getModelReferences(model, targetName) {
   return paths;
 }
 
-// Deletion
+// Delete
 
-async function deleteLocalReferences(doc, arr) {
-  if (!arr) {
-    return;
+async function deleteReferences(doc, hooks) {
+  for (let hook of hooks) {
+    if (hook.ref) {
+      await deleteForeignReferences(doc, hook);
+    } else {
+      await deleteLocalReferences(doc, hook);
+    }
   }
-  for (let name of arr) {
-    await doc.populate(name);
+}
+
+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.`);
+  }
+
+  const Model = mongoose.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);
 
-    const value = doc.get(name);
     if (!value) {
       continue;
     }
@@ -248,39 +296,6 @@ async function deleteLocalReferences(doc, arr) {
   }
 }
 
-async function deleteForeignReferences(doc, refs) {
-  if (!refs) {
-    return;
-  }
-  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.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),
-        });
-      }
-    }
-  }
-}
-
 async function runDeletes(Model, refDoc, query) {
   const docs = await Model.find(query);
   for (let doc of docs) {
@@ -292,33 +307,14 @@ 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;
-  }
-  for (let name of arr) {
-    const { ref } = getInnerField(refDoc.constructor.schema.obj, name);
-    const value = refDoc.get(name);
-    const ids = Array.isArray(value) ? value : [value];
-    const Model = mongoose.models[ref];
-
-    // @ts-ignore
-    const docs = await Model.findDeleted({
-      _id: { $in: ids },
-    });
-
-    for (let doc of docs) {
-      await doc.restore();
+async function restoreReferences(doc, hooks) {
+  for (let hook of hooks) {
+    if (hook.ref) {
+      await restoreForeignReferences(doc);
+    } else {
+      await restoreLocalReferences(doc, hook);
     }
   }
 }
@@ -344,3 +340,23 @@ async function restoreForeignReferences(refDoc) {
 
   refDoc.deletedRefs = [];
 }
+
+async function restoreLocalReferences(refDoc, hook) {
+  const paths = getHookPaths(hook);
+
+  for (let path of paths) {
+    const { ref } = getInnerField(refDoc.constructor.schema.obj, path);
+    const value = refDoc.get(path);
+    const ids = Array.isArray(value) ? value : [value];
+    const Model = mongoose.models[ref];
+
+    // @ts-ignore
+    const docs = await Model.findDeleted({
+      _id: { $in: ids },
+    });
+
+    for (let doc of docs) {
+      await doc.restore();
+    }
+  }
+}

package/src/serialization.js

@@ -24,6 +24,23 @@ function transformField(obj, field, options) {
   } else if (isPlainObject(obj)) {
     for (let [key, val] of Object.entries(obj)) {
       if (!isAllowedField(key, field, options)) {
+        // Although the "id" field is automatically added for most
+        // documents, this doesn't appear to be the case for mongoose
+        // schemas with a "type" field that is an array. For example:
+        //
+        // "type": [
+        //   {
+        //     "name": "String"
+        //   }
+        // ]
+        //
+        // This may be a mongoose bug.
+        // The "type": "Array" extended syntax wraps this behavior, so
+        // to keep consistency with other array field declaration types,
+        // force the "id" field to be set here.
+        if (key === '_id') {
+          obj.id = val.toString();
+        }
         delete obj[key];
       } else {
         transformField(val, getInnerField(field, key), options);

package/types/delete-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-hooks.d.ts","sourceRoot":"","sources":["../src/delete-hooks.js"],"names":[],"mappings":"AAQA,qEAkDC"}
+{"version":3,"file":"delete-hooks.d.ts","sourceRoot":"","sources":["../src/delete-hooks.js"],"names":[],"mappings":"AAQA,qEA8CC"}