dobo 1.2.10 → 2.0.1

package/index.js

@@ -1,22 +1,153 @@
 import collectConnections from './lib/collect-connections.js'
 import collectDrivers from './lib/collect-drivers.js'
-import collectFeature from './lib/collect-feature.js'
+import collectFeatures from './lib/collect-features.js'
 import collectSchemas from './lib/collect-schemas.js'
 import memDbStart from './lib/mem-db/start.js'
 import memDbInstantiate from './lib/mem-db/instantiate.js'
 import nql from '@tryghost/nql'
 import path from 'path'
 
+/**
+ * @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
+ */
+
+/**
+ * @typedef {Object} TPropType
+ * @property {Object} integer
+ * @property {string} [integer.validator=number]
+ * @property {Object} smallint
+ * @property {string} [smallint.validator=number]
+ * @property {Object} text
+ * @property {string} [text.validator=string]
+ * @property {string} [text.textType=string]
+ * @property {string[]} [text.values=['text', 'mediumtext', 'longtext']]
+ * @property {Object} string
+ * @property {string} [string.validator=string]
+ * @property {maxLength} [string.maxLength=255]
+ * @property {minLength} [string.minLength=0]
+ * @property {Object} float
+ * @property {string} [float.validator=number]
+ * @property {Object} double
+ * @property {string} [double.validator=number]
+ * @property {Object} boolean
+ * @property {string} [boolean.validator=boolean]
+ * @property {Object} datetime
+ * @property {string} [datetime.validator=date]
+ * @property {Object} date
+ * @property {string} [date.validator=date]
+ * @property {Object} time
+ * @property {string} [time.validator=date]
+ * @property {Object} timestamp
+ * @property {string} [timestamp.validator=timestamp]
+ * @property {Object} object={}
+ * @property {Object} array={}
+ */
+const propType = {
+  integer: {
+    validator: 'number'
+  },
+  smallint: {
+    validator: 'number'
+  },
+  text: {
+    validator: 'string',
+    textType: 'text',
+    values: ['text', 'mediumtext', 'longtext']
+  },
+  string: {
+    validator: 'string',
+    maxLength: 255,
+    minLength: 0
+  },
+  float: {
+    validator: 'number'
+  },
+  double: {
+    validator: 'number'
+  },
+  boolean: {
+    validator: 'boolean'
+  },
+  date: {
+    validator: 'date'
+  },
+  datetime: {
+    validator: 'date'
+  },
+  time: {
+    validator: 'date'
+  },
+  timestamp: {
+    validator: 'timestamp'
+  },
+  object: {},
+  array: {}
+}
+
+/**
+ * Plugin factory
+ *
+ * @param {string} pkgName - NPM package name
+ * @returns {class}
+ */
 async function factory (pkgName) {
   const me = this
 
-  return class Dobo extends this.lib.BajoPlugin {
+  /**
+   * Dobo Database Framework for {@link https://github.com/ardhi/bajo|Bajo}.
+   *
+   * See {@tutorial ecosystem} for available drivers & tools
+   *
+   * @class
+   */
+  class Dobo extends this.app.pluginClass.base {
+    /**
+     * @constant {string}
+     * @memberof Dobo
+     * @default 'db'
+     */
+    static alias = 'db'
+
+    /**
+     * @constant {string[]}
+     * @memberof Dobo
+     * @default ['count', 'avg', 'min', 'max', 'sum']
+     */
+    static aggregateTypes = ['count', 'avg', 'min', 'max', 'sum']
+    /**
+     * @constant {TPropType}
+     * @memberof Dobo
+     */
+    static propType = propType
+
     constructor () {
       super(pkgName, me.app)
-      this.alias = 'db'
       this.config = {
         connections: [],
-        mergeProps: ['connections'],
         validationParams: {
           abortEarly: false,
           convert: false,
@@ -25,7 +156,7 @@ async function factory (pkgName) {
         default: {
           property: {
             text: {
-              kind: 'text'
+              textType: 'text'
             },
             string: {
               length: 50
@@ -47,59 +178,49 @@ async function factory (pkgName) {
         memDb: {
           createDefConnAtStart: true,
           persistence: {
-            syncPeriod: 1
+            syncPeriodDur: '1s'
           }
-        }
-      }
-      this.aggregateTypes = ['count', 'avg', 'min', 'max', 'sum']
-      this.propType = {
-        integer: {
-          validator: 'number'
-        },
-        smallint: {
-          validator: 'number'
-        },
-        text: {
-          validator: 'string',
-          kind: 'text',
-          choices: ['text', 'mediumtext', 'longtext']
-        },
-        string: {
-          validator: 'string',
-          maxLength: 255,
-          minLength: 0
-        },
-        float: {
-          validator: 'number'
         },
-        double: {
-          validator: 'number'
-        },
-        boolean: {
-          validator: 'boolean'
-        },
-        date: {
-          validator: 'date'
-        },
-        datetime: {
-          validator: 'date'
-        },
-        time: {
-          validator: 'date'
-        },
-        timestamp: {
-          validator: 'timestamp'
-        },
-        object: {},
-        array: {}
+        applet: {
+          confirmation: false
+        }
       }
+
+      /**
+       * @type {Object[]}
+       */
+      this.drivers = []
+
+      /**
+       * @type {Object[]}
+       */
+      this.connections = []
+
+      /**
+       * @type {Object[]}
+       */
+      this.features = []
+
+      /**
+       * @type {Object[]}
+       */
+      this.schemas = []
     }
 
+    /**
+     * Initialize plugin and performing the following tasks:
+     * - {@link module:Lib.collectDrivers|Collecting all drivers}
+     * - {@link module:Lib.collectConnections|Collecting all connections}
+     * - {@link module:Lib.collectFeatures|Collecting all features}
+     * - {@link module:Lib.collectSchemas|Collecting all schemas}
+     * @method
+     * @async
+     */
     init = async () => {
       const { buildCollections } = this.app.bajo
-      const { fs } = this.lib
+      const { fs } = this.app.lib
       const checkType = async (item, items) => {
-        const { filter } = this.lib._
+        const { filter } = this.app.lib._
         const existing = filter(items, { type: 'dobo:memory' })
         if (existing.length > 1) this.fatal('onlyOneConnType%s', item.type)
       }
@@ -112,31 +233,52 @@ async function factory (pkgName) {
           name: 'memory'
         })
       }
-      this.connections = await buildCollections({ ns: this.name, container: 'connections', handler: collectConnections, dupChecks: ['name', checkType] })
-      if (this.connections.length === 0) this.log.warn('notFound%s', this.print.write('connection'))
-      await collectFeature.call(this)
+      this.connections = await buildCollections({ ns: this.ns, container: 'connections', handler: collectConnections, dupChecks: ['name', checkType] })
+      if (this.connections.length === 0) this.log.warn('notFound%s', this.t('connection'))
+      await collectFeatures.call(this)
       await collectSchemas.call(this)
     }
 
+    /**
+     * Start plugin
+     *
+     * @method
+     * @async
+     * @param {(string|Array)} [conns=all] - Which connections should be run on start
+     * @param {boolean} [noRebuild=false] - Set ```true``` to ALWAYS rebuild model on start. Yes, only set it to ```true``` if you REALLY know what you're doing!!!
+     */
     start = async (conns = 'all', noRebuild = true) => {
       const { importModule, breakNsPath } = this.app.bajo
-      const { find, filter, isString, map } = this.lib._
+      const { find, filter, isString, map } = this.app.lib._
       if (conns === 'all') conns = this.connections
       else if (isString(conns)) conns = filter(this.connections, { name: conns })
       else conns = map(conns, c => find(this.connections, { name: c }))
       for (const c of conns) {
         const { ns } = breakNsPath(c.type)
         const schemas = filter(this.schemas, { connection: c.name })
-        const mod = c.type === 'dobo:memory' ? memDbInstantiate : await importModule(`${ns}:/${this.name}/boot/instantiate.js`)
+        const mod = c.type === 'dobo:memory' ? memDbInstantiate : await importModule(`${ns}:/extend/${this.ns}/boot/instantiate.js`)
         await mod.call(this.app[ns], { connection: c, noRebuild, schemas })
         this.log.trace('driverInstantiated%s%s', c.driver, c.name)
       }
       await memDbStart.call(this)
     }
 
+    /**
+     * Pick only fields defined from a record
+     *
+     * @method
+     * @async
+     * @param {Object} [options={}] - Options object
+     * @param {Object} options.record - Record to pick fields from
+     * @param {Array} options.fields - Array of field names to be picked
+     * @param {Object} options.schema - Associated record's schema
+     * @param {Object} [options.hidden=[]] - Additional fields to be hidden in addition the one defined in schema
+     * @param {boolean} [options.forceNoHidden] - Force ALL fields to be picked, thus ignoring hidden fields
+     * @returns {Object}
+     */
     pickRecord = async ({ record, fields, schema = {}, hidden = [], forceNoHidden } = {}) => {
-      const { isArray, pick, clone, isEmpty, omit } = this.lib._
-      const { dayjs } = this.lib
+      const { isArray, pick, clone, isEmpty, omit } = this.app.lib._
+      const { dayjs } = this.app.lib
 
       const transform = async ({ record, schema, hidden = [], forceNoHidden } = {}) => {
         if (record._id) {
@@ -170,6 +312,20 @@ async function factory (pkgName) {
       return pick(await transform.call(this, { record, schema, hidden, forceNoHidden }), fl)
     }
 
+    /**
+     * Prepare records pagination:
+     * - making sure records limit is obeyed
+     * - making sure page is a positive value
+     * - if skip is given, recalculate limit to use skip instead of page number
+     * - Build sort info
+     *
+     * @method
+     * @async
+     * @param {Object} [filter={}] - Filter object
+     * @param {Object} schema - Model's schema
+     * @param {Object} options - Options
+     * @returns {TRecordPagination}
+     */
     prepPagination = async (filter = {}, schema, options = {}) => {
       const buildPageSkipLimit = (filter) => {
         let limit = parseInt(filter.limit) || this.config.default.filter.limit
@@ -188,7 +344,7 @@ async function factory (pkgName) {
       }
 
       const buildSort = (input, schema, allowSortUnindexed) => {
-        const { isEmpty, map, each, isPlainObject, isString, trim, keys } = this.lib._
+        const { isEmpty, map, each, isPlainObject, isString, trim, keys } = this.app.lib._
         let sort
         if (schema && isEmpty(input)) {
           const columns = map(schema.properties, 'name')
@@ -233,7 +389,7 @@ async function factory (pkgName) {
     }
 
     buildMatch = ({ input = '', schema, options }) => {
-      const { isPlainObject, trim } = this.lib._
+      const { isPlainObject, trim } = this.app.lib._
       if (isPlainObject(input)) return input
       const split = (value, schema) => {
         let [field, val] = value.split(':').map(i => i.trim())
@@ -266,7 +422,7 @@ async function factory (pkgName) {
     }
 
     buildQuery = ({ filter, schema, options = {} } = {}) => {
-      const { trim, find, isString, isPlainObject } = this.lib._
+      const { trim, find, isString, isPlainObject } = this.app.lib._
       let query = {}
       if (isString(filter.query)) {
         try {
@@ -295,9 +451,9 @@ async function factory (pkgName) {
     }
 
     sanitizeQuery = (query, schema, parent) => {
-      const { cloneDeep, isPlainObject, isArray, find } = this.lib._
-      const { isSet } = this.lib.aneka
-      const { dayjs } = this.lib
+      const { cloneDeep, isPlainObject, isArray, find } = this.app.lib._
+      const { isSet } = this.app.lib.aneka
+      const { dayjs } = this.app.lib
       const obj = cloneDeep(query)
       const keys = Object.keys(obj)
       const sanitize = (key, val, p) => {
@@ -336,13 +492,13 @@ async function factory (pkgName) {
     }
 
     getConnection = (name) => {
-      const { find } = this.lib._
+      const { find } = this.app.lib._
       return find(this.connections, { name })
     }
 
     getInfo = (name) => {
       const { breakNsPath } = this.app.bajo
-      const { find, map, isEmpty } = this.lib._
+      const { find, map, isEmpty } = this.app.lib._
       const schema = this.getSchema(name)
       const conn = this.getConnection(schema.connection)
       let { ns, path: type } = breakNsPath(conn.type)
@@ -355,8 +511,8 @@ async function factory (pkgName) {
     }
 
     getSchema = (input, cloned = true) => {
-      const { find, isPlainObject, cloneDeep } = this.lib._
-      const { pascalCase } = this.lib.aneka
+      const { find, isPlainObject, cloneDeep } = this.app.lib._
+      const { pascalCase } = this.app.lib.aneka
       let name = isPlainObject(input) ? input.name : input
       name = pascalCase(name)
       const schema = find(this.schemas, { name })
@@ -366,7 +522,7 @@ async function factory (pkgName) {
 
     getField = (name, model) => {
       const { getInfo } = this.app.dobo
-      const { find } = this.lib._
+      const { find } = this.app.lib._
       const { schema } = getInfo(model)
 
       return find(schema.properties, { name })
@@ -377,18 +533,18 @@ async function factory (pkgName) {
     }
 
     getMemdbStorage = (name, fields = []) => {
-      const { map, pick } = this.lib._
+      const { map, pick } = this.app.lib._
       const all = this.memDb.storage[name] ?? []
       if (fields.length === 0) return all
       return map(all, item => pick(item, fields))
     }
 
     listAttachments = async ({ model, id = '*', field = '*', file = '*' } = {}, { uriEncoded = true } = {}) => {
-      const { map, kebabCase } = this.lib._
-      const { pascalCase } = this.lib.aneka
+      const { map, kebabCase } = this.app.lib._
+      const { pascalCase } = this.app.lib.aneka
       const { importPkg, getPluginDataDir } = this.app.bajo
       const mime = await importPkg('waibu:mime')
-      const { fastGlob } = this.lib
+      const { fastGlob } = this.app.lib
       const root = `${getPluginDataDir('dobo')}/attachment`
       model = pascalCase(model)
       let pattern = `${root}/${model}/${id}/${field}/${file}`
@@ -412,6 +568,8 @@ async function factory (pkgName) {
       })
     }
   }
+
+  return Dobo
 }
 
 export default factory

package/lib/add-fixtures.js

@@ -2,8 +2,8 @@ import path from 'path'
 
 async function addFixture (name, { spinner } = {}) {
   const { resolvePath, readConfig, eachPlugins, getPluginDataDir } = this.app.bajo
-  const { isEmpty, isArray, isString } = this.lib._
-  const { fs } = this.lib
+  const { isEmpty, isArray, isString } = this.app.lib._
+  const { fs } = this.app.lib
   const { schema, connection } = this.getInfo(name)
   if (connection.proxy) {
     this.log.warn('proxiedConnBound%s', schema.name)
@@ -16,12 +16,13 @@ async function addFixture (name, { spinner } = {}) {
   let items = await readConfig(pattern, { ns: schema.ns, ignoreError: true })
   if (isEmpty(items)) items = []
   // override
-  const overrides = await readConfig(`${this.app.main.dir.pkg}/dobo/override/${schema.ns}/fixture/${base}.*`, { ns: this.name, ignoreError: true })
+  const overrides = await readConfig(`${this.app.main.dir.pkg}/extend/dobo/override/${schema.ns}/fixture/${base}.*`, { ns: this.ns, ignoreError: true })
 
   if (isArray(overrides) && !isEmpty(overrides)) items = overrides
   // extend
-  await eachPlugins(async function ({ dir, ns }) {
-    const extend = await readConfig(`${dir}/dobo/extend/${schema.ns}/fixture/${base}.*`, { ns, ignoreError: true })
+  await eachPlugins(async function ({ dir }) {
+    const { ns } = this
+    const extend = await readConfig(`${dir}/extend/dobo/extend/${schema.ns}/fixture/${base}.*`, { ns, ignoreError: true })
     if (isArray(extend) && !isEmpty(extend)) items.push(...extend)
   })
   if (isEmpty(items)) return result
@@ -56,7 +57,7 @@ async function addFixture (name, { spinner } = {}) {
     } catch (err) {
       console.log(err)
       err.model = schema.name
-      if (this.app.bajo.applet) this.print.fail(this.validationErrorMessage(err))
+      if (this.app.applet) this.print.fail(this.validationErrorMessage(err))
       result.failed++
     }
   }

package/lib/build-bulk-action.js

@@ -1,9 +1,9 @@
 async function buildBulkAction (name, action, options = {}) {
   const { fs, importModule } = this.app.bajo
-  const { camelCase } = this.lib._
+  const { camelCase } = this.app.lib._
   const { schema, driver, connection } = await this.getInfo(name)
   if (!options.force && (schema.disabled ?? []).includes(action)) throw this.error('methodIsDisabled%s%s', camelCase('bulk ' + action), name)
-  const file = `${driver.plugin}:/${this.name}/method/bulk/${action}.js`
+  const file = `${driver.plugin}:/extend/${this.ns}/method/bulk/${action}.js`
   if (!fs.existsSync(file)) throw this.error('methodUnsupported%s%s', camelCase('bulk ' + action), name)
   const handler = await importModule(file)
   return { handler, schema, driver, connection }

package/lib/check-unique.js

@@ -1,6 +1,6 @@
 async function checkUnique ({ schema, body, id }) {
-  const { isSet } = this.lib.aneka
-  const { filter, map, set } = this.lib._
+  const { isSet } = this.app.lib.aneka
+  const { filter, map, set } = this.app.lib._
   const singles = map(filter(schema.properties, p => (p.index ?? {}).type === 'unique'), 'name')
   const opts = { noHook: true, noCache: true, thrownNotFound: false, forceNoHidden: true }
   let old = {}

package/lib/collect-connections.js

@@ -2,18 +2,29 @@ async function defSanitizer (item) {
   return item
 }
 
-async function collectConnections ({ item, index, options }) {
+/**
+ * Collect all database connections from {@tutorial config}.
+ *
+ * @name collectConnections
+ * @memberof module:Lib
+ * @async
+ * @see Dobo#init
+ * @param {Object} [options={}]
+ * @param {Object} [options.item={}]
+ * @returns {Object}
+ */
+async function collectConnections ({ item }) {
   const conn = item
   const { importModule, breakNsPath } = this.app.bajo
-  const { has, find, isEmpty } = this.lib._
+  const { has, find, isEmpty } = this.app.lib._
   if (!has(conn, 'type')) this.fatal('mustValidDbType')
   let { ns, path: type } = breakNsPath(conn.type)
   if (isEmpty(type)) type = conn.type
   const driver = find(this.drivers, { ns, type })
   if (!driver) this.fatal('unsupportedDbType%s', conn.type)
-  let file = `${ns}:/${this.name}/lib/${type}/conn-sanitizer.js`
+  let file = `${ns}:/extend/${this.ns}/lib/${type}/conn-sanitizer.js`
   if (conn.type === 'dobo:memory') file = `${ns}:/lib/mem-db/conn-sanitizer.js`
-  if (driver.provider) file = `${driver.provider}:/${ns}/lib/${type}/conn-sanitizer.js`
+  if (driver.provider) file = `${driver.provider}:/extend/${ns}/lib/${type}/conn-sanitizer.js`
   let sanitizer = await importModule(file)
   if (!sanitizer) sanitizer = defSanitizer
   const result = await sanitizer.call(this, conn)

package/lib/collect-drivers.js

@@ -1,18 +1,27 @@
+/**
+ * Collect all database drivers from loaded plugins
+ *
+ * @name collectDrivers
+ * @memberof module:Lib
+ * @async
+ * @see Dobo#init
+ */
 async function collectDrivers () {
   const { eachPlugins, readConfig, runHook } = this.app.bajo
-  const { isString, find, pick, merge, cloneDeep } = this.lib._
+  const { isString, find, pick, merge, cloneDeep } = this.app.lib._
   const me = this
   me.drivers = []
   // built-in memory driver
   me.drivers.push({
     type: 'memory',
-    ns: me.name,
+    ns: me.ns,
     driver: 'memory',
     idField: merge(cloneDeep(me.config.default.idField), { name: 'id' })
   })
   // others
-  await runHook(`${this.name}:beforeCollectDrivers`)
-  await eachPlugins(async function ({ file, ns }) {
+  await runHook(`${this.ns}:beforeCollectDrivers`)
+  await eachPlugins(async function ({ file }) {
+    const { ns } = this
     const info = await readConfig(file, { ns })
     if (!info.type) this.fatal('driverMustProvideDbType')
     if (!info.driver) this.fatal('driverMustHaveName')
@@ -33,8 +42,8 @@ async function collectDrivers () {
       }
       me.drivers.push(merge(ext, driver))
     }
-  }, { glob: 'boot/driver.*', prefix: this.name })
-  await runHook(`${this.name}:afterCollectDrivers`)
+  }, { glob: 'boot/driver.*', prefix: this.ns })
+  await runHook(`${this.ns}:afterCollectDrivers`)
 }
 
 export default collectDrivers

package/lib/{collect-feature.js → collect-features.js}

@@ -1,23 +1,32 @@
 import path from 'path'
 
-async function handler ({ file, alias, ns }) {
+async function handler ({ file }) {
+  const { ns } = this
   const { importModule } = this.app.bajo
-  const { camelCase, isFunction } = this.lib._
+  const { camelCase, isFunction } = this.app.lib._
   const me = this.app.dobo
 
   let name = camelCase(path.basename(file, '.js'))
-  if (ns !== me.name) name = `${ns}.${name}`
+  if (ns !== me.ns) name = `${ns}.${name}`
   const mod = await importModule(file)
   if (!isFunction(mod)) this.fatal('featureNotAsync%s', name)
   me.feature[name] = mod
   me.log.trace('- %s', name)
 }
 
+/**
+ * Collect all database features from all loaded plugins
+ *
+ * @name collectFeatures
+ * @memberof module:Lib
+ * @async
+ * @see Dobo#init
+ */
 async function collectFeature () {
   const { eachPlugins } = this.app.bajo
   this.feature = {}
   this.log.trace('loadingDbFeature')
-  await eachPlugins(handler, { glob: 'feature/*.js', prefix: this.name })
+  await eachPlugins(handler, { glob: 'feature/*.js', prefix: this.ns })
   this.log.debug('totalLoadedFeatures%d', Object.keys(this.feature).length)
 }