dobo 2.0.0 → 2.2.0

package/lib/factory/model/update-record.js

@@ -0,0 +1,81 @@
+import { getFilterAndOptions, execHook, execValidation, execModelHook, getSingleRef, handleReq } from './_util.js'
+import { onlyTypes } from './create-record.js'
+const action = 'updateRecord'
+
+/**
+ * @typedef {Object} TRecordUpdateOptions
+ * @see Model#updateRecord
+ * @property {boolean} [dataOnly=true] - If ```true``` (default) returns record's object. Otherwise {@link TRecordUpdateResult}
+ * @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} [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=true] - If ```true``` (default), only updated values are saved. Otherwise replace all existing values with given payload
+ * @property {boolean} [fields=[]] - If not empty, return only these fields EXCLUDING hidden fields
+ * @property {boolean} [hidden=[]] - Additional fields to hide, in addition the one set in model's model
+ * @property {boolean} [forceNoHidden=false] - If ```true```, hidden fields will be ignored and ALL fields will be returned
+ */
+
+/**
+ * Update a record by it's ID and body payload
+ *
+ * Example:
+ * ```javascript
+ * const { recordUpdate } = this.app.dobo
+ * const { body } = {
+ *   name: 'Republic of Indonesia',
+ *   phoneCode: '+62'
+ * }
+ * const result = await recordUpdate('CdbCountry', 'ID', body)
+ * ```
+ *
+ * @method
+ * @memberof Dobo
+ * @async
+ * @instance
+ * @name recordUpdate
+ * @param {string} name - Model's name
+ * @param {(string|number)} id - Record's ID
+ * @param {Object} body - Body payload
+ * @param {TRecordUpdateOptions} [options={}]
+ * @returns {(TRecordUpdateResult|Object)} Returns updated record if ```options.dataOnly``` is set. {@link TRecordUpdateResult} otherwise
+ */
+async function updateRecord (...args) {
+  if (args.length === 0) return this.action(action, ...args)
+  let [id, body = {}, opts = {}] = args
+  const { isSet } = this.app.lib.aneka
+  const { runHook } = this.app.bajo
+  const { cloneDeep, get } = this.app.lib._
+  const { dataOnly = true } = opts
+  const { options } = await getFilterAndOptions.call(this, null, opts, action)
+  options.partial = options.partial ?? true
+  const { truncateString, noResult, noBodySanitizer, noResultSanitizer, noValidation, partial } = options
+  const extFields = get(options, 'validation.extFields', [])
+  id = this.sanitizeId(id)
+  const input = noBodySanitizer ? cloneDeep(body) : await this.sanitizeBody({ body, extFields, strict: true, truncateString, partial, onlyTypes })
+  delete input.id
+  await execHook.call(this, 'beforeUpdateRecord', id, input, options)
+  await execModelHook.call(this, 'beforeUpdateRecord', id, input, options)
+  if (!noValidation) await execValidation.call(this, input, options)
+  const result = options.record ?? (await this.driver._updateRecord(this, id, input, options)) ?? {}
+  if (noResult) {
+    await runHook('cache:clear', this, 'update', id, body)
+    return
+  }
+  if (!noResultSanitizer) {
+    result.data = await this.sanitizeRecord(result.data, options)
+    result.oldData = await this.sanitizeRecord(result.oldData, options)
+  }
+  if (isSet(options.refs)) await getSingleRef.call(this, { record: result.data, options })
+  await handleReq.call(this, result.data.id, 'updated', options)
+  await execModelHook.call(this, 'afterUpdateRecord', id, input, result, options)
+  await execHook.call(this, 'afterUpdateRecord', id, input, result, options)
+  await runHook('cache:clear', this, 'update', id, body, result)
+  return dataOnly ? result.data : result
+}
+
+export default updateRecord

package/lib/factory/model/upsert-record.js

