OnceDB

A dynamic schema Node.js OnceDB client.

Install

npm install oncedb

Quick start

Create an oncedb client instance:

var oncedb = require('oncedb')()

This will connect to the local oncedb-server which no password is set.

options

OnceDB connection options:

const oncedb = OnceDB(options, cb)

Options:

• host: Server address
• port: [Number] Service port number
• auth: Password set in oncedb-server
• select: [Number] selected database
• schema: schema folder path to load

Example

const OnceDB = require('oncedb')
const options = {
    auth    : '1234567890'
  , select  : 0
  , host    : '127.0.0.1'
  , port    : 6379
}
const oncedb = OnceDB(options);

Example with callback:

const oncedb = OnceDB(options, function(err) {
    if (err {
        console.log('connect error', err)
        return
    }

    console.log('connected')
})

Example

Data can be updated or queried after oncedb.client is created, here is an example of testOnceDB.js:

var util    = require('util');
var oncedb  = require('oncedb')();

oncedb.schema('user', {
    username  : 'id'
  , password  : ''
  , title     : 'group'
  , skills    : 'keywords'
  , birthday  : 'date;sort'
})

oncedb.upsert('user', { username: 'dota', password: '123456', title: 'SDEII', skills: 'c,go,node.js', birthday: '2000-01-01' }, function(err) {
  if (err) {
    console.log(err)
  }
})

oncedb.upsert('user', { username: 'like', password: '654321', title: 'SDEI', skills: 'javascript,node.js', birthday: '2010-12-12' }, function(err) {
  if (err) {
    console.log(err)
  }

  //When the update is complete, start the query
  oncedb.select('user', { skills: 'node.js' }, function(err, rows) {
    if (err) {
      console.log(err)
    }

    console.log(rows)
  })
})

Execute the testOnceDB.js:

$ node testOnceDB.js
[
  {
    _key: 'user:dota',
    skills: [ 'c', 'go', 'node.js' ],
    username: 'dota',
    password: '123456',
    title: 'SDEII',
    birthday: '2000-01-01'
  },
  {
    _key: 'user:like',
    skills: [ 'javascript', 'node.js' ],
    username: 'like',
    password: '654321',
    title: 'SDEI',
    birthday: '2010-12-12'
  }
]

Make sure oncedb-server service is running.

Promises & async/await

You can wrap the oncedb methods to support async/ await syntax. Using util.promisify method:

const util    = require('util');
const oncedb  = require('oncedb')();

// promisify methods
const insert  = util.promisify(oncedb.insert).bind(oncedb)
const update  = util.promisify(oncedb.update).bind(oncedb)
const upsert  = util.promisify(oncedb.upsert).bind(oncedb)
const select  = util.promisify(oncedb.select).bind(oncedb)
const remove  = util.promisify(oncedb.remove).bind(oncedb)

;(async() => {

  oncedb.schema('user', {
      username  : 'id'
    , password  : ''
    , title     : 'group'
    , skills    : 'keywords'
    , birthday  : 'date;sort'
  })

  await upsert('user', { username: 'dota', password: '123456', title: 'SDEII', skills: 'c,go,node.js', birthday: '2000-01-01' })
  await upsert('user', { username: 'like', password: '654321', title: 'SDEI', skills: 'javascript,node.js', birthday: '2010-12-12' })

  let rows = await select('user', { skills: 'c' })
  console.log(rows)

})()

Run the testOnceDB.js

$ node testOnceDB.js
rows.count 2
rows.length 1
[ { _key: 'user:dota',
    skills: [ 'c', 'go', 'node.js' ],
    username: 'dota',
    password: '1234',
    title: 'SDEII',
    birthday: '2000-01-01' } ]

You can use these async functions directly.

oncedb.selectAsync
oncedb.upsertAsync
oncedb.updateAsync
oncedb.removeAsync
oncedb.insertAsync

Document

Reference: OnceDB data query and delete instruction

oncedb.client

oncedb.client is an object based on node-redis, and with OnceDB custom extension commands added.

You can use util.promisify method on these commands.

const util    = require('util');
const oncedb  = require('oncedb')();

const hgetall = util.promisify(oncedb.client.hgetall).bind(oncedb.client)
const zrange  = util.promisify(oncedb.client.zrange).bind(oncedb.client)

oncedb.upsert

Update data, add if not exist.

oncedb.upsert(schemaName, updateObject, callback)

• oncedb.insert: Insert non-existent data
• oncedb.update: Update existing data
• oncedb.remove: Remove data

oncedb.select

oncedb.select is equal to oncedb.find.

oncedb.select(schemaName, [ where, ] callback [, options ])
oncedb.select(schemaName, where, [ options, ] callback)

where:

• equal query: { id: 'value' }
• string contain query: { id: { '~': 'partial string' } }
• compare query: { id: { '>': 10 } }

options:

• from: Number of rows to start, starting at 0
• to: Number of rows to end, -1 or (rows.count -1) is the last.
• range: Array object, equal to [ from, to ]
• desc Use reverse order
• order / sort / between: sort / order field, you can specify the range of scores in the array [ field, startScore, stopScore ]
• index: true or string. Output search results to the index, available during index search

rows.count

If using full-text search: rows.count = -1 If the search fields are all index fields: rows.count >= 0

;(async() => {
  oncedb.schema('blog', { id: 'id;sequence', visit: 'sort' })

  await upsert('blog', { visit: 10 })
  await upsert('blog', { visit: 22 })
  await upsert('blog', { visit: 44 })
  await upsert('blog', { visit: 14 })

  let blogs = await select('blog', {}, { order: [ 'visit', 10, 30 ], range: [0, 1], desc: true })
  console.log('rows.count', blogs.count)
  console.log(blogs)
})()

Results:

rows.count 3
[
  { _key: 'blog:2', id: '2', visit: '22' },
  { _key: 'blog:4', id: '4', visit: '14' }
]

oncedb.remove

Delete query data

oncedb.remove(schemaName, where [,callback])

schema

Schema in OnceDB is similar to table in SQL database. Schema can specify the field types, auxiliary index type, and so on.

oncedb.schema(schemaName, definitions [,callback])

field types

Fields are defined by keywords.

schema: id

Each schema must have one and only one ID field.

Optional options:

• Custom primary key index
• Custom score weights

;(async() => {
  oncedb.schema('user', {
      username  : 'id("users", this.ctime)'
    , ctime     : ''
  })

  await upsert('user', { username: 'dota', ctime: 123456 })
  let lines = await zrange('users', 0, -1, 'withscores')
  console.log(lines)
})()

results:

[ 'dota', '123456' ]

schema: sequence

Optional parameters:

• prefix: prefix of sequence
• start: start number
• increment: increment number

Example with parameters:

;(async() => {
  oncedb.schema('blog', { id: 'id;sequence("B", 1000, 10)', title: '' })

  await upsert('blog', { title: 'blog 1' })
  await upsert('blog', { title: 'blog 2' })
  let blogs = await select('blog')
  console.log(blogs)
})()

Result:

[
  { _key: 'blog:B1010', id: 'B1010', title: 'blog 1' },
  { _key: 'blog:B1020', id: 'B1020', title: 'blog 2' }
]

schema: date/ datetime

Dates are numbers in the database.

;(async() => {
  oncedb.schema('user', { username: 'id', ctime: 'date' })

  await upsert('user', { username: 'dota', ctime: '2000-10-10' })
  await upsert('user', { username: 'hero', ctime: '2020-10-10' })

  let user  = await hgetall('user:dota')
  let users = await select('user', { ctime: { '>': '2010-1-1' } })
  console.log(user)
  console.log(users)
})()

Result:

{ username: 'dota', ctime: '971136000000' }
[ { _key: 'user:hero', ctime: '2020-10-10', username: 'hero' } ]

Date output format can be specified using dateFormat and dateTimeformat

oncedb.dateFormat     = 'yyyy/mm/dd'
oncedb.datetimeFormat = 'yyyy/mm/dd hh:MM:ss'
  
let users = await select('user', {}, { from: 0, to: 0 })
console.log(users)

Result:

[ { _key: 'user:dota', username: 'dota', ctime: '2000/10/10' } ]

schema: group, index

Grouping index: use 'group' or 'index'

;(async() => {
  oncedb.schema('blog', { id: 'id;sequence', poster: 'group' })

  await upsert('blog', { poster: 'dota' })
  await upsert('blog', { poster: 'hero' })
  await upsert('blog', { poster: 'dota' })

  let blogs = await select('blog', { poster: 'dota' })
  console.log(blogs)
})()

Result:

[
  { _key: 'blog:1', poster: 'dota', id: '1' },
  { _key: 'blog:3', poster: 'dota', id: '3' }
]

Default grouping index name: *schema.field:value

  let lines = await zrange('*blog.poster:dota', 0, -1)
  console.log(lines)
  > [ '1', '3' ]

Optional options:

• Custom index name
• Custom score weights

oncedb.schema('blog', { id: 'id;sequence', poster: 'group("blog_user", Date.now())' })

schema: keywords, groups

Keywords index: use "keywords" or "groups" Keywords separated by commas or array objects:

;(async() => {
  oncedb.schema('blog', { id: 'id;sequence', keys: 'keywords' })

  await upsert('blog', { keys: 'node.js,c,go' })
  await upsert('blog', { keys: [ 'go', 'c' ] })
  await upsert('blog', { keys: 'node.js,c' })
  // select data which has go and c
  let blogs = await select('blog', { keys: ['go', 'c'] })
  console.log(blogs)
})()

Results:

[
  { _key: 'blog:1', keys: [ 'node.js', 'c', 'go' ], id: '1' },
  { _key: 'blog:2', keys: [ 'go', 'c' ], id: '2' }
]

Optional options:

• Custom index name
• Custom score weights

oncedb.schema('blog', { id: 'id', keys: 'keywords("blog_keys", Date.now())' })

schema: sort, order

Sort index: use "sort" or "order"

;(async() => {
  oncedb.schema('blog', { id: 'id;sequence', visit: 'sort' })

  await upsert('blog', { visit: 10 })
  await upsert('blog', { visit: 22 })
  await upsert('blog', { visit: 44 })
  await upsert('blog', { visit: 14 })

  let blogs = await select('blog', {}, { order: [ 'visit', 10, 20 ] })
  console.log(blogs)
})()

Results:

[
  { _key: 'blog:1', id: '1', visit: '10' },
  { _key: 'blog:4', id: '4', visit: '14' }
]

Other rules

schema: required

schema: int

schema: number

schema: array, json, object

schema: min (minNumber)

schema: max (maxNumber)

schema: minlen (minLength)

schema: maxlen (maxLength)

oncedb.extend

Extend an existing schema.

Join query

The search object can be an array to implement a join query

oncedb.select(schemaName, [query1, query2 ...], options, cb)
oncedb.select(schemaName, [[query1, options1], [query2, options2] ...], options, cb)

Examples

oncedb.schema('issue', { id:'id;sequence', group:'index', keys:'keywords', priority:'sort' })

await upsert('issue', { group: 'bug', keys: 'node.js,c,go', priority: 1 })
await upsert('issue', { group: 'task', keys: 'java,c,go', priority: 7 })
await upsert('issue', { group: 'task', keys: 'java,c', priority: 4 })

Merge query two conditions: Returns 3 rows of data

var issues = await select('issue', [ { group: 'task'}, { priority: 1 } ])

Merge query with parameters:Returns 2 rows of data

var issues = await select('issue', [
    [ { group: 'task'}, { between: [ 'priority', 7, 10 ] } ]
  , { keys: 'node.js' }
])

Events

ready

oncedb.on('ready', function() {
  console.log('ready')
})

error

oncedb.on('error', function(err) {
  console.log('error', err)
})

connect

oncedb.on('connect', function(err) {
  console.log('connect')
})

oncedb.client extension

Reference: oncedb command reference

oncedb.client.execute(command, cb)

oncedb.client.hsearch(keyPattern, conditions, cb)

oncedb.client.horsearch(keyPattern, conditions, cb)

oncedb.client.hsearchids(keyPattern, keys, conditions, cb)

oncedb.client.hselect(fields, keys, cb)

oncedb.client.hmgetall(args, cb)

oncedb.client.hmget(args, cb)

oncedb.client.hmset(args, cb)

oncedb.client.zhsearch(zsetKey, from, to, schemaName, conditions, cb)

oncedb.client.zrangehmget(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrevrangehmget(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrangehmgetbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrevrangehmgetbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrangehmgetbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrevrangehmsumbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrangehmsum(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrevrangehmsum(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrangehmsumbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.zrevrangehmsumbyscore(zsetKey, from, to, schemaAndField, cb)

oncedb.client.shmget(setKey, schemaAndField, cb)

oncedb.client.shmset(setKey, schemaName, updateObject, cb)

oncedb.client.shmsum(setKey, schemaAndField, cb)