monastery 3.5.7 → 3.5.8

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.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)

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 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/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/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.7",
+  "version": "3.5.8",
   "license": "MIT",
   "repository": "github:boycce/monastery",
   "homepage": "https://boycce.github.io/monastery/",

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"}