@@ -0,0 +1,95 @@
+import { getFilterAndOptions, execHook, execModelHook, execValidation, getSingleRef, handleReq } from './_util.js'
+const action = 'upsertRecord'
+
+async function native (body = {}, opts = {}) {
+  const { isSet } = this.app.lib.aneka
+  const { runHook } = this.app.bajo
+  const { cloneDeep, get } = this.app.lib._
+  const { dataOnly = true } = opts
+  const { options } = await getFilterAndOptions.call(this, null, opts, action)
+  const { truncateString, noResult, noBodySanitizer, noResultSanitizer, noValidation } = options
+  const extFields = get(options, 'validation.extFields', [])
+  let input = noBodySanitizer ? cloneDeep(body) : await this.sanitizeBody({ body, extFields, strict: true, truncateString })
+  if (!noValidation) input = await execValidation.call(this, input, options)
+  await execHook.call(this, 'beforeUpsertRecord', input, options)
+  await execModelHook.call(this, 'beforeUpsertRecord', input, options)
+  const result = options.record ?? (await this.driver._upsertRecord(this, input, options)) ?? {}
+  if (noResult) {
+    await runHook('cache:clear', this, 'upsert', body)
+    return
+  }
+  if (!noResultSanitizer) result.data = await this.sanitizeRecord(result.data, options)
+  if (isSet(options.refs)) await getSingleRef.call(this, { record: result.data, options })
+  await handleReq.call(this, result.data.id, 'upserted', options)
+  await execModelHook.call(this, 'afterUpsertRecord', input, result, options)
+  await execHook.call(this, 'afterUpsertRecord', input, result, options)
+  await runHook('cache:clear', this, 'upsert', body, result)
+  return dataOnly ? result.data : result
+}
+
+async function manual (body = {}, options = {}) {
+  const { isSet } = this.app.lib.aneka
+  if (isSet(body.id)) body.id = this.sanitizeId(body.id)
+  let old = false
+  if (isSet(body.id)) {
+    try {
+      old = await this.driver._getRecord(this, body.id, { noHook: true, noModelHook: true })
+    } catch (err) {}
+  }
+  if (old) return await this.updateRecord(old.data.id, body, options)
+  return await this.createRecord(body, options)
+}
+
+/**
+ * @typedef {Object} TRecordUpdateOptions
+ * @see Model#updateRecord
+ * @property {boolean} [dataOnly=true] - If ```true``` (default) returns record's object. Otherwise {@link TRecordUpdateResult}
+ * @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} [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=true] - If ```true``` (default), only updated values are saved. Otherwise replace all existing values with given payload
+ * @property {boolean} [fields=[]] - If not empty, return only these fields EXCLUDING hidden fields
+ * @property {boolean} [hidden=[]] - Additional fields to hide, in addition the one set in model's model
+ * @property {boolean} [forceNoHidden=false] - If ```true```, hidden fields will be ignored and ALL fields will be returned
+ */
+
+/**
+ * Update a record by it's ID and body payload
+ *
+ * Example:
+ * ```javascript
+ * const { recordUpdate } = this.app.dobo
+ * const { body } = {
+ *   name: 'Republic of Indonesia',
+ *   phoneCode: '+62'
+ * }
+ * const result = await recordUpdate('CdbCountry', 'ID', body)
+ * ```
+ *
+ * @method
+ * @memberof Dobo
+ * @async
+ * @instance
+ * @name recordUpdate
+ * @param {string} name - Model's name
+ * @param {(string|number)} id - Record's ID
+ * @param {Object} body - Body payload
+ * @param {TRecordUpdateOptions} [options={}]
+ * @returns {(TRecordUpdateResult|Object)} Returns updated record if ```options.dataOnly``` is set. {@link TRecordUpdateResult} otherwise
+ */
+async function upsertRecord (...args) {
+  if (args.length === 0) return this.action(action, ...args)
+  const [body = {}, opts = {}] = args
+  if (this.driver.upsertRecord) {
+    const { options } = await getFilterAndOptions.call(this, null, opts, action)
+    return await native.call(this, body, options)
+  }
+  return await manual.call(this, body, opts)
+}
+
+export default upsertRecord

package/lib/factory/model/validate.js

