monastery 3.5.6 → 3.5.8

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.8](https://github.com/boycce/monastery/compare/3.5.6...3.5.8) (2025-12-23)
+
+### [3.5.7](https://github.com/boycce/monastery/compare/3.5.6...3.5.7) (2025-09-16)
+
 ### [3.5.6](https://github.com/boycce/monastery/compare/3.5.5...3.5.6) (2025-06-15)
 
 ### [3.5.5](https://github.com/boycce/monastery/compare/3.5.4...3.5.5) (2025-06-14)

package/docs/definition/index.md

@@ -147,7 +147,7 @@ fieldType: {
 
 ### MongoDB indexes
 
-You are able to automatically setup MongoDB indexes via the `index` field option.
+You are able to define MongoDB indexes via the `index` field option, these are automatically on initialisation. **Note, Monastery doesn't delete old indexes**.
 
 ```js
 fieldType: {
@@ -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 promises to the following model operation hooks. `this` is the operation details.
+You are able provide an array of promises to the following model operation hooks.
 
 ```js
 {
@@ -318,7 +318,7 @@ You are able provide an array of promises to the following model operation hooks
   beforeInsertUpdate: [await function(data) {}],
   beforeUpdate: [await function(data) {}],
   beforeRemove: [await function() {}],
-  beforeValidate: [await function(data) {}],
+  beforeValidate: [await function(data) {}], // runs prior to beforeInsert/Update
 
   // You can also return an object which will be passed to the next hook in the chain, or if it's the last hook, returned as the result:
   afterFind: [await function(data) {
@@ -328,6 +328,20 @@ You are able provide an array of promises to the following model operation hooks
 }
 ```
 
+The context (`this`) inside each hook will contain extra information relating to the operation, for an example, a basic update operation may contain the following fields:
+```js
+{
+  query: { _id: new ObjectId("68d66a33ae584af64197c971") },
+  data: { name: 'John Doe' },
+  limit: 1,
+  sort: { createdAt: -1 },
+  type: 'update',
+  model: {...}, // Model reference,
+  skipValidation: [],
+  // ...
+}
+```
+
 ### Methods
 
 You are able define reusable methods in the definition which is handy for storing related functions.

package/docs/model/find.md

@@ -123,12 +123,9 @@ user.find({
     as: 'myBooks',
     from: 'book',
     let: { userId: '$_id' },
-    pipeline: [{
-      $match: {
-        $expr: {
-          $eq: ['$bookOwnerId', '$$userId']
-        }
-      }
+    pipeline: [
+      { $match: { $expr: { $eq: ['$bookOwnerId', '$$userId'] } } },
+      { $project: { '_id': 1, 'bookTitle': 1 }}, // <-- optional line to make responses smaller.
     }]
   }]
 })

package/docs/model/insert.md

@@ -5,7 +5,7 @@ parent: Model
 
 # `model.insert`
 
-Validate and insert document(s) in a collection and calls model hooks: `beforeInsert`,  `afterInsert`
+Validate and insert document(s) in a collection and calls model hooks: `beforeValidate`, `beforeInsert`, `afterInsert`
 
 ### Arguments
 

package/docs/model/update.md

@@ -5,14 +5,14 @@ parent: Model
 
 # `model.update`
 
-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.
+Update document(s) in a collection and calls model hooks: `beforeValidate`,  `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)*
 
 - `query` *(object\|id)*: [`MongoDB query document`](https://www.mongodb.com/docs/v5.0/tutorial/query-documents/), or id
-- [`data`](#data) *(object)* - data that's validated against the model fields (always wrapped in `{ $set: .. }`)
+- [`data`](#data) *(object)* - data that's validated against the model fields, which eventually gets 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\|boolean)*:  skip validation for these fields, or pass `true` to skip all fields and validation hooks
@@ -42,7 +42,7 @@ await user.update({ query: { name: 'foo' }, data: { name: 'bar' }})
 
 ### Data
 
-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.
+Data that's validated against the model fields, which eventually gets 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.
 

package/docs/readme.md

@@ -138,6 +138,7 @@ You can view MongoDB's [compatibility table here](https://www.mongodb.com/docs/d
 - Add soft remove plugin
 - ~~Added deep path validation support for updates~~
 - ~~Added option skipHooks~~
+- beforeValidate should pass the document rather than the whole array of documents
 
 ## Debugging
 

package/lib/manager.js

@@ -100,7 +100,8 @@ function Manager(uri, opts, parent) {
   // Update the parent manager with the new manager
   if (!hasDefaultManager && parent) hasDefaultManager = true
   if (opts.promise) return that.open()
-  else that.open()
+  that.open()
+  return that // return that since it may be a different context
 }
 
 Manager.prototype.manager = function(uri, opts) {
@@ -134,7 +135,7 @@ Manager.prototype.close = async function() {
   }
 }
 
-Manager.prototype.command = function(...args) {
+Manager.prototype.rawCommand = function(...args) {
   /**
    * Run a raw MongoDB command
    */

package/lib/rules.js

@@ -83,7 +83,7 @@ module.exports = {
     },
     fn: function(x) {
       if (util.isString(x) && x.match(/^[+-][0-9]+$/)) return true
-      return typeof x === 'number' && (parseInt(x) === x)
+      return typeof x === 'number' && (parseInt(x + '') === x)
     },
   },
   isNumber: {

package/lib/util.js

@@ -71,22 +71,28 @@ module.exports = {
   forceArray: function(value) {
     return this.isArray(value)? value : [value]
   },
+
+  /**
+   * @typedef {string} HexString
+   * @description A hex string of 24 characters
+   */
   
   /**
    * Casts to ObjectId
-   * @param {string|ObjectId} str - string = hex string
-   * @return {ObjectId}
+   * @param {HexString|ObjectId} [value] - empty string = new ObjectId('')
    */
-  id: function(str) {
-    if (str == null) return new ObjectId()
-    return typeof str === 'string' ? ObjectId.createFromHexString(str) : str
+  id: function(value) {
+    if (value === undefined) return new ObjectId()
+    else if (typeof value === 'string') return ObjectId.createFromHexString(value)
+    else if (value instanceof ObjectId) return value
+    else throw new Error(`Monastery: invalid value "${value}" passed to id(value?: HexString|ObjectId).`)
   },
 
   inArray: (array, key, value) => {
     /**
      * Property match inside an array of objects
      * (For a string/number value check just use [].includes(x))
-     * @param {string} <key> - optional to match across on a colleciton of objects
+     * @param {string} [key] - optional to match across on a colleciton of objects
      * @param {any} value
      */
     if (!array || typeof key == 'undefined') return false
@@ -361,7 +367,7 @@ module.exports = {
     /**
      * Runs functions in series
      * 
-     * @param {function(err, result)[]}  tasks - array of functions
+     * @param {((err: any, result: any) => any)[]}  tasks - array of functions
      * @param {string}  hookName - e.g. 'afterFind'
      * @param {any}  data - data to pass to the first function
      * 

package/package.json

@@ -2,7 +2,7 @@
   "name": "monastery",
   "description": "⛪ A simple, straightforward MongoDB ODM",
   "author": "Ricky Boyce",
-  "version": "3.5.6",
+  "version": "3.5.8",
   "license": "MIT",
   "repository": "github:boycce/monastery",
   "homepage": "https://boycce.github.io/monastery/",

package/test/collection.js

@@ -425,8 +425,8 @@ test('bulkWrite', async () => {
 })
 
 test('drop > should not throw when dropping an empty db', async () => {
-  const result = await db.get('dropDB-' + Date.now()).drop().catch(() => false)
-  expect(result).toBeTruthy()
+  await db.get('dropDB-' + Date.now()).drop().catch(() => false)
+  // expect(result).toBeUndefined()
 })
 
 test('caching collections', () => {

package/test/manager.js

@@ -8,12 +8,12 @@ test('manager > basics', async () => {
   // Basic find command
   expect(await db.db.collection('non-collection').findOne({})).toEqual(null)
   // Raw MongoDB ping command
-  expect(await db.command({ ping: 1 })).toMatchObject({ ok: 1 }) // cluster connections return extra fields
+  expect(await db.rawCommand({ ping: 1 })).toMatchObject({ ok: 1 }) // cluster connections return extra fields
   db.close()
 })
 
 test('manager > uri error', async () => {
-  expect(() => monastery.manager('', {})).toThrow('No connection URI provided.')
+  expect(() => monastery.manager('', {})).toThrow('No monastery connection URI provided.')
 })
 
 test('manager > onError', async () => {
@@ -21,7 +21,7 @@ test('manager > onError', async () => {
   const db = monastery.manager('localhost:1234/monastery', { serverSelectionTimeoutMS: 500 })
   let error, isAPromise
   await db.onError((res) => { error = res.message }).then(() => { isAPromise = true })
-  expect(error).toEqual('connect ECONNREFUSED 127.0.0.1:1234')
+  expect(error).toContain('connect ECONNREFUSED 127.0.0.1:1234')
   expect(isAPromise).toEqual(true)
   db.close()
 })
@@ -67,7 +67,7 @@ test('manager > return a promise', async () => {
 
 test('manager > return a promise with uri error', async () => {
   await expect(monastery.manager('badlocalhost/monastery', { serverSelectionTimeoutMS: 500, promise: true }))
-    .rejects.toThrow('getaddrinfo EAI_AGAIN badlocalhost')
+    .rejects.toThrow(/getaddrinfo ENOTFOUND badlocalhost/)
 })
 
 test('manager > reuse MongoDB Client', async () => {

package/types/lib/manager.d.ts

@@ -6,7 +6,7 @@ declare class Manager {
     arrayWithSchema(array: any, schema: any): any;
     close(): Promise<any>;
     _state: string;
-    command(...args: any[]): any;
+    rawCommand(...args: any[]): any;
     connectionString(uri: any, databaseName: any): any;
     get(name: any, options: any): any;
     id(str: any): import("bson").ObjectId;

package/types/lib/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../lib/manager.js"],"names":[],"mappings":";AAYA,gEAuFC;;IAvFD,8CAuFC;IAED,sCAEC;IAED,8CAGC;IAED,sBAoBC;IAfqB,eAAuB;IAiB7C,6BAKC;IAED,mDA2BC;IAED,kCAYC;IAED,sCAEC;IAED,0BAEC;IAED,8CAsCC;IAED,+BAiBC;IAED,8BAuBC;IAED,sBAsBC;IAfG,QAA0B;IAiB9B,gFAEC;IAED,oBAAuB;IAEvB,2EAA8B;IAE9B,uBAEC"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../lib/manager.js"],"names":[],"mappings":";AAYA,gEA4FC;;IA5FD,8CA4FC;IAED,sCAEC;IAED,8CAGC;IAED,sBAoBC;IAfqB,eAAuB;IAiB7C,gCAKC;IAED,mDA2BC;IAED,kCAYC;IAED,sCAEC;IAED,0BAEC;IAED,8CAsCC;IAED,+BAiBC;IAED,8BAuBC;IAED,sBAsBC;IAfG,QAA0B;IAiB9B,gFAEC;IAED,oBAAuB;IAEvB,2EAA8B;IAE9B,uBAEC"}