monastery 1.36.0 → 1.36.3

package/docs/model/findOneAndUpdate.md

@@ -0,0 +1,42 @@
+---
+title: findOneAndUpdate
+parent: Model
+---
+
+# `model.findOneAndUpdate`
+
+Find a document and update it in one atomic operation (unless using `opt.populate`), requires a write lock for the duration of the operation. Calls the following model hooks: `beforeUpdate`,  `afterUpdate`,  `afterFind`.
+
+### Arguments
+
+Same argument signatures as [`model.find`](./find) and [`model.update`](./update).
+
+### Returns
+
+A promise if no callback is passed in.
+
+### Example
+
+```js
+await user.findOneAndUpdate({
+  query: { name: "Martin" },
+  data: { name: "Martin2" },
+})
+// { name: 'Martin2', ... }
+
+// You can return a populated model which isn't atomic
+await user.findOneAndUpdate({
+  query: { name: "Martin" },
+  data: { name: "Martin2" },
+  populate: ['pet'],
+})
+// { name: 'Martin2', pet: {...}, ... }
+
+// Blacklisting prunes the data and returned document
+await user.findOneAndUpdate({
+  query: { name: "Martin" },
+  data: { name: "Martin2", age: 100 },
+  blacklist: ['age'],
+})
+// { name: 'Martin2', ... }
+```

package/docs/model/index.md

@@ -8,9 +8,9 @@ has_children: true
 
 Created via [`manager.model`](../manager/model).
 
-#### Monk collection instance methods
+#### Monk collection instance operators
 
