dobo 2.0.0 → 2.0.1

package/method/validate.js

@@ -3,6 +3,80 @@ 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',
@@ -20,9 +94,9 @@ function buildFromDbSchema (schema, { fields = [], rule = {}, extFields = [] } =
   const {
     isPlainObject, get, each, isEmpty, isString, forOwn, keys,
     find, isArray, has, cloneDeep, concat, without
-  } = this.lib._
+  } = this.app.lib._
   const obj = {}
-  const me = this
+  const { propType } = this.app.pluginClass.dobo
   const refs = []
 
   function getRuleKv (kvRule) {
@@ -44,7 +118,7 @@ function buildFromDbSchema (schema, { fields = [], rule = {}, extFields = [] } =
     const rules = get(rule, prop.name, prop.rules ?? [])
     if (!isArray(rules)) return rules
     each(rules, r => {
-      const types = validator[me.propType[prop.type].validator]
+      const types = validator[propType[prop.type].validator]
       const { key, value } = getRuleKv(r)
       if (keys(minMax).includes(key)) minMax[key] = true
       if (key === 'ref') {
@@ -110,7 +184,7 @@ function buildFromDbSchema (schema, { fields = [], rule = {}, extFields = [] } =
     each(without(keys(obj), ...refs), k => {
       const prop = find(props, { name: k })
       if (!prop) return undefined
-      const types = validator[me.propType[prop.type].validator]
+      const types = validator[propType[prop.type].validator]
       const { key, value, columns = [] } = getRuleKv(r)
       if (!types.includes(key)) return undefined
       if (columns.length === 0 || columns.includes(k)) obj[k] = obj[k][key](value)
@@ -125,11 +199,26 @@ function buildFromDbSchema (schema, { fields = [], rule = {}, extFields = [] } =
   return result
 }
 
+/**
+ * Validate value against JOI schema
+ *
+ * @method
+ * @memberof Dobo
+ * @async
+ * @param {Object} value - value to validate
+ * @param {Object} joiSchema - JOI schema
+ * @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 (value, joiSchema, { ns, fields, extFields, params } = {}) {
-  const { defaultsDeep, isSet } = this.lib.aneka
-  const { isString, forOwn, find } = this.lib._
+  const { defaultsDeep, isSet } = this.app.lib.aneka
+  const { isString, forOwn, find } = this.app.lib._
 
-  ns = ns ?? [this.name]
+  ns = ns ?? [this.ns]
   params = defaultsDeep(params, this.config.validationParams)
   const { rule = {} } = params
   delete params.rule

package/package.json

@@ -1,36 +1,41 @@
-{
-  "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.0.1",
+  "description": "DBMS for Bajo Framework",
+  "main": "index.js",
+  "scripts": {
+    "build-doc": "jsdoc -c .jsdoc.conf.json",
+    "test": "mocha"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "clean-jsdoc-theme": "^4.3.0",
+    "jsdoc-plugin-intersection": "^1.0.4"
+  }
+}

package/wiki/APPLETS.md

@@ -0,0 +1,57 @@
+# Applet
+
+## connection
+
+Gunakan applet ini untuk menampilkan koneksi database yang Anda miliki
+
+```bash
+$ node index.js -a dobo:connection                        # Masuk ke mode interaktif
+$ node index.js -a dobo:connection default                # Tampilkan koneksi dengan nama 'default'
+$ node index.js -a dobo:connection default --format=json  # Tampilkan dalam format 'json'
+```
+
+## modelClear
+
+Hapus tabel yang Anda inginkan. **Perhatian**: tabel akan dihapus dari database BESERTA isinya. Jadi pastikan bahwa Anda telah membackup tabel Anda terlebih dahulu sebelum Anda memanggil applet ini.
+
+```bash
+$ node index.js -a dobo:modelRebuild                      # Masuk ke mode interaktif
+$ node index.js -a dobo:modelRebuild 'Cdb*'               # Hapus model dengan awalan 'Cdb'
+```
+
+## modelRebuild
+
+Pada saat pertama kali sebuah plugin dimuat dan plugin meng-extend Dobo, Anda perlu memanggil applet ini untuk membuat tabel sesuai dengan skema yang telah ditentukan.
+
+```bash
+$ node index.js -a dobo:modelRebuild                      # Gunakan mode interaktif
+$ node index.js -a dobo:modelRebuild CdbCountry Sumba     # Masukkan satu persatu nama modelnya
+$ node index.js -a dobo:modelRebuild 'Cdb*'               # List semua model dengan awalan 'Cdb'
+```
+Setelah tabel sukses dibuat, maka jika model dilengkapi dengan fixture, fixture tersebut akan dimuat didalam tabel yang bersangkutan.
+
+Jika tabel telah ada di database, Anda harus menggunakan switch ```--force``` untuk memaksa model bisa di hapus kemudian dibuat ulang kembali.
+
+## recordCreate
+
+Gunakan applet ini untuk membuat rekord:
+
+```bash
+$ node index.js -a dobo:recordCreate CdbCountry
+ℹ App is running as applet...
+✔ Enter JSON payload: { "id": "XX", "name": "My Country" }
+╭ CdbCountry ─────────────╮
+│ {                       │
+│   "id": "XX",           │
+│   "name": "My Country"  │
+│ }                       │
+╰─────────────────────────╯
+? Are you sure to continue? (y/N)
+```
+
+## recordFind
+
+Mencari rekord yang sesuai dengan kriteria pemilihan Anda. Jika kriteria tidak dimasukkan (filter kosong), maka akan diberikan semua rekord yang ada.
+
+```bash
+

package/wiki/CONFIG.md

@@ -0,0 +1,25 @@
+# Config Object
+
+| Key Name | Type | Default | Description |
+| ------- | ---- | ----- | ----------- |
+| ```connections``` | ```array``` | ```[]``` | Connection object |
+| ```validationParams``` | ```object``` | | Defaults to [Joi validate's](https://joi.dev/api/?v=17.13.3#anyvalidateasyncvalue-options) options |
+|     ```abortEarly``` | ```boolean``` | ```false``` | |
+|     ```convert``` | ```boolean``` | ```false``` | |
+|     ```allowUnknown``` | ```boolean``` | ```true``` | |
+| ```default``` | ```object``` | | default values |
+|     ```property``` | ```object``` | | |
+|         ```text``` | ```object``` | | |
+|             ```textType``` | ```string``` | ```text``` | Allowed values: ```text```, ```mediumtext```, or ```longtext``` |
+|         ```string``` | ```object``` | | |
+|             ```length``` | ```number``` | ```50``` | |
+|         ```filter``` | ```object``` | | |
+|             ```limit``` | ```number``` | ```25``` | Rows returned in one page |
+|             ```maxLimit``` | ```number``` | ```200``` | Max rows returned in one page |
+|             ```hardLimit``` | ```number``` | ```10000``` | Max rows returned on dataset export |
+|             ```sort``` | ```array``` | | |
+|         ```idField``` | ```object``` | | |
+| ```memDb``` | ```object``` | | |
+|     ```createDefConnAtStart``` | ```boolean``` | ```true``` | |
+|     ```persistence``` | ```object``` | | |
+|         ```syncPeriodDur``` | ```string | number``` | ```1s``` | |

package/wiki/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Thanks very much to everyone who wants to join as a contributor, but I have committed to devoting 100% of my time to this project. Therefore, I'm currently unable to accept pull requests from anyone until the project is large enough for me to manage it independently.
+
+However, I am available if you encounter any bugs that require immediate fixes. Please report your issues in a GitHub issue, and I'll try to address them promptly. I'm also open to criticism and suggestions for improvements or requests for new features.

package/wiki/DEV-GUIDE.md

@@ -0,0 +1 @@
+# Developer Guide

package/wiki/ECOSYSTEM.md

@@ -0,0 +1,20 @@
+# Ecosystem
+
+## Drivers
+
+| Package | Docs | NS | Alias | Description |
+| ------- | ---- | -- | ----- | ----------- |
+| [dobo-couchdb](https://github.com/ardhi/dobo-couchdb) | [Docs](https://ardhi.github.io/dobo-couchdb) | doboCouchdb | dbcouch | CouchDB Driver |
+| [dobo-elasticsearch](https://github.com/ardhi/dobo-elasticsearch) | [Docs](https://ardhi.github.io/dobo-elasticsearch) | doboElasticsearch | dbes | Elasticsearch Driver |
+| [dobo-knex](https://github.com/ardhi/dobo-knex) | [Docs](https://ardhi.github.io/dobo-knex) | doboKnex | dbknex | Knex/SQL Driver |
+| [dobo-mongodb](https://github.com/ardhi/dobo-mongodb) | [Docs](https://ardhi.github.io/dobo-mongodb) | doboMongodb | dbmongo | MongoDB Driver |
+| [dobo-redis](https://github.com/ardhi/dobo-redis) | [Docs](https://ardhi.github.io/dobo-redis) | doboRedis | dbredis | Redis Driver |
+| [dobo-restproxy](https://github.com/ardhi/dobo-restproxy) | [Docs](https://ardhi.github.io/dobo-restproxy) | doboRestproxy | dbrpx | Restproxy Driver |
+| [dobo-restproxy-jsonserver](https://github.com/ardhi/dobo-restproxy-jsonserver) | [Docs](https://ardhi.github.io/dobo-restproxy-jsonserver) | doboResporoxyJsonserver | dbrpxjs |JsonServer Support for doboRestproxy |
+| [dobo-restproxy-ndut](https://github.com/ardhi/dobo-restproxy-ndut) | [Docs](https://ardhi.github.io/dobo-restproxy-ndut) | doboRestproxyNdut | dbrpxndut | NDUT Support for doboRestproxy |
+
+## Misc
+
+| Package | Docs | NS | Alias | Description |
+| ------- | ---- | -- | ----- | ----------- |
+| [dobo-extra](https://github.com/ardhi/dobo-extra) | [Docs](https://ardhi.github.io/dobo-extra) | doboExtra | dbx | Dobo Extra Tools/Utility |

package/wiki/GETTING-STARTED.md

@@ -0,0 +1,166 @@
+# Getting Started
+
+> If you're new to the [Dobo DBMS](https://ardhi.github.io/dobo), we recommend you to read and follow along with [Bajo Tutorial](https://ardhi.github.io/bajo/tutorial-01-getting-started.html) first, as this document is the continuation of it
+
+**Dobo** is the Bajo sub-framework developed specifically to handle database management. In this tutorial, we'll go over how to install the necessary packages and interact with them.
+
+Here is some basic knowledge about Dobo you need to be familiar with:
+
+- All record-related actions mimic REST API methods: *find* records, *get* a particular record by its ID, *create* a new record, *update* an existing record by ID and payload, and *remove* an existing record by its ID.
+- A Dobo model requires a predefined schema. Even if you use a NoSQL database, you still need to write a schema.
+- There are two main groups of methods to be familiar with:
+  - ```dobo.model{Action}``` methods manage everything related to model management, such as table creation or deletion.
+  - ```dobo.record{Action}``` methods handle record manipulation.
+- A record in Bajo always needs to have an ID. The ID can be alphanumeric characters or an integer, and it is defined by the underlying driver used by the model.
+
+For more info about Dobo, please [click here](https://ardhi.github.io/dobo).
+
+### Installation
+
+As you might have guessed, Dobo and its drivers are normal Bajo plugins. Although [many drivers](https://github.com/ardhi/dobo/tutorials/drivers.md) exist, for this tutorial, we'll only use SQLite 3, which is provided by the dobo-knex driver.
+
+Now, please install the required plugins and SQLite drivers first:
+
+```bash
+$ npm install dobo dobo-knex sqlite3
+```
+
+Don't forget to add ```dobo``` and ```dobo-knex``` to the ```data/config/.plugins``` file.
+
+### Model
+
+Let's pretend we're building an address book with fields like name, age, phone, etc. This entity needs to be modeled with a schema and then "connected" to a database:
+
+1. Create ```main/extend/dobo/schema/address-book.json``` file.
+2. Enter the following schema:
+   ```json
+   {
+     "properties": [{
+       "name": "firstName",
+       "type": "string",
+       "maxLength": 20,
+       "required": true,
+       "index": true
+     },
+       "lastName::20:true:true",
+       "age:smallint",
+       "phone::20:true:true",
+       "email::50:true"
+     ],
+     "feature": {
+       "createdAt": true,
+       "updatedAt": true
+     }
+   }
+   ```
+   You should notice here that in properties you can use either the verbose, full-object syntax or the string-based one. Please visit the Dobo documentation to learn more.
+
+3. Create ```main/extend/dobo/fixture/address-book.json``` file. Fixtures allow you to quickly fill your database with predefined records. It's not required, but it helps a lot with prototyping.
+   ```json
+   [{
+     "firstName": "James",
+     "lastName": "Bond",
+     "phone": "+44-007"
+   }, {
+     "firstName": "Felix",
+     "lastName": "Leiter",
+     "age": 50,
+     "phone": "+1-0000001"
+   }]
+   ```
+4. By default, all schemas are connected to a database connection named ```default```. Now let's create this connection by creating ```data/config/dobo.json``` file:
+
+   ```json
+   {
+     "connections": [{
+       "name": "default",
+       "type": "knex:sqlite3",
+       "connection": {
+         "filename": "my-project.sqlite3"
+       }
+     }]
+   }
+   ```
+5. That's all there is to it. Now you need to build this model like this:
+   ```
+   $ node index.js -a dobo:modelRebuild MainAddressBook
+   ℹ App runs in applet mode
+   ╭ Schema (1) ──────╮
+   │ MainAddressBook  │
+   ╰──────────────────╯
+   ✔ The above mentioned schema(s) will be rebuilt as model. Continue? Yes
+   ✔ Model 'MainAddressBook' successfully created
+   ℹ Done! Succeded: 1, failed: 0, skipped: 0
+   ✔ Fixture on 'MainAddressBook': added 2, rejected: 0
+   ```
+6. Done!
+
+Note: Although you can use YAML or TOML for schemas/fixtures, it's recommended to stick with JSON because it's always supported and doesn't require an extra plugin.
+
+Dobo models are by default always named with ```{Alias}{ModelName}```, which is a pascal-cased plugin alias and base name from your schema file. For field names, Dobo use camel-cased names as a convention. You can change this behavior to match your needs, but it is suggested that you're keeping these conventions at least for this tutorial.
+
+### Applets
+
+Dobo provides you with a number of applets that will help you manipulate models and records directly. This means you don't have to touch your tables and databases directly through SQL statements or NoSQL procedures ever again. Everything can be managed through one common syntax provided by Dobo, regardless of your backend type.
+
+First, let's try to list records:
+
+```bash
+$ node index.js -a dobo:recordFind MainAddressBook
+ℹ App runs in applet mode
+✔ Please enter your query (if any):
+✔ Done
+┌────┬───────────┬──────────┬─────┬────────────┬───────┬──────────────────────────┬──────────────────────────┐
+│ id │ firstName │ lastName │ age │ phone      │ email │ createdAt                │ updatedAt                │
+├────┼───────────┼──────────┼─────┼────────────┼───────┼──────────────────────────┼──────────────────────────┤
+│ 2  │ Felix     │ Leiter   │ 50  │ +1-0000001 │       │ 2025-09-18T13:47:29.296Z │ 2025-09-18T13:47:29.296Z │
+├────┼───────────┼──────────┼─────┼────────────┼───────┼──────────────────────────┼──────────────────────────┤
+│ 1  │ James     │ Bond     │     │ +44-007    │       │ 2025-09-18T13:47:29.280Z │ 2025-09-18T13:47:29.280Z │
+└────┴───────────┴──────────┴─────┴────────────┴───────┴──────────────────────────┴──────────────────────────┘
+```
+
+Now, add a new record:
+
+```bash
+$ node index.js -a dobo:recordCreate MainAddressBook
+ℹ App runs in applet mode
+✔ Enter JSON payload: { "firstName": "Miss", "lastName": "Moneypenny" }
+╭ MainAddressBook ────────────╮
+│ {                           │
+│   "firstName": "Miss",      │
+│   "lastName": "Moneypenny"  │
+│ }                           │
+╰─────────────────────────────╯
+✖ Error: Validation Error
+✔ Enter JSON payload: { "firstName": "Miss", "lastName": "Moneypenny", "phone": "+44-111" }
+╭ MainAddressBook ─────────────╮
+│ {                            │
+│   "firstName": "Miss",       │
+│   "lastName": "Moneypenny",  │
+│   "phone": "+44-111"         │
+│ }                            │
+╰──────────────────────────────╯
+✔ Done
+┌───────────┬──────────────────────────┐
+│ id        │ 3                        │
+├───────────┼──────────────────────────┤
+│ firstName │ Miss                     │
+├───────────┼──────────────────────────┤
+│ lastName  │ Moneypenny               │
+├───────────┼──────────────────────────┤
+│ age       │                          │
+├───────────┼──────────────────────────┤
+│ phone     │ +44-111                  │
+├───────────┼──────────────────────────┤
+│ email     │                          │
+├───────────┼──────────────────────────┤
+│ createdAt │ 2025-09-18T14:38:11.933Z │
+├───────────┼──────────────────────────┤
+│ updatedAt │ 2025-09-18T14:38:11.933Z │
+└───────────┴──────────────────────────┘
+```
+
+As you can see, Dobo is smart enough to reject any payload that isn't right. In this case, we forgot to include the phone number since according to the schema, this field is defined as required.
+
+You can now try all of Dobo's other applets. [This page](https://github.com/ardhi/dobo/tutorials/applets) provides its complete list.
+

package/wiki/USER-GUIDE.md

@@ -0,0 +1 @@
+# User Guide