monastery 3.3.0 → 3.4.0

package/.eslintrc.json

@@ -32,7 +32,7 @@
       "exports": "always-multiline",
       "functions": "never"
     }],
-    "max-len": ["error", { "code": 125, "ignorePattern": "^\\s*<(rect|path|line)\\s" }],
+    "max-len": ["error", { "code": 130, "ignorePattern": "^\\s*<(rect|path|line)\\s" }],
     "no-prototype-builtins": "off",
     "no-unused-vars": ["error", { "args": "none" }],
     "object-shorthand": ["error", "consistent"],

package/changelog.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [3.4.0](https://github.com/boycce/monastery/compare/3.3.0...3.4.0) (2024-08-09)
+
 ## [3.3.0](https://github.com/boycce/monastery/compare/3.2.1...3.3.0) (2024-08-07)
 
 ### [3.2.1](https://github.com/boycce/monastery/compare/3.2.0...3.2.1) (2024-08-05)

package/docs/readme.md

@@ -86,7 +86,7 @@ You can view MongoDB's [compatibility table here](https://www.mongodb.com/docs/d
 ## v3 Breaking Changes
 
   - Removed callback functions on all model methods, you can use the returned promise instead
-  - model.update() now returns the following _update property: `{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedCount: 0, upsertedId: null }` instead of `{ n: 1, nModified: 1, ok: 1 }`
+  - model.update() now returns the following res._output property: `{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedCount: 0, upsertedId: null }` instead of `{ n: 1, nModified: 1, ok: 1 }`
   - model.remove() now returns `{ acknowledged: true, deletedCount: 1 }`, instead of `{ results: {n:1, ok:1} }`
   - model._indexes() now returns collection._indexes() not collection._indexInformation()
   - db.model.* moved to db.models.*
@@ -95,7 +95,7 @@ You can view MongoDB's [compatibility table here](https://www.mongodb.com/docs/d
   - db._db moved to db.db
   - db.catch/then() moved to db.onError/db.onOpen()
   - next() is now redundant when returning promises from hooks, e.g. `afterFind: [async (data) => {...}]`
-  - option `skipValidation: true` now skips validation hooks 
+  - deep paths in data, e.g. `books[].title` are now validated, and don't replace the whole object, e.g. `books`
 
 ## v2 Breaking Changes
 
@@ -134,6 +134,8 @@ You can view MongoDB's [compatibility table here](https://www.mongodb.com/docs/d
 - ~~added `model.count()`~~
 - Typescript support
 - Add soft remove plugin
+- ~~Added deep path validation support for updates~~
+- ~~Added option skipHooks~~
 
 ## Debugging
 

package/lib/index.js

@@ -277,8 +277,20 @@ Manager.prototype.open = async function() {
   }
 }
 