-Additionally models inherit most of the [monk collection](https://automattic.github.io/monk/docs/collection/) instance methods which are available under `model`.
+Additionally models inherit most of the [monk collection](https://automattic.github.io/monk/docs/collection/) instance operators which are available under `model`.
 
   * model.[_aggregate](https://automattic.github.io/monk/docs/collection/aggregate.html)
   * model.[_bulkWrite](https://automattic.github.io/monk/docs/collection/bulkWrite.html)

package/docs/model/insert.md

@@ -5,16 +5,17 @@ parent: Model
 
 # `model.insert`
 
-Validate and insert document(s) in a collection and call related hooks: `schema.beforeInsert`,  `schema.afterInsert`
+Validate and insert document(s) in a collection and calls model hooks: `beforeInsert`,  `afterInsert`
 
 ### Arguments
 
 `options` *(object)*
 
-- `options.data` *(object\|array)* - Data that is validated against the model schema. Key names can be in dot or bracket notation which is handy for HTML FormData.
-- [`options.skipValidation`] (string\|array): skip validation for this field name(s)
-- [`options.timestamps`] *(boolean)*: whether `createdAt` and `updatedAt` are automatically inserted, defaults to `manager.timestamps`
-- [`options.blacklist`] *(array\|string\|false)*: augment `schema.insertBL`. `false` will remove all blacklisting
+- `data` *(object\|array)* - Data that is validated against the model fields. Key names can be in dot or bracket notation which is handy for HTML FormData.
+- [[`blacklist`](#blacklisting)] *(array\|string\|false)*: augment `definition.insertBL`. `false` will remove all blacklisting
+- [`project`] *(string\|array\|object)*: project these fields, ignores blacklisting
+- [`skipValidation`] (string\|array): skip validation for this field name(s)
+- [`timestamps`] *(boolean)*: whether `createdAt` and `updatedAt` are automatically inserted, defaults to `manager.timestamps`
 - [[`any mongodb option`](http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#insert)] *(any)*
 
 [`callback`] *(function)*: pass instead of return a promise
@@ -32,32 +33,33 @@ user.insert({ data: [{ name: 'Martin Luther' }, { name: 'Bruce Lee' }]})
 
 ### Blacklisting
 
-You can augment the model's `schema.insertBL` blacklist by passing a custom `blacklist`:
+You can augment the model's blacklist (`definition.insertBL`) by passing a custom `blacklist`:
 
 ```js
 // Prevents `name` and `pets.$.name` (array) from being returned.
 user.insert({ data: {}, blacklist: ['name', 'pets.name'] })
-// You can also whitelist any blacklisted fields found in schema.insertBL
+// You can also whitelist any blacklisted fields found in definition.insertBL
 user.insert({ data: {}, blacklist: ['-name', '-pet'] })
 ```
 
 ### Defaults example
 
-When defaultObjects is enabled, undefined subdocuments and arrays will default to `{}` `[]` respectively when inserting. You can enable `defaultObjects` via the [manager options](../manager#arguments).
+When defaultObjects is enabled, undefined embedded documents and arrays will default to `{}` `[]` respectively when inserting. You can enable `defaultObjects` via the [manager options](../manager#arguments).
 
 ```js
-db.model({ fields: {
-  names: [{ type: 'string' }],
-  pets: {
-    name: { type: 'string' },
-    colors: [{ type: 'string' }]
+db.model({
+  fields: {
+    names: [{ type: 'string' }],
+    pets: {
+      name: { type: 'string' },
+      colors: [{ type: 'string' }]
+    }
   }
-}})
-
-user.insert({ data: {} }).then(data => {
-  // data = {
-  //   names: [],
-  //   pets: { colors: [] }
-  // }
 })
+
+await user.insert({ data: {} })
+// data = {
+//   names: [],
+//   pets: { colors: [] }
+// }
 ```

package/docs/model/remove.md

@@ -5,14 +5,14 @@ parent: Model
 
 # `model.remove`
 
-Remove document(s) in a collection and call related hooks: `schema.beforeRemove`,  `schema.afterRemove`
+Remove document(s) in a collection and calls model hooks: `beforeRemove`,  `afterRemove`
 
 ### Arguments
 
 `options` *(object)*
 
-- `options.query` *(object\|id)*
-- [`options.sort`] *(string\|object\|array)*: same as the mongodb option, but  allows for string parsing e.g. 'name', 'name:1'
+- `query` *(object\|id)*
+- [`sort`] *(string\|object\|array)*: same as the mongodb option, but  allows for string parsing e.g. 'name', 'name:1'
 - [[`any mongodb option`](http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#remove)] *(any)*
 
 [`callback`] *(function)*: pass instead of return a promise

package/docs/model/update.md

@@ -5,18 +5,19 @@ parent: Model
 
 # `model.update`
 
-Update document(s) in a collection and call related hooks: `schema.beforeUpdate`,  `schema.afterUpdate`. By default this method method updates a single document. Set the `multi` mongodb option to update all documents that match the query criteria.
+Update document(s) in a collection and calls model hooks: `beforeUpdate`,  `afterUpdate`. By default this method method updates a single document. Set the `multi` mongodb option to update all documents that match the query criteria.
 
 ### Arguments
 
 `options` *(object)*
 
-- `options.query` *(object\|id)*
-- `options.data` *(object)* - data that's validated against the model schema and then wrapped in `{ $set: .. }`, [`more below`](#data)
-- [`options.skipValidation`] (string\|array): skip validation for this field name(s)
-- [`options.sort`] *(string\|object\|array)*: same as the mongodb option, but  allows for string parsing e.g. 'name', 'name:1'
-- [`options.timestamps`] *(boolean)*: whether `updatedAt` is automatically updated, defaults to the `manager.timestamps` value
-- [`options.blacklist`] *(array\|string\|false)*: augment `schema.updateBL`. `false` will remove all blacklisting
+- `query` *(object\|id)*
+- [`data`](#data) *(object)* - data that's validated against the model fields (always wrapped in `{ $set: .. }`)
+- [[`blacklist`](#blacklisting)]*(array\|string\|false)*: augment `definition.updateBL`. `false` will remove all blacklisting
+- [`project`] *(string\|array\|object)*: project these fields, ignores blacklisting
+- [`skipValidation`] (string\|array): skip validation for this field name(s)
+- [`sort`] *(string\|object\|array)*: same as the mongodb option, but  allows for string parsing e.g. 'name', 'name:1'
+- [`timestamps`] *(boolean)*: whether `updatedAt` is automatically updated, defaults to the `manager.timestamps` value
 - [[`any mongodb option`](http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#update)] *(any)*
 
 [`callback`] *(function)*: pass instead of return a promise
@@ -33,7 +34,7 @@ user.update({ query: { name: 'foo' }, data: { name: 'bar' }})
 
 ### Data
 
-Data that is validated against the model schema and then wrapped in `{ $set: .. }`. Key names can be in dot or bracket notation which is handy for HTML FormData.
+Data that's validated against the model fields (always wrapped in `{ $set: .. }`). Key names can be in dot or bracket notation which is handy for HTML FormData.
 
 You can also pass `options.$set` or any other mongodb update operation instead of `options.data`, which bypasses validation, e.g.
 
@@ -48,10 +49,10 @@ user.update({ query: {}, $pull: { name: 'Martin', badField: 1 }})
 
 ### Blacklisting
 
-You can augment the model's `schema.updateBL` blacklist by passing a custom `blacklist`:
+You can augment the model's blacklist (`updateBL`) by passing a custom `blacklist`:
 
 ```js
 // Prevents `name` and `pets.$.name` (array) from being returned.
 user.update({ query: {}, data: {}, blacklist: ['name', 'pets.name'] })
-// You can also whitelist any blacklisted fields found in schema.updateBL
+// You can also whitelist any blacklisted fields found in updateBL
 user.update({ query: {}, data: {}, blacklist: ['-name', '-pet'] })

package/docs/model/validate.md

@@ -5,7 +5,7 @@ parent: Model
 
 # `model.validate`
 
-Validate a model and call related hook: `schema.beforeValidate`
+Validate a model and calls the model hook: `beforeValidate`
 
 
 ### Arguments
@@ -14,10 +14,11 @@ Validate a model and call related hook: `schema.beforeValidate`
 
 [`options`] *(object)*
 
-- [`options.skipValidation`] (string\|array): skip validation for this field name(s)
-- [`options.blacklist`] *(array\|string\|false)*: augment the model's blacklist. `false` will remove all blacklisting
-- [`options.timestamps`] *(boolean)*: whether `createdAt` and `updatedAt` are inserted, or `updatedAt` is updated, depending on the `options.update` value. Defaults to the `manager.timestamps` value
-- [`options.update`] *(boolean)*: If true, required rules will be skipped, defaults to false
+- [`skipValidation`] (string\|array): skip validation for this field name(s)
+- [[`blacklist`](#blacklisting)] *(array\|string\|false)*: augment the model's blacklist. `false` will remove all blacklisting
+- [`project`] *(string\|array\|object)*: project these fields, ignores blacklisting
+- [`timestamps`] *(boolean)*: whether `createdAt` and `updatedAt` are inserted, or `updatedAt` is updated, depending on the `update` value. Defaults to the `manager.timestamps` value
+- [`update`] *(boolean)*: If true, required rules will be skipped, defaults to false
 
 ### Returns
 
@@ -34,39 +35,35 @@ db.model('user', {
   }
 })
 
-db.user.validate({
+await db.user.validate({
   name: 'Martin Luther',
   unknownField: 'Some data'
-
-}).then(data => {
-  // { name: "Martin Luther" }
 })
+// { name: "Martin Luther" }
 
-db.user.validate({
+await db.user.validate({
   name: 'Martin Luther'
   address: { city: 'Eisleben' }
-
-}).catch(errs => {
-  // [{
-  //   detail: "Value needs to be at least 10 characters long.",
-  //   status: "400",
-  //   title: "address.city",
-  //   meta: {
-  //     field: "city",
-  //     model: "user",
-  //     rule: "minLength"
-  //   }
-  // }]
 })
-
+// Error [{
+//   detail: "Value needs to be at least 10 characters long.",
+//   status: "400",
+//   title: "address.city",
+//   meta: {
+//     field: "city",
+//     model: "user",
+//     rule: "minLength"
+//   }
+// }]
 ```
+
 ### Blacklisting
 
-Depending on the `update` option, you can augment the model's `schema.insertBL` or `schema.updateBL` by passing a custom `blacklist`:
+Depending on the `update` option, you can augment the model's `insertBL` or `updateBL` by passing a custom `blacklist`:
 
 ```js
 // Prevents `name` and `pets.$.name` (array) from being returned.
 user.validate({}, { blacklist: ['name', 'pets.name'] })
-// You can also whitelist any blacklisted fields found in schema's blacklist
+// You can also whitelist any blacklisted fields found in insertBL/updateBL
 user.validate({}, { blacklist: ['-name', '-pet'] })
 ```

package/docs/readme.md

@@ -6,8 +6,8 @@
 
 * User friendly API design, built around the awesome [Monk](https://automattic.github.io/monk/)
 * Simple CRUD operations with model population
-* Model validation deriving from your schema
-* Custom error messages can be defined in your schema
+* Model validation deriving from your model definitions
+* Custom error messages can be defined in your model definition
 * Normalised error responses ready for client consumption
 * Automatic mongodb index setup
 
@@ -83,20 +83,21 @@ Coming soon...
 
 ## Roadmap
 
-- Add FindOneAndUpdate
-- Add before/afterInsertUpdate
+- Add Aggregate
+- ~~Add FindOneAndUpdate~~
+- ~~Add beforeInsertUpdate / afterInsertUpdate~~
 - Bug: Setting an object literal on an ID field ('model') saves successfully
 - Population within array items
 - ~~Blacklist false removes all blacklisting~~
 - ~~Add project to insert/update/validate~~
 - ~~Whitelisting a parent will remove any previously blacklisted children~~
 - ~~Blacklist/project works the same across find/insert/update/validate~~
-- Automatic subdocument ids
+- Automatic embedded document ids/createdAt/updatedAt fields
 - Remove ACL default 'public read'
 - ~~Public db.arrayWithSchema method~~
 - Global after/before hooks
-- Split away from Monk (unless updated)
 - docs: Make the implicit ID query conversion more apparent
+- Split away from Monk (unless updated)
 
 ## Special Thanks
 

package/lib/model-crud.js

@@ -24,14 +24,13 @@ module.exports = {
     }
     try {
       opts = await this._queryObject(opts, 'insert')
-      let custom = ['blacklist', 'data', 'insert', 'model', 'respond', 'skipValidation',  'validateUndefined']
 
       // Validate
-      let data = await this.validate(opts.data || {}, { ...opts })
+      let data = await this.validate(opts.data || {}, opts) // was { ...opts }
 
       // Insert
       await util.runSeries(this.beforeInsert.map(f => f.bind(opts, data)))
-      let response = await this._insert(data, util.omit(opts, custom))
+      let response = await this._insert(data, util.omit(opts, this._queryOptions))
       await util.runSeries(this.afterInsert.map(f => f.bind(opts, response)))
 
       // Success/error
@@ -64,9 +63,8 @@ module.exports = {
       throw new Error(`The callback passed to ${this.name}.find() is not a function`)
     }
     try {
-      opts = await this._queryObject(opts, 'find', one)
-      let custom = ['blacklist', 'model', 'one', 'populate', 'project', 'query', 'respond']
       let lookups = []
+      opts = await this._queryObject(opts, 'find', one)
 
       // Get projection
       if (opts.project) opts.projection = this._getProjectionFromProject(opts.project)
@@ -80,7 +78,7 @@ module.exports = {
 
       // Wanting to populate?
       if (!opts.populate) {
-        var response = await this[`_find${opts.one? 'One' : ''}`](opts.query, util.omit(opts, custom))
+        var response = await this[`_find${opts.one? 'One' : ''}`](opts.query, util.omit(opts, this._queryOptions))
       } else {
         loop: for (let item of opts.populate) {
           let path = util.isObject(item)? item.as : item
@@ -157,18 +155,14 @@ module.exports = {
      * Find and update document(s) with monk, also auto populates
      * @param {object} opts
      *     @param {array|string|false} <opts.blacklist> - augment findBL/updateBL, `false` will remove all blacklisting
-     *     @param {array|string|false} <opts.blacklistFind> - augment findBL, `false` will remove all blacklisting
      *     @param {array} <opts.populate> - find population, see docs
      *     @param {array|string} <opts.project> - return only these fields, ignores blacklisting
-     *     @param {array|string} <opts.projectFind> - 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|false} <opts.blacklistUpdate> - augment updateBL, `false` will remove all blacklisting
-     *     @param {array|string} <opts.projectUpdate> - return only these fields, ignores blacklisting
      *     @param {array|string|true} <opts.skipValidation> - skip validation for this field name(s)
      *     @param {boolean} <opts.timestamps> - whether `updatedAt` is automatically updated
      *     @param {array|string|false} <opts.validateUndefined> - validates all 'required' undefined fields, true by
@@ -228,37 +222,49 @@ module.exports = {
       let data = opts.data
       let response = null
       let operators = util.pick(opts, [/^\$/])
-      let custom = [
-        'blacklist', 'data', 'model', 'one', 'populate', 'project', 'query', 'respond', 'skipValidation',
-        'validateUndefined'
-      ]
 
       // Validate
-      if (util.isDefined(data)) data = await this.validate(opts.data, { ...opts })
+      if (util.isDefined(data)) {
+        data = await this.validate(opts.data, opts) // was {...opts}
+      }
       if (!util.isDefined(data) && util.isEmpty(operators)) {
         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)
       await util.runSeries(this.beforeUpdate.map(f => f.bind(opts, data||{})))
+
       if (data && operators['$set']) {
         this.warn(`'$set' fields take precedence over the data fields for \`${this.name}.${type}()\``)
       }
       if (data || operators['$set']) {
         operators['$set'] = { ...data, ...(operators['$set'] || {}) }
       }
-      // Just peform a normal update if we need to populate a findOneAndUpdate
-      if (opts.populate && type == 'findOneAndUpdate') type ='update'
+
+      // findOneAndUpdate, get 'find' projection
+      if (type == 'findOneAndUpdate') {
+        if (opts.project) opts.projection = this._getProjectionFromProject(opts.project)
+        else opts.projection = this._getProjectionFromBlacklist('find', opts.blacklist)
+        // Just peform a normal update if we need to populate a findOneAndUpdate
+        if (opts.populate) type = 'update'
+      }
+
       // Update
-      let update = await this['_' + type](opts.query, operators, util.omit(opts, custom))
+      let update = await this['_' + type](opts.query, operators, util.omit(opts, this._queryOptions))
       if (type == 'findOneAndUpdate') response = update
       else if (update.n) response = Object.assign(Object.create({ _output: update }), operators['$set']||{})
 
       // Hook: afterUpdate (doesn't have access to validated data)
       if (response) await util.runSeries(this.afterUpdate.map(f => f.bind(opts, response)))
 
+      // Hook: afterFind if findOneAndUpdate
+      if (response && type == 'findOneAndUpdate') {
+        response = await this._processAfterFind(response, opts.projection, opts)
+      }
+
       // Success
       if (cb) cb(null, response)
       else if (opts.req && opts.respond) opts.req.res.json(response)
@@ -288,12 +294,11 @@ module.exports = {
     }
     try {
       opts = await this._queryObject(opts, 'remove')
-      let custom =  ['model', 'query', 'respond']
       if (util.isEmpty(opts.query)) throw new Error('Please specify opts.query')
 
       // Remove
       await util.runSeries(this.beforeRemove.map(f => f.bind(opts)))
-      let response = await this._remove(opts.query, util.omit(opts, custom))
+      let response = await this._remove(opts.query, util.omit(opts, this._queryOptions))
       await util.runSeries(this.afterRemove.map(f => f.bind(response)))
 
       // Success
@@ -626,4 +631,11 @@ module.exports = {
     }, this)
   },
 
+  _queryOptions: [
+    // todo: remove type properties
+    'blacklist', 'data', 'find', 'findOneAndUpdate', 'insert', 'model', 'one', 'populate', 'project',
+    'projectionValidate', 'query', 'remove', 'req', 'respond', 'skipValidation', 'type', 'update',
+    'validateUndefined',
+  ],
+
 }

package/lib/model-validate.js

@@ -36,8 +36,8 @@ module.exports = {
       opts.skipValidation = opts.skipValidation === true ? true : util.toArray(opts.skipValidation||[])
 
       // Get projection
-      if (opts.project) opts.projection = this._getProjectionFromProject(opts.project)
-      else opts.projection = this._getProjectionFromBlacklist(opts.update ? 'update' : 'insert', opts.blacklist)
+      if (opts.project) opts.projectionValidate = this._getProjectionFromProject(opts.project)
+      else opts.projectionValidate = this._getProjectionFromBlacklist(opts.update ? 'update' : 'insert', opts.blacklist)
 
       // Hook: beforeValidate
       await util.runSeries(this.beforeValidate.map(f => f.bind(opts, data)))
@@ -132,7 +132,7 @@ module.exports = {
         }
 
         // Ignore blacklisted
-        if (this._pathBlacklisted(path3, opts.projection) && !schema.defaultOverride) return
+        if (this._pathBlacklisted(path3, opts.projectionValidate) && !schema.defaultOverride) return
         // Ignore insert only
         if (opts.update && schema.insertOnly) return
         // Ignore virtual fields
@@ -245,7 +245,7 @@ module.exports = {
     if (typeof value === 'undefined' && (!validateUndefined  || !rule.validateUndefined)) return
 
     // Ignore null (if nullObject is set on objects or arrays)
-    if (value === null && (field.isObject || field.isArray) && field.nullObject) return
+    if (value === null && (field.isObject || field.isArray) && field.nullObject && !rule.validateNull) return
 
     // Ignore null
     if (value === null && !(field.isObject || field.isArray) && !rule.validateNull) return

package/lib/util.js

@@ -163,8 +163,15 @@ module.exports = {
      * Mutates dot notation objects into a deep object
      * @param {object}
      */
+    let original = this.deepCopy(obj)
     for (let key in obj) {
-      if (key.indexOf('.') !== -1) recurse(key, obj[key], obj)
+      if (key.indexOf('.') !== -1) {
+        recurse(key, obj[key], obj)
+      } else {
+        // Ordinary values may of been updated by the bracket notation values, we are
+        // reassigning, trying to preserve the order of keys (not always guaranteed in for loops)
+        obj[key] = original[key]
+      }
     }
     return obj
     function recurse(str, val, obj) {
@@ -188,6 +195,7 @@ module.exports = {
   },
 
   parseFormData: function(obj) {
+    let original = this.deepCopy(obj)
     /**
      * Mutates FormData (bracket notation) objects into a deep object
      * @param {object}
@@ -203,6 +211,10 @@ module.exports = {
         }
         if (key.indexOf('[') !== -1) {
           setup(key)
+        } else {
+          // Ordinary values may of been updated by the bracket notation values, we are
+          // reassigning, trying to preserve the order of keys (not always guaranteed in for loops)
+          obj[key] = original[key]
         }
       }
       res(obj)

package/package.json

@@ -2,7 +2,7 @@
   "name": "monastery",
   "description": "⛪ A straight forward MongoDB ODM built around Monk",
   "author": "Ricky Boyce",
-  "version": "1.36.0",
+  "version": "1.36.3",
   "license": "MIT",
   "repository": "github:boycce/monastery",
   "homepage": "https://boycce.github.io/monastery/",