monastery 3.4.2 → 3.5.0

package/changelog.md

@@ -2,6 +2,10 @@
 
 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.5.0](https://github.com/boycce/monastery/compare/3.4.3...3.5.0) (2024-12-20)
+
+### [3.4.3](https://github.com/boycce/monastery/compare/3.4.2...3.4.3) (2024-08-27)
+
 ### [3.4.2](https://github.com/boycce/monastery/compare/3.4.1...3.4.2) (2024-08-24)
 
 ### [3.4.1](https://github.com/boycce/monastery/compare/3.4.0...3.4.1) (2024-08-09)

package/docs/definition/index.md

@@ -304,7 +304,7 @@ You are able to define custom error messages for each field rule.
 
 ### Operation hooks
 
-You are able provide an array of callbacks to these model operation hooks. If you need to throw an error asynchronously, please pass an error as the first argument to `next()`, e.g. `next(new Error('Your error here'))`. You can also access the operation details via `this` in each callback.
+You are able provide an array of promises to the following model operation hooks. `this` is the operation details.
 
 ```js
 {

package/docs/manager/index.md

@@ -6,7 +6,7 @@ has_children: true
 
 # Manager
 
-Monastery manager constructor.
+Creates a new manager instance and makes the first instance available globally via the `db`.
 
 ### Arguments
 
@@ -24,26 +24,27 @@ Monastery manager constructor.
 
 ### Returns
 
-A manager instance.
+A new manager instance.
 
 ### Example
 
 ```js
-import monastery from 'monastery'
+import db from 'monastery'
 
-const db = monastery('localhost/mydb', options)
+// this manager instance is now available via the `db` object on subsequent imports
+const manager = db.manager('localhost/mydb', options)
 // replica set
-const db = monastery('localhost/mydb,192.168.1.1')
+const manager = db.manager('localhost/mydb,192.168.1.1')
 // you can wait for the connection (which is not required before calling methods)
-const db = await monastery('localhost/mydb,192.168.1.1', { promise: true })
+const manager = await db.manager('localhost/mydb,192.168.1.1', { promise: true })
 ```
 
 You can also listen for errors or successful connection using these hooks
 ```js
-db.onOpen((manager) => {
+manager.onOpen((manager) => {
   // manager.client is connected...
 })
-db.onError((err) => {
+manager.onError((err) => {
   // connection error
 })
 ```

package/docs/manager/model.md

@@ -11,7 +11,9 @@ Sets up a model, retrieves a collection, and sets up any required indexes
 
 `name` *(string)*: name of the mongo collection
 
-[`definition`] *(object)*: [definition](../definition)
+`definition` *(object)*: [definition](../definition)
+
+`waitForIndexes` *(boolean)*: wait for indexes to be setup (returns a promise instead of a model)
 
 ### Returns
 

package/docs/manager/models.md

@@ -13,7 +13,7 @@ Setup model definitions from a folder location
 
 [`options`] *(object)*:
   - [`commonJs=false`] *(boolean)*: for old commonjs projects, you will need to set this to `true` which uses `require` instead of `import` (removed in `3.0.0`)
-  - [`waitForIndexes=false`] *(boolean)*: returns a proimse that waits for the Mongo collection indexes to be setup
+  - [`waitForIndexes=false`] *(boolean)*: wait for collection indexes to be setup
 
 ### Returns
 
@@ -39,5 +39,5 @@ export default { // Make sure the model definition is exported as the default
 ```
 
 ```js
-await db.models(__dirname + "models")
+await db.models(__dirname + 'models', { waitForIndexes: true })
 ```

package/docs/readme.md

@@ -35,10 +35,10 @@ $ npm install --save monastery
 ## Usage
 
 ```javascript
-import monastery from 'monastery'
+import db from 'monastery'
 
 // Initialize a monastery manager
-const db = monastery('localhost/mydb')
+db.manager('localhost/mydb')
 
 // Define a model
 db.model('user', {
@@ -96,6 +96,7 @@ You can view MongoDB's [compatibility table here](https://www.mongodb.com/docs/d
   - db.catch/then() moved to db.onError/db.onOpen()
   - next() is now redundant when returning promises from hooks, e.g. `afterFind: [async (data) => {...}]`
   - deep paths in data, e.g. `books[].title` are now validated, and don't replace the whole object, e.g. `books`
+  - `db()` moved to `db.manager()`
 
 ## v2 Breaking Changes
 

package/lib/index.js

@@ -1,301 +1,32 @@
-/*eslint-disable max-len*/
-const fs = require('fs')
-const debug = require('debug')
-const path = require('path')
-const EventEmitter = require('events').EventEmitter
+const Manager = require('./manager')
 const inherits = require('util').inherits
-const { MongoClient } = require('mongodb')
-const Collection = require('./collection.js')
-const imagePluginFile = require('../plugins/images/index.js')
-const Model = require('./model.js')
 const rules = require('./rules.js')
-const util = require('./util.js')
 
-function Manager(uri, opts) {
-  /**
-   * Constructs a new manager which contains a new MongoDB client
-   * 
-   * @param {String|Array|Object} uri - MongoDB connection URI string / replica set, or reuse a MongoClient instance
-   * @param {Object} opts -
-   *   {String} <opts.databaseName> - the name of the database
-   *   {Boolean} <opts.promise(manager)> - return a promise
-   * 
-   * @return {Connection|Promise}
-   * @link https://www.mongodb.com/docs/drivers/node/v5.9/quick-reference/
-   * @link https://mongodb.github.io/node-mongodb-native/ (all versions)
-   */
-  if (!opts) opts = {}
-  if (!(this instanceof Manager)) return new Manager(uri, opts)
+function Monastery() {
+  let hasDefaultManager = false
 
-  // opts: timestamps
-  if (typeof opts.defaultFields != 'undefined') throw Error('opts.defaultFields has been depreciated, use opts.timestamps')
-  if (typeof opts.timestamps == 'undefined') opts.timestamps = true
-
-  // opts: logLevel
-  if (typeof opts.logLevel == 'undefined') opts.logLevel = 2
-
-  // opts: separate out monastery options
-  const mongoOpts = Object.keys(opts||{}).reduce((acc, key) => {
-    if (
-      ![
-        'databaseName', 'defaultObjects', 'logLevel', 'imagePlugin', 'limit', 'noDefaults', 'nullObjects',
-        'promise', 'timestamps', 'useMilliseconds',
-      ].includes(key)) {
-        acc[key] = opts[key]
-    }
-    return acc
-  }, {})
-
-  // Add properties
-  this.uri = uri
-  this.error = debug('monastery:error' + (opts.logLevel > 0 ? '*' : ''))
-  this.warn = debug('monastery:warn' + (opts.logLevel > 1 ? '*' : ''))
-  this.info = debug('monastery:info' + (opts.logLevel > 2 ? '*' : ''))
-  this.opts = opts
-  this.beforeModel = []
-  this.collections = {}
-  this._openQueue = []
-
-  // If there is no DEBUG= environment variable, we will need to force the debugs on (due to bug on debug@4.3.4)
-  if (!debug.namespaces) {
-    if (opts.logLevel > 0) this.error.enabled = true
-    if (opts.logLevel > 1) this.warn.enabled = true
-    if (opts.logLevel > 2) this.info.enabled = true
-  }
-  
-  // Create a new MongoDB Client
-  if (typeof this.uri == 'string' || Array.isArray(this.uri)) {
-    this.uri = this.connectionString(this.uri, opts.databaseName)
-    this.client = new MongoClient(this.uri, mongoOpts)
-  } else {
-    this.client = this.uri
-  }
-
-  // Listen to MongoDB events
-  for (let eventName of ['close', 'error', 'timeout']) {
-    this.client.on(eventName, (e) => this.emit(eventName, e))
-  }
-
-  // Listen to custom open event
-  this.on('open', () => {
-    // wait for all the on('open') events to get called first
-    setTimeout(() => {
-      for (let item of this._openQueue) {
-        item()
-      }
-    })
-  })
-
-  // Initiate any plugins
-  if (opts.imagePlugin) {
-    imagePluginFile.setup(this, util.isObject(opts.imagePlugin) ? opts.imagePlugin : {})
-  }
-
-  // Expose the last manager
-  module.exports.manager = this
-
-  // Connect to the database
-  if (opts.promise) return this.open()
-  else this.open()
-}
-
-Manager.prototype.arrayWithSchema = function(array, schema) {
-  array.schema = schema
-  return array
-}
-
-Manager.prototype.close = async function() {
-  /**
-   * Close the database connection, gracefully
-   */
-  const _close = async () => {
-    this.emit(this._state = 'closing')
-    await this.client.close()
-    this.emit(this._state = 'close')
-  }
-  if (this._state == 'open') {
-    return await _close()
-
-  } else if (this._state == 'opening') {
-    return new Promise((resolve) => {
-      this._openQueue.push(() => _close().then(resolve))
-    })
-
-  } else if (this._state == 'close' || this._state == 'closing') {
-    return
-  }
-}
-
-Manager.prototype.command = function(...args) {
-  /**
-   * Run a raw MongoDB command
-   */
-  return this.db.command(...args)
-}
-
-Manager.prototype.connectionString = function(uri, databaseName) {
-  /**
-   * get the connection string
-   * @param {string|array} uri
-   * @param {string} <databaseName>
-   * @return {string}
-   */
-  if (!uri) {
-    throw Error('No connection URI provided.')
-  }
-  // uri: array, sort out the connection string
-  if (util.isArray(uri)) {
-    if (!databaseName) {
-      for (var i=0, l=uri.length; i<l; i++) {
-        if (!databaseName) databaseName = uri[i].replace(/([^\/])+\/?/, '') // eslint-disable-line
-        uri[i] = uri[i].replace(/\/.*/, '')
-      }
-    }
-    uri = uri.join(',') + '/' + databaseName
-  }
-  // uri: string, sort out the connection string
-  if (typeof uri === 'string') {
-    if (!/^mongodb(\+srv)?:\/\//.test(uri)) {
-      uri = 'mongodb://' + uri
-    }
-  }
-  return uri
-}
-
-Manager.prototype.get = function(name, options) {
-  /**
-   * Returns a MongoDB collection
-   * @param {String} name
-   * @param {Object} [options] - options to pass to the collection
-   * @return {MongoDB Collection}
-   */
-  if (!this.collections[name] || (options||{}).cache === false) {
-    delete (options||{}).cache
-    this.collections[name] = new Collection(this, name, options)
-  }
-  return this.collections[name]
-}
-
-Manager.prototype.id = function(str) {
-  return util.id(str)
-}
-
-Manager.prototype.isId = function(value) {
-  return util.isId(value)
-}
-
-Manager.prototype.models = async function(pathname, opts) {
-  /**
-   * Setup model definitions from a folder location
-   * @param {string} pathname
-   * @param {object} opts:
-   *   @param {boolean} opts.waitForIndexes - Wait for indexes to be created?
-   * @return {Promise(object)} - e.g. { user: , article: , .. }
-   * @this Manager
-   */
-  let out = {}
-  let { waitForIndexes } = opts || {}
-  if (!pathname || typeof pathname !== 'string') {
-    throw 'The path must be a valid pathname'
-  }
-  let filenames = fs.readdirSync(pathname)
-  for (let filename of filenames) {
-    // Ignore folders
-    if (!filename.match(/\.[cm]?js$/)) continue
-    let name = filename.replace('.js', '')
-    let filepath = path.join(pathname, filename)
-    // We can't use require() here since we need to be able to import both CJS and ES6 modules
-    let definition = ((await import(filepath))||{}).default
-    // When a commonJS project uses babel (e.g. `nodemon -r @babel/register`, similar to `-r esm`), import() 
-    // will return ES6 model definitions in another nested `default` object
-    if (definition && definition.default) definition = definition.default
-    if (!definition) throw new Error(`The model definition for '${name}' must export a default object`)
-    // Wait for indexes to be created?
-    if (waitForIndexes) out[name] = await this.model(name, { ...definition, waitForIndexes })
-    else out[name] = this.model(name, definition)
-  }
-  return out
-}
-
-Manager.prototype.onError = function(fn) {
-  /**
-   * Called when an error occurs when trying to connect to the MongoClient.
-   * @param {Function} fn
-   * @return {Promise}
-   */
-  return new Promise((resolve, reject) => {
-    this.on('error', (err) => {
-      resolve(err)
-    })
-  }).then((err) => {
-    return fn(err)
-  })
-}
-
-Manager.prototype.onOpen = function(fn) {
-  /**
-   * Called when a successful MongoClient connection has been made.
-   * @param {Function} fn
-   * @return {Promise(manager)}
-   */
-  return new Promise((resolve, reject) => {
-    if (this._state == 'open') {
-      resolve(this)
-    }
-    this.on('open', () => {
-      resolve(this)
-    })
-    this.on('error', (err) => {
-      reject(err)
-    })
-  }).then((err) => { // If `then` is not chained, the error will be thrown, detached!
-    return fn(err)
-  })
-}
-
-Manager.prototype.open = async function() {
-  /**
-   * Connect to the database
-   * @return {Promise(manager)}
-   */
-  try {
-    this._state = 'opening'
-    this.db = this.client.db()
-    await this.client.connect() // now optional since db().command() will auto-connect
-    this.emit(this._state = 'open', this)
-    return this
-
-  } catch (err) {
-    this._state = 'closed'
-    // Only emit the error if there are listeners, since it will throw an unhandled error
-    if (this.listeners('error').length > 0) {
-      this.emit('error', err)
-    }
-    if (this.opts.promise || this.listeners('error').length == 0) {
-      throw new Error(err)
+  this.manager = function(uri, opts) {
+    const manager = new Manager(uri, opts)
+    // Inherit the default manager onto Monastery once
+    if (!hasDefaultManager) {
+      hasDefaultManager = true
+      Object.assign(this, manager)
     }
+    return manager
   }
 }
 
-Manager.prototype.parseData = function(obj, parseBracketToDotNotation, parseDotNotation) {
-  return util.parseData(obj, parseBracketToDotNotation, parseDotNotation)
-}
+// Inherit Manager prototypes onto Monastery
+inherits(Monastery, Manager)
 
-Manager.prototype.model = Model
-Manager.prototype.getSignedUrl = imagePluginFile.getSignedUrl
-Manager.prototype._getSignedUrl = () => { 
-  throw new Error('monastery._getSignedUrl() has been moved to monastery.getSignedUrl()')
-}
-
-inherits(Manager, EventEmitter)
-module.exports = Manager
+// Exports
+module.exports = new Monastery()
+module.exports.arrayWithSchema = Manager.prototype.arrayWithSchema
+module.exports.getSignedUrl = Manager.prototype.getSignedUrl
 module.exports.id = Manager.prototype.id
 module.exports.isId = Manager.prototype.isId
-module.exports.arrayWithSchema = Manager.prototype.arrayWithSchema
-module.exports.parseData = Manager.prototype.parseData
 module.exports.parseBracketNotation = Manager.prototype.parseBracketNotation
 module.exports.parseBracketToDotNotation = Manager.prototype.parseBracketToDotNotation
+module.exports.parseData = Manager.prototype.parseData
 module.exports.parseDotNotation = Manager.prototype.parseDotNotation
-module.exports.getSignedUrl = Manager.prototype.getSignedUrl
-module.exports.manager = null
 module.exports.rules = rules