-Manager.prototype.parseData = function(obj) {
-  return util.parseData(obj)
+Manager.prototype.parseData = function(obj, parseBracketToDotNotation, parseDotNotation) {
+  return util.parseData(obj, parseBracketToDotNotation, parseDotNotation)
+}
+
+Manager.prototype.parseBracketNotation = function(obj) {
+  return util.parseBracketNotation(obj)
+}
+
+Manager.prototype.parseBracketToDotNotation = function(obj) {
+  return util.parseBracketToDotNotation(obj)
+}
+
+Manager.prototype.parseDotNotation = function(obj) {
+  return util.parseDotNotation(obj)
 }
 
 Manager.prototype.model = Model

package/lib/model-crud.js

@@ -5,9 +5,9 @@ Model.prototype.count = async function (opts) {
   /**
    * Count document(s)
    * @param {object} opts
-   *     @param {object} <opts.query> - mongodb query object
+   *     @param {object}  <opts.query> - mongodb query object
    *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {any} <any mongodb option>
+   *     @param {any}     <any mongodb option>
    * @return promise
    * @this model
    */
@@ -28,30 +28,38 @@ Model.prototype.count = async function (opts) {
 Model.prototype.insert = async function (opts) {
   /**
    * Inserts document(s) after validating data & before hooks.
+   * 
    * @param {object} opts
-   *     @param {object|array} opts.data - documents to insert
-   *     @param {array|string|false} <opts.blacklist> - augment schema.insertBL, `false` will remove blacklisting
-   *     @param {array|string} <opts.project> - return only these fields, ignores blacklisting
-   *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {array|string|true} <opts.skipValidation> - skip validation for these fields, or pass `true` to skip
-   *         all fields and hooks
-   *     @param {boolean} <opts.timestamps> - whether `createdAt` and `updatedAt` are automatically inserted
-   *     @param {array|string|false} <opts.validateUndefined> - validates all 'required' undefined fields, true by
-   *         default, but false on update
-   *     @param {any} <any mongodb option>
+   *   @param {object|array}         opts.data - documents to insert
+   *   @param {array|string|false}   <opts.blacklist> - augment schema.insertBL, `false` will remove blacklisting
+   *   @param {boolean}              <opts.bracketToDotNotation> - covert fields in bracket notation (form data) to 
+   *     paths in dot notation instead of objects, e.g. { 'user[names][0]': 'John' } => { user.names.0 }
+   *   @param {array|string}         <opts.project> - return only these fields, ignores blacklisting
+   *   @param {boolean}              <opts.respond> - automatically call res.json/error (requires opts.req)
+   *   @param {boolean}              <opts.skipHooks> - skip insert and validate before/after hooks
+   *   @param {array|string|boolean} <opts.skipValidation> - skip validation for these fields, or pass `true` for all fields.
+   *     $set and $unset objects are skipped by default, but can be enabled via opts.skipValidation=false
+   *   @param {boolean}              <opts.timestamps> - whether `createdAt` and `updatedAt` are automatically inserted
+   *   @param {array|string|false}   <opts.validateUndefined> - validates all 'required' undefined fields, true by
+   *     default, but false on update
+   *   @param {any}                  <any mongodb option>
+   * 
    * @return promise
    * @this model
    */
   try {
     opts = await this._queryObject(opts, 'insert')
+    let data = opts.data
 
     // Validate
-    let data = await this.validate(opts.data || {}, opts) // was { ...opts }
+    if (this._shouldValidate(opts, 'data')) {
+      data = await this.validate(data || {}, opts) // was { ...opts }
+    }
 
     // Insert
-    data = await util.runSeries.call(this, this.beforeInsert.map(f => f.bind(opts)), 'beforeInsert', data)
+    data = await this._callHooks('beforeInsert', data, opts)
     let response = await this._insert(data, util.omit(opts, this._queryOptions))
-    response = await util.runSeries.call(this, this.afterInsert.map(f => f.bind(opts)), 'afterInsert', response)
+    response = await this._callHooks('afterInsert', response, opts)
 
     // Success/error
     if (opts.req && opts.respond) opts.req.res.json(response)
@@ -66,15 +74,18 @@ Model.prototype.insert = async function (opts) {
 Model.prototype.find = async function (opts, _one) {
   /**
    * Finds document(s), with auto population
+   * 
    * @param {object} opts (todo doc getSignedUrls like in the doc)
-   *     @param {array|string|false} <opts.blacklist> - augment schema.findBL, `false` will remove all blacklisting
-   *     @param {boolean|string|array} <opts.noDefaults> - dont add defaults for any matching paths, e.g. ['pet.name']
-   *     @param {array} <opts.populate> - population, see docs
-   *     @param {array|string} <opts.project> - return only these fields, ignores blacklisting
-   *     @param {object} <opts.query> - mongodb query object
-   *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {any} <any mongodb option>
+   *   @param {object}                <opts.query> - mongodb query object
+   *   @param {array|string|false}    <opts.blacklist> - augment schema.findBL, `false` will remove all blacklisting
+   *   @param {boolean|string|array}  <opts.noDefaults> - dont add defaults for any matching paths, e.g. ['pet.name']
+   *   @param {array}                 <opts.populate> - population, see docs
+   *   @param {array|string}          <opts.project> - return only these fields, ignores blacklisting
+   *   @param {boolean}               <opts.respond> - automatically call res.json/error (requires opts.req)
+   *   @param {boolean}               <opts.skipHooks> - skip after find hooks
+   *   @param {any}                   <any mongodb option>
    * @param {boolean} <_one> - return one document
+   * 
    * @return promise
    * @this model
    */
@@ -215,22 +226,20 @@ Model.prototype.findOne = async function (opts) {
 Model.prototype.findOneAndUpdate = async function (opts) {
   /**
    * Find and update document(s) with auto population
+   * 
    * @param {object} opts
-   *     @param {array|string|false} <opts.blacklist> - augment findBL/updateBL, `false` will remove all blacklisting
-   *     @param {boolean|string|array} <opts.noDefaults> - dont add defaults for any matching paths, e.g. ['pet.name']
-   *     @param {array} <opts.populate> - find population, see docs
-   *     @param {array|string} <opts.project> - return only these fields, ignores blacklisting
-   *     @param {object} <opts.query> - mongodb query object
-   *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {any} <any mongodb option>
-   *
-   *     Update options:
-   *     @param {object|array} opts.data - mongodb document update object(s)
-   *     @param {array|string|true} <opts.skipValidation>- skip validation for these fields, or pass `true` to skip
-   *         all fields and hooks
-   *     @param {boolean} <opts.timestamps> - whether `updatedAt` is automatically updated
-   *     @param {array|string|false} <opts.validateUndefined> - validates all 'required' undefined fields, true by
-   *         default, but false on update
+   *   Find options:
+   *   @param {object}               <opts.query> - mongodb query object
+   *   @param {array}                <opts.populate> - find population, see docs
+   *   @param {any}                  <any model.find option>
+   * 
+   *   Update options:
+   *   @param {object|array}         opts.data - mongodb document update object(s)
+   *   @param {any}                  <any model.update option>
+   * 
+   *   Mongo options:
+   *   @param {any}                  <any mongodb option>
+   * 
    * @return promise
    * @this model
    */
@@ -259,50 +268,59 @@ Model.prototype.findOneAndUpdate = async function (opts) {
 Model.prototype.update = async function (opts, type='update') {
   /**
    * Updates document(s) after validating data & before hooks.
+   * 
    * @param {object} opts
-   *     @param {object|array} opts.data - mongodb document update object(s)
-   *     @param {array|string|false} <opts.blacklist> - augment schema.updateBL, `false` will remove blacklisting
-   *     @param {array|string} <opts.project> - return only these fields, ignores blacklisting
-   *     @param {object} <opts.query> - mongodb query object
-   *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {array|string|true} <opts.skipValidation> - skip validation for these fields, or pass `true` to skip
-   *         all fields and hooks
-   *     @param {boolean} <opts.timestamps> - whether `updatedAt` is automatically updated
-   *     @param {array|string|false} <opts.validateUndefined> - validates all 'required' undefined fields, true by
-   *         default, but false on update
-   *     @param {any} <any mongodb option>
+   *   @param {object}               opts.query - mongodb query object
+   *   @param {object|array}         opts.data - mongodb document update object(s)
+   *   @param {array|string|false}   <opts.blacklist> - augment schema.updateBL, `false` will remove blacklisting
+   *   @param {boolean}              <opts.bracketToDotNotation> - covert fields in bracket notation (form data) to 
+   *     paths in dot notation instead of objects, e.g. { 'user[names][0]': 'John' } => { user.names.0 }
+   *   @param {array|string}         <opts.project> - return only these fields, ignores blacklisting
+   *   @param {boolean}              <opts.respond> - automatically call res.json/error (requires opts.req)
+   *   @param {boolean}              <opts.skipHooks> - validate and update before/after hooks
+   *   @param {array|string|boolean} <opts.skipValidation> - skip validation for these fields, or pass `true` for all fields.
+   *     $set and $unset objects are skipped by default, but can be enabled via opts.skipValidation=false
+   *   @param {boolean}              <opts.timestamps> - whether `updatedAt` is automatically updated
+   *   @param {array|string|false}   <opts.validateUndefined> - validates all 'required' undefined fields, true by
+   *     default, but false on update
+   *   @param {any}                  <any mongodb option or operation>
    * @param {function} <type> - 'update', or 'findOneAndUpdate'
+   * 
    * @return promise(data)
    * @this model
    */
   try {
     opts = await this._queryObject(opts, type)
-    let data = opts.data
     let response = null
-    let operators = util.pick(opts, [/^\$/])
+    let operators = util.removeUndefined(util.pick(opts, [/^\$/, 'data']))
 
-    // Validate
-    if (util.isDefined(data)) {
-      data = await this.validate(opts.data, opts) // was {...opts}
-    }
-    if (!util.isDefined(data) && util.isEmpty(operators)) {
+    if (operators.data && operators.$set) {
+      this.info(`'$set' fields take precedence over the data fields for \`${this.name}.${type}()\``)
+    } else if (!Object.keys(operators).length) {
       throw new Error(`Please pass an update operator to ${this.name}.${type}(), e.g. data, $unset, etc`)
     }
-    if (util.isDefined(data) && (!data || util.isEmpty(data))) {
-      throw new Error(`No valid data passed to ${this.name}.${type}({ data: .. })`)
-    }
 
-    // Hook: beforeUpdate (has access to original, non-validated opts.data)
-    data = data || {}
-    data = await util.runSeries.call(this, this.beforeUpdate.map(f => f.bind(opts)), 'beforeUpdate', data)
-
-    if (data && operators['$set']) {
-      this.info(`'$set' fields take precedence over the data fields for \`${this.name}.${type}()\``)
+    // Validate data (doesn't mutate opts)
+    for (let key in operators) {
+      if (this._shouldValidate(opts, key)) {
+        operators[key] = await this.validate(operators[key], opts)
+      }
+      if (util.isEmpty(operators[key] || {})) {
+        throw new Error(`No valid data passed to ${this.name}.${type}({ ${key}: .. })`)
+      }
     }
-    if (data || operators['$set']) {
-      operators['$set'] = { ...data, ...(operators['$set'] || {}) }
+
+    // Merge data into $set
+    if (operators.data || operators.$set) {
+      operators.$set = { ...(operators.data||{}), ...(operators['$set'] || {}) }
+      delete operators.data
     }
 
+    // Hook: beforeUpdate (has access to original, non-validated data via opts.data)
+    const onlySet = Object.keys(operators).length == 1 && operators.$set
+    if (onlySet) operators.$set = await this._callHooks('beforeUpdate', operators.$set, opts)
+    else operators = await this._callHooks('beforeUpdate', operators, opts)
+
     // findOneAndUpdate, get 'find' projection
     if (type == 'findOneAndUpdate') {
       if (opts.project) opts.projection = this._getProjectionFromProject(opts.project)
@@ -323,10 +341,8 @@ Model.prototype.update = async function (opts, type='update') {
       )
     }
 
-    // Hook: afterUpdate (doesn't have access to validated data)
-    if (response) {
-      response = await util.runSeries.call(this, this.afterUpdate.map(f => f.bind(opts)), 'afterUpdate', response)
-    }
+    // Hook: afterUpdate (doesn't have access to validated data, just the response)
+    if (response) response = await this._callHooks('afterUpdate', response, opts)
 
     // Hook: afterFind if findOneAndUpdate
     if (response && type == 'findOneAndUpdate') {
@@ -346,11 +362,14 @@ Model.prototype.update = async function (opts, type='update') {
 Model.prototype.remove = async function (opts) {
   /**
    * Remove document(s) with before and after hooks.
+   * 
    * @param {object} opts
-   *     @param {object} <opts.query> - mongodb query object
-   *     @param {boolean} <opts.respond> - automatically call res.json/error (requires opts.req)
-   *     @param {boolean=true} <opts.multi> - set to false to limit the deletion to just one document
-   *     @param {any} <any mongodb option>
+   *   @param {object}       <opts.query> - mongodb query object
+   *   @param {boolean=true} <opts.multi> - set to false to limit the deletion to just one document
+   *   @param {boolean}      <opts.respond> - automatically call res.json/error (requires opts.req)
+   *   @param {boolean}      <opts.skipHooks> - remove before/after hooks
+   *   @param {any}          <any mongodb option>
+   * 
    * @return promise
    * @this model
    */
@@ -358,9 +377,9 @@ Model.prototype.remove = async function (opts) {
     opts = await this._queryObject(opts, 'remove')
 
     // Remove
-    await util.runSeries.call(this, this.beforeRemove.map(f => f.bind(opts)), 'beforeRemove')
+    await this._callHooks('beforeRemove', null, opts)
     let response = await this._remove(opts.query, util.omit(opts, this._queryOptions))
-    await util.runSeries.call(this, this.afterRemove.map(f => f.bind(response)), 'afterRemove')
+    await this._callHooks('afterRemove', response, opts)
 
     // Success
     if (opts.req && opts.respond) opts.req.res.json(response)
@@ -379,9 +398,10 @@ Model.prototype._getProjectionFromBlacklist = function (type, customBlacklist) {
    * Path collisions are removed
    * E.g. ['pets.dogs', 'pets.dogs.name', '-cat', 'pets.dogs.age'] = { 'pets.dog': 0 }
    *
-   * @param {string} type - find, insert, or update
+   * @param {string}             type - find, insert, or update
    * @param {array|string|false} customBlacklist - normally passed through options
-   * @return {array|undefined} exclusion $project {'pets.name': 0}
+   * 
+   * @return {array|undefined}   exclusion $project {'pets.name': 0}
    * @this model
    *
    * 1. collate deep-blacklists
@@ -467,7 +487,8 @@ Model.prototype._getProjectionFromProject = function (customProject) {
    * todo: tests
    *
    * @param {object|array|string} customProject - normally passed through options
-   * @return {array|undefined} in/exclusion projection {'pets.name': 0}
+   * 
+   * @return {array|undefined}    in/exclusion projection {'pets.name': 0}
    * @this model
    */
   let projection
@@ -488,9 +509,11 @@ Model.prototype._getProjectionFromProject = function (customProject) {
 Model.prototype._queryObject = async function (opts, type, _one) {
   /**
    * Normalize options
+   * 
    * @param {MongoId|string|object} opts
-   * @param {string} type - insert, update, find, remove, findOneAndUpdate
-   * @param {boolean} _one - return one document
+   * @param {string}                type - insert, update, find, remove, findOneAndUpdate
+   * @param {boolean}               _one - return one document
+   * 
    * @return {Promise} opts
    * @this model
    *
@@ -542,7 +565,7 @@ Model.prototype._queryObject = async function (opts, type, _one) {
   // Data
   if (!opts) opts = {}
   if (!util.isDefined(opts.data) && util.isDefined((opts.req||{}).body)) opts.data = opts.req.body
-  if (util.isDefined(opts.data)) opts.data = await util.parseData(opts.data)
+  if (util.isDefined(opts.data)) opts.data = await util.parseData(opts.data, opts.bracketToDotNotation)/////
 
   opts.type = type
   opts[type] = true // still being included in the operation options..
@@ -554,11 +577,13 @@ Model.prototype._queryObject = async function (opts, type, _one) {
 Model.prototype._pathBlacklisted = function (path, projectionInclusion, projectionKeys, matchDeepWhitelistedKeys=true) {
   /**
    * Checks if the path is blacklisted within a inclusion/exclusion projection
-   * @param {string} path - path without array brackets e.g. '.[]'
+   * 
+   * @param {string}  path - path without array brackets e.g. '.[]'
    * @param {boolean} projectionInclusion - is a inclusion or exclusion projection (default is exclusion)
-   * @param {array} projectionKeys - inclusion/exclusion projection keys, not mixed
+   * @param {array}   projectionKeys - inclusion/exclusion projection keys, not mixed
    * @param {boolean} matchDeepWhitelistedKeys - match deep whitelisted keys containing path
    *     E.g. pets.color == pets.color.age
+   * 
    * @return {boolean}
    */
   if (projectionInclusion) {
@@ -592,8 +617,9 @@ Model.prototype._processAfterFind = async function (data, projection={}, afterFi
    * e.g. "nurses": [{ model: 'user' }]
    *
    * @param {object|array|null} data
-   * @param {object} projection - opts.projection (== opts.blacklist is merged with all found deep model blacklists)
-   * @param {object} afterFindContext - handy context object given to schema.afterFind
+   * @param {object}            projection - opts.projection (== opts.blacklist is merged with all found deep model blacklists)
+   * @param {object}            afterFindContext - handy context object given to schema.afterFind
+   * 
    * @return Promise(data)
    * @this model
    */
@@ -606,6 +632,7 @@ Model.prototype._processAfterFind = async function (data, projection={}, afterFi
   const projectionKeys = Object.keys(projection)
   const projectionInclusion = projection[projectionKeys[0]] ? true : false // default false
   if (!isArray) data = [data]
+
   let modelFields = this
     ._recurseAndFindModels(data)
     .concat(data.map((o, i) => ({
@@ -652,7 +679,7 @@ Model.prototype._processAfterFind = async function (data, projection={}, afterFi
           const _opts = { ...afterFindContext, afterFindName: _modelName }
           const _dataRef = _item.dataRefParent[_item.dataRefKey]
           _item.dataRefParent[_item.dataRefKey] = (
-            await util.runSeries.call(_model, _model.afterFind.map(f => f.bind(_opts)), 'afterFind', _dataRef)
+            await _model._callHooks('afterFind', _dataRef, _opts)
           )
         }).bind(null, item)
       )
@@ -665,8 +692,10 @@ Model.prototype._processAfterFind = async function (data, projection={}, afterFi
 Model.prototype._recurseAndFindModels = function (dataArr, dataParentPath='') {
   /**
    * Returns a flattened list of models fields, sorted by depth
+   * 
    * @param {object|array} dataArr
-   * @param {string} <dataParentPath>
+   * @param {string}       <dataParentPath>
+   * 
    * @this Model
    * @return [{
    *   dataRefParent: { *fields here* },
@@ -736,6 +765,14 @@ Model.prototype._recurseAndFindModels = function (dataArr, dataParentPath='') {
   return out
 }
 
+Model.prototype._shouldValidate = function (opts, operatorName) {
+  return ['data', '$set', '$unset'].includes(operatorName) && (
+      opts.skipValidation === false ? true 
+      : opts.skipValidation && opts.skipValidation !== true ? true
+      : operatorName == 'data' // enabled by default
+  )
+}
+
 Model.prototype._queryOptions = [
   // todo: remove type properties
   'blacklist', 'data', 'find', 'findOneAndUpdate', 'insert', 'model', '_one', 'populate', 'project',