@@ -0,0 +1,232 @@
+import joi from 'joi'
+
+const excludedTypes = ['object', 'array']
+const excludedNames = []
+
+/**
+ * @typedef {string[]} TValidatorString
+ * @property {string} 0=alphanum
+ * @property {string} 1=base64
+ * @property {string} 2=case
+ * @property {string} 3=creditCard
+ * @property {string} 4=dataUri
+ * @property {string} 5=email
+ * @property {string} 6=guid
+ * @property {string} 7=uuid
+ * @property {string} 8=hex
+ * @property {string} 9=hostname
+ * @property {string} 10=insenstive
+ * @property {string} 11=ip
+ * @property {string} 12=isoDate
+ * @property {string} 13=isoDuration
+ * @property {string} 14=length
+ * @property {string} 15=lowercase
+ * @property {string} 16=max
+ * @property {string} 17=min
+ * @property {string} 18=normalize
+ * @property {string} 19=pattern
+ * @property {string} 20=regex
+ * @property {string} 21=replace
+ * @property {string} 22=token
+ * @property {string} 23=trim
+ * @property {string} 24=truncate
+ * @property {string} 25=upercase
+ * @property {string} 26=uri
+ */
+
+/**
+ * @typedef {string[]} TValidatorNumber
+ * @property {string} 0=great
+ * @property {string} 1=less
+ * @property {string} 2=max
+ * @property {string} 3=min
+ * @property {string} 4=multiple
+ * @property {string} 5=negative
+ * @property {string} 6=port
+ * @property {string} 7=positive
+ * @property {string} 8=sign
+ * @property {string} 9=unsafe
+ */
+
+/**
+ * @typedef {string[]} TValidatorBoolean
+ * @property {string} 0=falsy
+ * @property {string} 1=sensitive
+ * @property {string} 2=truthy
+ */
+
+/**
+ * @typedef {string[]} TValidatorDate
+ * @property {string} 0=greater
+ * @property {string} 1=iso
+ * @property {string} 2=less
+ * @property {string} 2=max
+ * @property {string} 2=min
+ */
+
+/**
+ * @typedef {string[]} TValidatorTimestamp
+ * @property {string} 0=timestamp
+ */
+
+/**
+ * @typedef {Object} TValidator
+ * @property {TValidatorString} string
+ * @property {TValidatorNumber} number
+ * @property {TValidatorBoolean} boolean
+ * @property {TValidatorDate} date
+ * @property {TValidatorTimestamp} timestamp
+ */
+const validator = {
+  string: ['alphanum', 'base64', 'case', 'creditCard', 'dataUri', 'domain', 'email', 'guid',
+    'uuid', 'hex', 'hostname', 'insensitive', 'ip', 'isoDate', 'isoDuration', 'length', 'lowercase',
+    'max', 'min', 'normalize', 'pattern', 'regex', 'replace', 'token', 'trim', 'truncate',
+    'uppercase', 'uri'],
+  number: ['great', 'less', 'max', 'min', 'multiple', 'negative', 'port', 'positive',
+    'sign', 'unsafe'],
+  boolean: ['falsy', 'sensitive', 'truthy'],
+  date: ['greater', 'iso', 'less', 'max', 'min'],
+  timestamp: ['timestamp']
+}
+
+function buildFromDbModel (opts = {}) {
+  const { isPlainObject, get, isEmpty, isString, keys, find, has, without } = this.app.lib._
+  const { fields = [], rule = {}, extFields = [] } = opts
+  const obj = {}
+  const { propertyType: propType } = this.app.baseClass.Dobo
+  const refs = []
+
+  function getRuleKv (kvRule) {
+    let key
+    let value
+    let columns
+    if (isPlainObject(kvRule)) {
+      key = kvRule.rule
+      value = kvRule.params
+      columns = kvRule.fields
+    } else if (isString(kvRule)) {
+      [key, value, columns] = kvRule.split(':')
+    }
+    return { key, value, columns }
+  }
+
+  function applyFieldRules (prop, obj) {
+    const minMax = { min: false, max: false }
+    const rules = get(rule, prop.name, prop.rules ?? [])
+    if (!Array.isArray(rules)) return rules
+    for (const r of rules) {
+      const types = validator[propType[prop.type].validator]
+      const { key, value } = getRuleKv(r)
+      if (keys(minMax).includes(key)) minMax[key] = true
+      if (key === 'ref') {
+        refs.push(prop.name)
+        obj = joi.ref(value)
+        continue
+      }
+      if (!key || !types.includes(key)) continue
+      obj = obj[key](value)
+    }
+    if (refs.includes(prop.name)) return obj
+    if (['string', 'text'].includes(prop.type)) {
+      for (const k in minMax) {
+        if (minMax[k]) continue
+        if (has(prop, `${k}Length`)) obj = obj[k](prop[`${k}Length`])
+      }
+    }
+    if (Array.isArray(prop.values)) obj = obj.valid(...prop.values)
+    if (!['id'].includes(prop.name) && prop.required) obj = obj.required()
+    return obj
+  }
+
+  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
+    let item
+    switch (p.type) {
+      case 'text':
+      case 'string': {
+        item = applyFieldRules(p, joi.string())
+        break
+      }
+      case 'smallint':
+      case 'integer':
+        item = applyFieldRules(p, joi.number().integer())
+        break
+      case 'float':
+      case 'double':
+        if (p.precision) item = applyFieldRules(p, joi.number().precision(p.precision))
+        else item = applyFieldRules(p, joi.number())
+        break
+      case 'time':
+      case 'date':
+      case 'datetime':
+        item = applyFieldRules(p, joi.date())
+        break
+      case 'timestamp':
+        item = applyFieldRules(p, joi.number().integer())
+        break
+      case 'boolean':
+        item = applyFieldRules(p, joi.boolean())
+        break
+    }
+    if (item) {
+      if (item.$_root && !p.required) obj[p.name] = item.allow(null, '')
+      else obj[p.name] = item
+    }
+  }
+  if (isEmpty(obj)) return false
+  for (const r of this.rules) {
+    for (const k of without(keys(obj), ...refs)) {
+      const prop = find(props, { name: k })
+      if (!prop) continue
+      const types = validator[propType[prop.type].validator]
+      const { key, value, columns = [] } = getRuleKv(r)
+      if (!types.includes(key)) continue
+      if (columns.length === 0 || columns.includes(k)) obj[k] = obj[k][key](value)
+    }
+  }
+  const result = joi.object(obj)
+  for (const k of ['with', 'xor', 'without']) {
+    const item = get(this, `extRule.${k}`)
+    if (item) result[k](...item)
+  }
+  return result
+}
+
+/**
+ * Validate value against JOI model
+ *
+ * @method
+ * @memberof Dobo
+ * @async
+ * @param {Object} value - value 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 {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 = {}) {
+  const { defaultsDeep } = this.app.lib.aneka
+  const { isEmpty } = this.app.lib._
+  let { fields, extFields = [], params = {}, partial } = opts
+
+  params = defaultsDeep(params, this.app.dobo.config.validationParams)
+  const { rule = {} } = params
+  delete params.rule
+  if (isEmpty(joiModel)) joiModel = buildFromDbModel.call(this, { fields, rule, extFields, partial })
+  if (!joiModel) return { value: body }
+  try {
+    return await joiModel.validateAsync(body, params)
+  } catch (err) {
+    const payload = { details: err.details, statusCode: 422, code: 'DB_VALIDATION' }
+    if (err.values) payload.values = err.values
+    throw this.plugin.error('validationError', payload)
+  }
+}
+
+export default validate

package/lib/factory/model.js

@@ -0,0 +1,150 @@
+import { sanitizeAll, sanitizeRef } from '../collect-models.js'
+import clearRecord from './model/clear-record.js'
+import countRecord from './model/count-record.js'
+import createRecord from './model/create-record.js'
+import drop from './model/drop.js'
+import findAllRecord from './model/find-all-record.js'
+import findOneRecord from './model/find-one-record.js'
+import findRecord from './model/find-record.js'
+import getRecord from './model/get-record.js'
+import createHistogram from './model/create-histogram.js'
+import createAggregate from './model/create-aggregate.js'
+import exists from './model/exists.js'
+import build from './model/build.js'
+import loadFixtures from './model/load-fixtures.js'
+import removeRecord from './model/remove-record.js'
+import updateRecord from './model/update-record.js'
+import createAttachment from './model/create-attachment.js'
+import updateAttachment from './model/update-attachment.js'
+import getAttachment from './model/get-attachment.js'
+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 upsertRecord from './model/upsert-record.js'
+import listAttachment from './model/list-attachment.js'
+import validate from './model/validate.js'
+
+/**
+ * @typedef {string} TRecordSortKey
+ */
+
+/**
+ * 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
+ *
+ * Example: to sort by firstName (ascending) and lastName (descending)
+ * ```javascript
+ * const sort = {
+ *   firstName: 1,
+ *   lastName: -1
+ * }
+ * ```
+ *
+ * @typedef {Object.<string, TRecordSortKey>} TRecordSort
+ */
+
+/**
+ * @typedef {Object} TRecordPagination
+ * @property {number} limit - Number of records per page
+ * @property {number} page - Page number
+ * @property {number} skip - Records to skip
+ * @property {TRecordSort} sort - Sort order
+ */
+
+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
+   *
+   * @class
+   */
+  class DoboModel extends Tools {
+    constructor (plugin, options) {
+      super(plugin)
+      defaults(this, options)
+      this.driver = this.connection.driver
+      this.cacheable = this.cacheable ?? this.driver.cacheable ?? true
+    }
+
+    action = (name, ...args) => {
+      const action = new this.app.baseClass.DoboAction(this, name, ...args)
+      return action
+    }
+
+    sanitizeObjectDef = async (obj) => {
+      await sanitizeAll.call(this.app.dobo, obj)
+    }
+
+    sanitizeRef = async (obj, fatal = true) => {
+      await sanitizeRef.call(this.app.dobo, obj, this.app.dobo.models, fatal)
+    }
+
+    getProperty = (name) => {
+      return this.properties.find(prop => prop.name === name)
+    }
+
+    hasProperty = (name) => {
+      return !!this.getProperty(name)
+    }
+
+    build = build
+    exists = exists
+    drop = drop
+
+    createRecord = createRecord
+    getRecord = getRecord
+    updateRecord = updateRecord
+    upsertRecord = upsertRecord
+    removeRecord = removeRecord
+    clearRecord = clearRecord
+    findRecord = findRecord
+    findOneRecord = findOneRecord
+    findAllRecord = findAllRecord
+
+    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
+    validate = validate
+
+    // aliases
+    deleteRecord = removeRecord
+    clearRecords = clearRecord
+    countRecords = countRecord
+    findRecords = findRecord
+    findAllRecords = findAllRecord
+    listAttachments = listAttachment
+
+    getField = (name) => this.getProperty(name)
+    hasField = (name) => this.hasProperty(name)
+
+    dispose () {
+      super.dispose()
+      this.connection = null
+      this.driver = null
+    }
+  }
+
+  this.app.baseClass.DoboModel = DoboModel
+  return DoboModel
+}
+
+export default modelFactory

