monastery 1.36.1 → 1.37.0

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,10 +6,12 @@
 
 * 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
+* CRUD operations can accept bracket (multipart/form-data) and dot notation data formats, you can also mix these together
+
 
 ## Install
 
@@ -63,12 +65,10 @@ db.user.insert({
 ```
 ## Debugging
 
-This package uses [Debug](https://github.com/visionmedia/debug) which allows you to see different levels of output:
+This package uses [debug](https://github.com/visionmedia/debug) which allows you to set different levels of output via the `DEBUG` environment variable. Due to known limations `monastery:warning` and `monastery:error` are forced on, you can however disable these via [manager settings](./manager).
 
 ```bash
-$ DEBUG=monastery:info
-# or show all levels of output, currently shows the same output as above
-$ DEBUG=monastery:*
+$ DEBUG=monastery:info # shows operation information
 ```
 
 To run isolated tests with Jest:
@@ -83,15 +83,16 @@ Coming soon...
 
 ## Roadmap
 
+- Add Aggregate
 - ~~Add FindOneAndUpdate~~
-- Add before/afterInsertUpdate
+- ~~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

package/lib/index.js

@@ -16,13 +16,19 @@ module.exports = function(uri, opts, fn) {
    * @param {object} opts
    * @return monk manager
    */
+  if (!opts) opts = {}
   let monasteryOpts = [
-    'defaultObjects', 'imagePlugin', 'limit', 'nullObjects', 'timestamps', 'useMilliseconds'
+    'defaultObjects', 'hideWarnings', 'hideErrors', 'imagePlugin', 'limit', 'nullObjects',
+    'timestamps', 'useMilliseconds',
   ]
 
-  if (!opts) opts = {}
+  // Note: Debug doesn't allow debuggers to be enabled by default
+  let info = debug('monastery:info')
+  let warn = debug('monastery:warn' + (opts.hideWarnings ? '' : '*'))
+  let error = debug('monastery:error' + (opts.hideErrors ? '' : '*'))
+
   if (util.isDefined(opts.defaultFields)) {
-    var depreciationWarningDefaultField = true
+    warn('opts.defaultFields has been depreciated in favour of opts.timestamps')
     opts.timestamps = opts.defaultFields
     delete opts.defaultFields
   }
@@ -44,20 +50,15 @@ module.exports = function(uri, opts, fn) {
   manager.model = require('./model')
   manager.models = models
   manager.parseData = util.parseData.bind(util)
-  manager.warn = debug('monastery:warn')
-  manager.error = debug('monastery:error*')
-  manager.info = debug('monastery:info')
+  manager.info = info
+  manager.warn = warn
+  manager.error = error
 
   // Add opts onto manager
   for (let key of monasteryOpts) {
     manager[key] = opts[key]
   }
 
-  // Depreciation warnings
-  if (depreciationWarningDefaultField) {
-    manager.error('opts.defaultFields has been depreciated in favour of opts.timestamps')
-  }
-
   // Initiate any plugins
   if (manager.imagePlugin) {
     manager.imagePluginFile.setup(manager, util.isObject(manager.imagePlugin)? manager.imagePlugin : {})

package/lib/model-crud.js

@@ -238,7 +238,7 @@ module.exports = {
       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}()\``)
+        this.info(`'$set' fields take precedence over the data fields for \`${this.name}.${type}()\``)
       }
       if (data || operators['$set']) {
         operators['$set'] = { ...data, ...(operators['$set'] || {}) }

package/lib/model-validate.js

@@ -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
@@ -266,8 +266,9 @@ module.exports = {
 
   _ignoredRules: [ // todo: change name? i.e. 'specialFields'
     // Need to remove filesize and formats..
-    'default', 'defaultOverride', 'filename', 'filesize', 'fileSize', 'formats', 'image', 'index', 'insertOnly',
-    'model', 'nullObject', 'params', 'getSignedUrl', 'timestampField', 'type', 'virtual'
+    'awsAcl', 'awsBucket', 'default', 'defaultOverride', 'filename', 'filesize', 'fileSize', 'formats',
+    'image', 'index', 'insertOnly', 'model', 'nullObject', 'params', 'path', 'getSignedUrl', 'timestampField',
+    'type', 'virtual',
   ]
 
 }

package/lib/model.js

@@ -86,7 +86,7 @@ let Model = module.exports = function(name, opts, manager) {
   if (typeof this.manager[name] === 'undefined' || typeof this.manager.model[name] !== 'undefined') {
     this.manager[name] = this
   } else {
-    this.warn(`Your model name '${name}' is conflicting, you are only able to
+    this.warn(`Your model name '${name}' is conflicting with an builtin manager property, you are only able to
     access this model via \`db.model.${name}\``)
   }
 

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.1",
+  "version": "1.37.0",
   "license": "MIT",
   "repository": "github:boycce/monastery",
   "homepage": "https://boycce.github.io/monastery/",
@@ -17,7 +17,7 @@
     "mongo odm"
   ],
   "scripts": {
-    "dev": "npm run lint & DEBUG=-monastery:info jest --watchAll --runInBand --verbose=false",
+    "dev": "npm run lint & jest --watchAll --runInBand --verbose=false",
     "docs": "cd docs && bundle exec jekyll serve --livereload --livereload-port 4001",
     "lint": "eslint ./lib ./plugins ./test",
     "mong": "nodemon resources/mong.js",