dobo 2.31.0 → 2.33.0

package/lib/factory/model/validate.js

@@ -4,7 +4,9 @@ const excludedTypes = ['object']
 const excludedNames = []
 
 /**
+ * List of available string validators to check against model's properties and rules
  * @typedef {string[]} TValidatorString
+ * @memberof DoboModel
  * @property {string} 0=alphanum
  * @property {string} 1=base64
  * @property {string} 2=case
@@ -35,7 +37,9 @@ const excludedNames = []
  */
 
 /**
+ * List of available number validators to check against model's properties and rules
  * @typedef {string[]} TValidatorNumber
+ * @memberof DoboModel
  * @property {string} 0=great
  * @property {string} 1=less
  * @property {string} 2=max
@@ -49,33 +53,51 @@ const excludedNames = []
  */
 
 /**
+ * List of available boolean validators to check against model's properties and rules
  * @typedef {string[]} TValidatorBoolean
+ * @memberof DoboModel
  * @property {string} 0=falsy
  * @property {string} 1=sensitive
  * @property {string} 2=truthy
  */
 
 /**
+ * List of available date validators to check against model's properties and rules
  * @typedef {string[]} TValidatorDate
+ * @memberof DoboModel
  * @property {string} 0=greater
  * @property {string} 1=iso
  * @property {string} 2=less
- * @property {string} 2=max
- * @property {string} 2=min
+ * @property {string} 3=max
+ * @property {string} 4=min
  */
 
 /**
+ * List of available timestamp validators to check against model's properties and rules
  * @typedef {string[]} TValidatorTimestamp
+ * @memberof DoboModel
  * @property {string} 0=timestamp
  */
 
 /**
+ * All available validators to check against model's properties and rules
  * @typedef {Object} TValidator
+ * @memberof DoboModel
  * @property {TValidatorString} string
  * @property {TValidatorNumber} number
  * @property {TValidatorBoolean} boolean
  * @property {TValidatorDate} date
  * @property {TValidatorTimestamp} timestamp
+ * @property {TValidatorArray} array
+ */
+
+/**
+ * List of available array validators to check against model's properties and rules
+ * @typedef {string[]} TValidatorArray
+ * @memberof DoboModel
+ * @property {string} 0=length
+ * @property {string} 1=max
+ * @property {string} 2=min
  */
 const validator = {
   string: ['alphanum', 'base64', 'case', 'creditCard', 'dataUri', 'domain', 'email', 'guid',
@@ -90,9 +112,21 @@ const validator = {
   array: ['length', 'max', 'min']
 }
 
-async function buildFromDbModel (opts = {}) {
+/**
+ * Build JOI model from database model's properties and rules
+ * @method
+ * @memberof DoboModel
+ * @async
+ * @param {object} [options={}] - Options object
+ * @param {Array} [options.fields=[]] - If not empty, only these fields will be included in the JOI model
+ * @param {object} [options.rule={}] - Custom rules to override model's rules
+ * @param {Array} [options.extFields=[]] - Additional fields to include in the JOI model
+ * @param {boolean} [options.partial=false] - If `true`, only the fields present in the body will be validated
+ * @returns {object|boolean} Returns JOI model object or `false` if no properties to validate
+ */
+async function buildFromDbModel (options = {}) {
   const { isPlainObject, get, isEmpty, isString, keys, find, has, without } = this.app.lib._
-  const { fields = [], rule = {}, extFields = [] } = opts
+  const { fields = [], rule = {}, extFields = [] } = options
   const obj = {}
   const { propertyType: propType } = this.app.baseClass.Dobo
   const refs = []
@@ -137,7 +171,7 @@ async function buildFromDbModel (opts = {}) {
     }
     if (!['id'].includes(prop.name) && prop.required) obj = obj.required()
     if (prop.values) {
-      const values = await me.buildPropValues(prop, opts)
+      const values = await me.buildPropValues(prop, options)
       const items = values.map(item => item.value)
       if (prop.type === 'array') {
         obj = obj.items(joi.string().valid(...items))
@@ -156,7 +190,7 @@ async function buildFromDbModel (opts = {}) {
   const props = [...this.properties, ...extFields]
   for (const p of props) {
     if (excludedTypes.includes(p.type) || excludedNames.includes(p.name)) continue
-    if (opts.partial && fields.length > 0 && !fields.includes(p.name)) continue
+    if (options.partial && fields.length > 0 && !fields.includes(p.name)) continue
     let item
     switch (p.type) {
       case 'text':
@@ -213,28 +247,27 @@ async function buildFromDbModel (opts = {}) {
 }
 
 /**
- * Validate value against JOI model
+ * Validate body object against JOI model
  *
  * @method
- * @memberof Dobo
+ * @memberof DoboModel
  * @async
- * @param {Object} value - value to validate
+ * @param {Object} body - Body object to validate
  * @param {Object} joiModel - JOI model
  * @param {Object} [options={}] - Options object
- * @param {string} [options.ns=dobo] - Scope's namespace
- * @param {Array} [options.fields=[]]
  * @param {Array} [options.extFields=[]]
+ * @param {boolean} [options.partial=false] - If `true`, only the fields present in the body will be validated
  * @param {Object} [options.params={}] - Validation parameters. See {@tutorial config} and {@link https://joi.dev/api/?v=17.13.3#anyvalidateasyncvalue-options|JOI validate's options}
  * @returns {Object}
  */
-async function validate (body, joiModel, opts = {}) {
+async function validate (body, joiModel, options = {}) {
   const { defaultsDeep } = this.app.lib.aneka
   const { isEmpty } = this.app.lib._
-  let { extFields = [], params = {}, partial } = opts
+  let { extFields = [], params = {}, partial } = options
   params = defaultsDeep(params, this.app.dobo.config.validationParams)
   const { rule = {} } = params
   delete params.rule
-  const fields = partial ? Object.keys(body) : [...opts.fields]
+  const fields = partial ? Object.keys(body) : [...options.fields]
   if (isEmpty(joiModel)) joiModel = await buildFromDbModel.call(this, { fields, rule, extFields, partial })
   if (!joiModel) return { value: body }
   try {

package/lib/factory/model.js

@@ -1,4 +1,4 @@
-import { sanitizeAll, sanitizeRef } from '../collect-models.js'
+import { sanitizeAll, sanitizeRef } from '../helper.js'
 import clearRecord from './model/clear-record.js'
 import countRecord from './model/count-record.js'
 import createRecord from './model/create-record.js'
@@ -21,7 +21,6 @@ import removeAttachment from './model/remove-attachment.js'
 import findAttachment from './model/find-attachment.js'
 import sanitizeBody from './model/sanitize-body.js'
 import sanitizeRecord from './model/sanitize-record.js'
-import sanitizeId from './model/sanitize-id.js'
 import sanitizeFixture from './model/sanitize-fixture.js'
 import upsertRecord from './model/upsert-record.js'
 import bulkCreateRecord from './model/bulk-create-record.js'
@@ -30,51 +29,287 @@ import transaction from './model/transaction.js'
 import validate from './model/validate.js'
 
 /**
- * @typedef {string} TRecordSortKey
+ * @typedef {Object} TOptions
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {boolean} [noHook=false] - If `true`, no model's hook will be executed
+ * @property {boolean} [noModelHook=false] - If `true`, no model's hook will be executed
+ * @property {boolean} [noDynHook=false] - If `true`, no dynamic hook will be executed
+ * @property {boolean} [noValidation=false] - If `true`, no validation of data payload performed
+ * @property {boolean} [noCheckUnique=false] - If `true`, no unique validation for ID performed
+ * @property {boolean} [noBodySanitizer=false] - If `true`, accept data payload as is without sanitization
+ * @property {boolean} [noRecordSanitizer=false] - If `true`, accept result payload as is without sanitization
+ * @property {boolean} [noResult=false] - If `true`, returns nothing
+ * @property {boolean} [truncateString=true] - If `true` (default), string is truncated to its model's `maxLength`
+ * @property {boolean} [partial] - If `true`, only updated values are saved. Otherwise replace all existing values with given payload. Defaults to `true` for `updateRecord`
+ * @property {boolean} [dataOnly=true] - If `true` (default) returns only record's object. Otherwise {@link DoboModel.TResult}
  */
 
 /**
- * Key value pairs used as sort information:
- * - Key represent model's field name
- * - value represent its sort order: ```1``` for ascending order, and ```-1``` for descending order
+ * Sort order key used in pagination and sorting of records. It can be either:
+ * - `1` for ascending order (the default, if none is provided) or
+ * - `-1` for descending order.
+ * @typedef {string} TSortOrder
+ * @memberof DoboModel
+ */
+
+/**
+ * Key value pairs used as sort order in pagination and sorting of records. It is an object where:
+ * - Key represents model's field name
+ * - Value represents its sort order
  *
- * Example: to sort by firstName (ascending) and lastName (descending)
- * ```javascript
+ * @typedef {Object.<string, DoboModel.TSortOrder>} TSort
+ * @memberof DoboModel
+ * @example
+ * // to sort by firstName (ascending) and lastName (descending)
  * const sort = {
  *   firstName: 1,
  *   lastName: -1
  * }
- * ```
- *
- * @typedef {Object.<string, TRecordSortKey>} TRecordSort
  */
 
 /**
- * @typedef {Object} TRecordPagination
+ * @typedef {Object} TPagination
+ * @memberof DoboModel
  * @property {number} limit - Number of records per page
  * @property {number} page - Page number
- * @property {number} skip - Records to skip
- * @property {TRecordSort} sort - Sort order
+ * @property {number} [skip] - Records to skip. If not provided, it will be calculated based on `limit` and `page`
  */
 
+/**
+ * Property value type definition. Used for building property `values` in a model which is an array of this object type.
+ * @typedef TPropertyValue
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {string} value - The actual value of the property
+ * @property {string} text - The display text for the property value, which can be translated based on the request context
+ */
+
+/**
+ * Formatted version of a record's property values. It is an object where:
+ * - Key represents the property name
+ * - Value represents its formatted value according to the property's data type or formatting function. Data type is ALWAYS in string.
+ *
+ * This record is then wrapped in a `_fmt` property.
+ * @typedef TRecordFormatted
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {Object} [_fmt={}] - Wrapper
+ * @example
+ * {
+ *   _fmt: {
+ *     id: "1",
+ *     item: "Laptop",
+ *     createdAt: "Jan 1, 2024, 12:00 AM",
+ *     isActive: "True",
+ *     price: "2,500.00"
+ *   }
+ * }
+ */
+
+/**
+ * Reference record related to a record's result. It is an object where:
+ * - Key represents the name of the referenced record. Normally, it is the referenced model's name in camelCase format.
+ * - Value represents its reference record. It can be an object or an array of objects, depending on the relationship type.
+ *
+ * This record is then wrapped in a `_ref` property in the result object.
+ * @typedef TRecordRef
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {Object} [_ref={}] - Wrapper
+ * @property {Object|Array} [_ref.<string>.<DoboModel.TRecord>] - Reference record
+ * @example
+ * {
+ *   _ref: {
+ *     user: {
+ *       id: 1,
+ *       name: "John Doe"
+ *     },
+ *     posts: [
+ *       {
+ *         id: 1,
+ *         title: "Post Title"
+ *       },
+ *       {
+ *         id: 2,
+ *         title: "Another Post Title"
+ *       }
+ *     ]
+ *   }
+ * }
+ */
+
+/**
+ * The record returned from a model's action. It is an object where:
+ * - Key represents the property name
+ * - Value represents its value according to the property's data type
+ *
+ * This record is then merged with {@link DoboModel.TRecordFormatted} and {@link DoboModel.TRecordRef} to form the final record returned from a model's action.
+ * @typedef TRecord
+ * @memberof DoboModel
+ * @type {Object & DoboModel.TRecordFormatted & DoboModel.TRecordRef}
+ * @example
+ * {
+ *   id: 1,
+ *   item: "Laptop",
+ *   createdAt: "2024-01-01T00:00:00.000Z",
+ *   isActive: true,
+ *   price: 2500.00,
+ *   _fmt: {
+ *     id: "1",
+ *     item: "Laptop",
+ *     createdAt: "Jan 1, 2024, 12:00 AM",
+ *     isActive: "True",
+ *     price: "2,500.00"
+ *   },
+ *   _ref: {
+ *     user: {
+ *       id: 1,
+ *       name: "John Doe"
+ *     }
+ *   }
+ * }
+ */
+
+/**
+ * The result returned from a model's action other than `find*`, `{create|update|remove}Record` if `dataOnly` is set to `false`.
+ * @typedef TResultRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {Array<DoboModel.TRecord>} data - The data returned from the action
+ */
+
+/**
+ * The result returned from a model's `find*` actions if `dataOnly` is set to `false`.
+ * @typedef TResultFindRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {Array<DoboModel.TRecord>} data - The data returned from the action
+ * @property {number} [count] - The total number of records found, if applicable
+ * @property {boolean} [cached] - Indicates if the result was retrieved from cache, if applicable. Only available if `bajoCache` is used
+ * @property {Array} [warnings] - Any warnings generated during the action, if applicable
+ */
+
+/**
+ * The result returned from a model's `getRecord` action if `dataOnly` is set to `false`.
+ * @typedef TResultGetRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {DoboModel.TRecord} data - The data returned from the action
+ */
+
+/**
+ * The result returned from a model's `createRecord` action if `dataOnly` is set to `false`.
+ * @typedef TResultCreateRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {DoboModel.TRecord} data - The data returned from the action
+ */
+
+/**
+ * The result returned from a model's `updateRecord` action if `dataOnly` is set to `false`.
+ * @typedef TResultUpdateRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {DoboModel.TRecord} data - The updated data returned from the action
+ * @property {DoboModel.TRecord} oldData - The previous data before the update
+ */
+
+/**
+ * The result returned from a model's `removeRecord` action if `dataOnly` is set to `false`.
+ * @typedef TResultRemoveRecord
+ * @memberof DoboModel
+ * @type {Object}
+ * @property {DoboModel.TRecord} oldData - The removed data returned from the action
+ */
+
+/**
+ * Model factory.
+ *
+ * @async
+ * @returns {Promise<void>} Returns nothing
+ */
 async function modelFactory () {
   const { Tools } = this.app.baseClass
   const { defaults } = this.app.lib._
 
   /**
-   * Feature class
-   *
-   * ```this.plugin``` should be the one who owned this driver
+   * Model class defintion.
    *
    * @class
    */
   class DoboModel extends Tools {
+    /**
+     * Constructor
+     */
     constructor (plugin, options) {
       super(plugin)
+
       defaults(this, options)
-      this.driver = this.connection.driver
+
+      /**
+       * Model's adapter name
+       * @type {string}
+       */
+      this.adapter = this.connection.adapter
+
+      this.bindThis(
+        build,
+        exists,
+        drop,
+
+        createRecord,
+        getRecord,
+        updateRecord,
+        upsertRecord,
+        removeRecord,
+        clearRecord,
+        findRecord,
+        findOneRecord,
+        findAllRecord,
+
+        transaction,
+        bulkCreateRecord,
+
+        createAggregate,
+        createHistogram,
+        countRecord,
+
+        createAttachment,
+        getAttachment,
+        updateAttachment,
+        removeAttachment,
+        findAttachment,
+        listAttachment,
+
+        loadFixtures,
+        sanitizeRecord,
+        sanitizeBody,
+        sanitizeFixture,
+        validate
+      )
+
+      // aliases
+      this.deleteRecord = this.removeRecord
+      this.clearRecords = this.clearRecord
+      this.countRecords = this.countRecord
+      this.findRecords = this.findRecord
+      this.findAllRecords = this.findAllRecord
+      this.listAttachments = this.listAttachment
+      this.bulkCreateRecords = this.bulkCreateRecord
+
+      this.getField = this.getProperty
+      this.hasField = this.hasProperty
     }
 
+    /**
+     * Invoke a model's action. It will create a new instance of {@link DoboAction} and return it.
+     * @method
+     * @memberof DoboModel
+     * @param {string} name - The name of the action to invoke
+     * @param  {...any} args - Arguments to pass to the action
+     * @returns {DoboAction} Returns an instance of {@link DoboAction}
+     */
     action = (name, ...args) => {
       const action = new this.app.baseClass.DoboAction(this, name, ...args)
       return action
@@ -84,47 +319,123 @@ async function modelFactory () {
       await sanitizeAll.call(this.app.dobo, obj)
     }
 
+    /**
+     * Sanitize a reference object based on the model's properties and rules.
+     * @method
+     * @memberof DoboModel
+     * @async
+     * @param {*} obj - The reference object to sanitize
+     * @param {boolean} [fatal=true] - Whether to throw an error if sanitization fails
+     */
     sanitizeRef = async (obj, fatal = true) => {
       await sanitizeRef.call(this.app.dobo, obj, this.app.dobo.models, fatal)
     }
 
+    /**
+     * Sanitize the given ID based on the model's properties.
+     * @method
+     * @memberof DoboModel
+     * @param {string|number} id - The ID to sanitize
+     * @returns {string|number} Returns the sanitized ID
+     */
+    sanitizeId = (id) => {
+      const prop = this.properties.find(p => p.name === 'id')
+      if (prop.type === 'integer') id = parseInt(id)
+      return id
+    }
+
+    /**
+     * Get a property by its name.
+     * @method
+     * @memberof DoboModel
+     * @param {string} name - The name of the property to retrieve
+     * @returns {Object|null} Returns the property object if found, otherwise `undefined`
+     */
     getProperty = (name) => {
       return this.properties.find(prop => prop.name === name)
     }
 
-    getProperties = ({ noVirtual, namesOnly } = {}) => {
+    /**
+     * Get the model's properties based on the given options.
+     * @method
+     * @memberof DoboModel
+     * @param {Object} [options={}] - Options object
+     * @param {boolean} [options.noVirtual=false] - If `true`, exclude virtual properties
+     * @param {boolean} [options.namesOnly=false] - If `true`, return only property names instead of full property objects
+     * @returns {Array<object|string>} Returns an array of properties or property names based on the options
+     */
+    getProperties = (options = {}) => {
+      const { noVirtual, namesOnly } = options
       const items = noVirtual ? this.properties.filter(prop => !prop.virtual) : this.properties
       return namesOnly ? items.map(item => item.name) : items
     }
 
+    /**
+     * Get the model's virtual properties.
+     * @method
+     * @memberof DoboModel
+     * @param {boolean} [namesOnly=false] - If `true`, return only property names instead of full property objects
+     * @returns {Array<object|string>} Returns an array of virtual properties or property names based on the `namesOnly` option
+     */
     getVirtualProperties = (namesOnly) => {
       const items = this.properties.filter(prop => prop.virtual)
       return namesOnly ? items.map(item => item.name) : items
     }
 
+    /**
+     * Get the model's non-virtual properties.
+     * @method
+     * @memberof DoboModel
+     * @param {boolean} [namesOnly=false] - If `true`, return only property names instead of full property objects
+     * @returns {Array<object|string>} Returns an array of non-virtual properties or property names based on the `namesOnly` option
+     */
     getNonVirtualProperties = (namesOnly) => {
       const items = this.properties.filter(prop => !prop.virtual)
       return namesOnly ? items.map(item => item.name) : items
     }
 
+    /**
+     * Returns the model's indexes.
+     * @method
+     * @memberof DoboModel
+     * @returns {Array<object>} Returns an array of index objects defined in the model
+     */
     getIndexes = () => {
       return this.indexes
     }
 
+    /**
+     * Checks if the model has a property with the given name.
+     * @method
+     * @memberof DoboModel
+     * @param {string} name - The name of the property to check
+     * @returns {boolean} Returns `true` if the property exists, otherwise `false`
+     */
     hasProperty = (name) => {
       return !!this.getProperty(name)
     }
 
     syncIdField = (idField) => {
       const { cloneDeep, findIndex } = this.app.lib._
-      if (!this.driver) return
-      if (!idField) idField = cloneDeep(this.driver.idField)
+      if (!this.adapter) return
+      if (!idField) idField = cloneDeep(this.adapter.idField)
       const idx = findIndex(this.properties, { name: 'id' })
       if (idx === -1) return
       this.properties.splice(idx, 1)
       this.properties.unshift(idField)
     }
 
+    /**
+     * Internal method to perform a simple lookup based on the provided value and lookupValue.
+     * @method
+     * @internal
+     * @memberof DoboModel
+     * @async
+     * @param {string|object|Array} value - The value to look up
+     * @param {object} lookupValue - The lookup values to replace in the query
+     * @param {object} [options={}] - Additional options for the lookup
+     * @returns {*|null|undefined} Returns the result of the lookup or `null` if not found or `undefined` if the value is not a string, object, or array
+     */
     _simpleLookup = async (value, lookupValue, options = {}) => {
       const { get, isEmpty, isString, isPlainObject, isArray } = this.app.lib._
       let model
@@ -148,6 +459,22 @@ async function modelFactory () {
       return get(rec, field, null)
     }
 
+    /**
+     * Builds the values for a given property if `prop.values` is set:
+     * - If a string, it will be treated as a handler and executed to get the values.
+     * - If a function, it will be executed to get the values.
+     * - If an array, it will be used as is.
+     *
+     * Values are returned as an array of {@link DoboModel.TPropertyValues}.
+     * If a request object is provided in the options, the `text` will be translated using
+     * the request's translation function.
+     * @async
+     * @method
+     * @memberof DoboModel
+     * @param {object} prop - The property definition
+     * @param {DoboModel.TOptions} opts - Additional options for building the property values
+     * @returns {Array<DoboModel.TPropertyValue>} Returns an array of property values
+     */
     buildPropValues = async (prop, opts) => {
       const { isString, camelCase, isFunction } = this.app.lib._
       const { callHandler } = this.app.bajo
@@ -162,57 +489,10 @@ async function modelFactory () {
       })
     }
 
-    build = build
-    exists = exists
-    drop = drop
-
-    createRecord = createRecord
-    getRecord = getRecord
-    updateRecord = updateRecord
-    upsertRecord = upsertRecord
-    removeRecord = removeRecord
-    clearRecord = clearRecord
-    findRecord = findRecord
-    findOneRecord = findOneRecord
-    findAllRecord = findAllRecord
-
-    transaction = transaction
-    bulkCreateRecord = bulkCreateRecord
-
-    createAggregate = createAggregate
-    createHistogram = createHistogram
-    countRecord = countRecord
-
-    createAttachment = createAttachment
-    getAttachment = getAttachment
-    updateAttachment = updateAttachment
-    removeAttachment = removeAttachment
-    findAttachment = findAttachment
-    listAttachment = listAttachment
-
-    loadFixtures = loadFixtures
-    sanitizeRecord = sanitizeRecord
-    sanitizeBody = sanitizeBody
-    sanitizeId = sanitizeId
-    sanitizeFixture = sanitizeFixture
-    validate = validate
-
-    // aliases
-    deleteRecord = removeRecord
-    clearRecords = clearRecord
-    countRecords = countRecord
-    findRecords = findRecord
-    findAllRecords = findAllRecord
-    listAttachments = listAttachment
-    bulkCreateRecords = bulkCreateRecord
-
-    getField = (name) => this.getProperty(name)
-    hasField = (name) => this.hasProperty(name)
-
     dispose = async () => {
       await super.dispose()
       this.connection = null
-      this.driver = null
+      this.adapter = null
     }
   }