package/lib/index.js

@@ -0,0 +1,3 @@
+/**
+ * @module Lib
+ */

package/package.json

@@ -1,36 +1,45 @@
-{
-  "name": "dobo",
-  "version": "2.0.0",
-  "description": "Database ORM/ODM for Bajo Framework",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "type": "module",
-  "bajo": {
-    "type": "plugin"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ardhi/dobo.git"
-  },
-  "keywords": [
-    "database",
-    "dobo",
-    "db",
-    "orm",
-    "bajo",
-    "framework"
-  ],
-  "author": "Ardhi Lukianto <ardhi@lukianto.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/ardhi/dobo/issues"
-  },
-  "homepage": "https://github.com/ardhi/dobo#readme",
-  "dependencies": {
-    "@tryghost/nql": "^0.12.7",
-    "joi": "^17.13.3",
-    "mingo": "^6.5.1"
-  }
-}
+{
+  "name": "dobo",
+  "version": "2.2.0",
+  "description": "DBMS for Bajo Framework",
+  "main": "index.js",
+  "scripts": {
+    "build-doc": "jsdoc -c .jsdoc.conf.json",
+    "test": "mocha"
+  },
+  "type": "module",
+  "bajo": {
+    "type": "plugin",
+    "alias": "db",
+    "bootorder": 50
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ardhi/dobo.git"
+  },
+  "keywords": [
+    "database",
+    "dobo",
+    "db",
+    "orm",
+    "bajo",
+    "framework"
+  ],
+  "author": "Ardhi Lukianto <ardhi@lukianto.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ardhi/dobo/issues"
+  },
+  "homepage": "https://github.com/ardhi/dobo#readme",
+  "dependencies": {
+    "@tryghost/nql": "^0.12.7",
+    "joi": "^18.0.2",
+    "mingo": "^7.1.0",
+    "ulid": "^3.0.2",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "clean-jsdoc-theme": "^4.3.0",
+    "jsdoc-plugin-intersection": "^1.0.4"
+  }
+}