oad-utils

Collection of utility functions for OAD: Operations As Data.

OAD: Operation As Data

Operations As Data(OAD) is the concept of handling large JSON data that all the data operations (update/find) should be written as JSON format (≒ plain object). This oad-utils provides utility functions for handling OAD.

Phenyl Family

oad-utils is one of Phenyl Family. Phenyl is a JavaScript Server/Client framework for State Synchronization over Environment(SSoE).

Installation

npm install oad-utils

Using types with flow

For Flow annotations, just use /jsnext entrypoint.

import { hasOwnNestedProperty, visitFindOperation } from 'oad-utils/jsnext'

All the interfaces are defined in the depending module mongolike-operations.

API Documentation

Overview

• normalizeQueryCondition()
• getNestedValue()
• hasOwnNestedProperty()
• updateOperationToJSON()
• normalizeUpdateOperation()
• mergeUpdateOperations()
• findOperationToJSON()
• visitFindOperation()
• parseDocumentPath()
• convertToDotNotationString()
• createDocumentPath()

Definitions

FindOperation

Operation to find values in large JSON.

See FindOperation(mongolike-operations) for detailed definition.

Example:

const findOperation = {
  $and: [
    { libraryName: 'phenyl' },
    { 'libraryVersion.major': { $gte: 1 } }
  ]
}

QueryCondition

Condition to find values in large JSON, included in FindOperation. Almost compatible with MongoDB's Query Operators.

See QueryCondition(mongolike-operations) for detailed definition.

UpdateOperation

Operations to update values of large JSON. Almost compatible with MongoDB's Update Operators.

See README of power-assign for more detailed use.

Restorable

Restorable is a characteristic of JavaScript class instances which meets the following requirement.

const jsonStr = JSON.stringify(instance)
const plain = JSON.parse(jsonStr)
const newInstance = new TheClass(plain)
 
assert.deepEqual(newInstance, instance)

Roughly, Restorable object is an instance which can re-created by passing its JSON object to the class constructor.

See is-restorable module for more detail.

DocumentPath

The same definition as Amazon DynamoDB's DocumentPath.

type DocumentPath = string

DocumentPath expresses nested value location.

{ foo: { arr: [ { bar: 'baz' }] }}

The string 'baz' is expressed as 'foo.arr[0].bar' in DocumentPath format.

This DocumentPath is slightly different from Dot Notation in MongoDB which expresses 'baz' as 'foo.arr.0.bar' (array index expression is different).

normalizeQueryCondition()

Convert the given object into regular QueryCondition.

import { normalizeQueryCondition } from 'oad-utils'
const cond = { name: 'Shin' }
const normalized = normalizeQueryCondition(cond)
assert.deepEqual(normalized, { $eq: { name: 'Shin' } })

getNestedValue()

Get the value in the object at the DocumentPath.

import { hasOwnNestedProperty } from 'oad-utils'
 
const obj = {
  foo: {
    bar: [{}, {}, { baz1: false, baz2: null }
    ]
  },
  foo2: undefined
}
 
assert(getNestedValue(obj, 'foo') === obj.foo)
assert(getNestedValue(obj, 'foo.bar') === obj.foo.bar)
assert(getNestedValue(obj, 'foo.bar[0]') === obj.foo.bar[0])
assert(getNestedValue(obj, 'foo.bar[1]') === obj.foo.bar[1])
assert(getNestedValue(obj, 'foo.bar[2]') === obj.foo.bar[2])
assert(getNestedValue(obj, 'foo.bar[2].baz1') === obj.foo.bar[2].baz1)
assert(getNestedValue(obj, 'foo.bar[2].baz2') === obj.foo.bar[2].baz2)
assert(getNestedValue(obj, 'foo2') === obj.foo2)

Behavior toward non-existing values:

assert(getNestedValue(obj, 'a.b.c.d.e') === undefined)
 
const noNullAccess = true
assert.throws(() => getNestedValue(obj, 'a.b.c.d.e', noNullAccess), /Cannot get value/)

Set the 3rd argument noNullAccess to true and an error is thrown when property access to null occurs.

hasOwnNestedProperty()

Check if the object has the DocumentPath.

import { hasOwnNestedProperty } from 'oad-utils'
 
const obj = {
  foo: {
    bar: [{}, {}, { baz1: false, baz2: null }
    ]
  },
  foo2: undefined
}
assert(hasOwnNestedProperty(obj, 'foo') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar[0]') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar[1]') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar[2]') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar[2].baz1') === true)
assert(hasOwnNestedProperty(obj, 'foo.bar[2].baz2') === true)
assert(hasOwnNestedProperty(obj, 'foo2') === true)
 
assert(hasOwnNestedProperty(obj, 'bar') === false)
assert(hasOwnNestedProperty(obj, 'foo.baz') === false)
assert(hasOwnNestedProperty(obj, 'foo.bar[3]') === false)
assert(hasOwnNestedProperty(obj, 'foo.bar[2].baz3') === false)
assert(hasOwnNestedProperty(obj, 'foo.bar2') === false)

updateOperationToJSON()

Convert UpdateOperation to Restorable JSON format.

import { updateOperationToJSON } from 'oad-utils'
class Name {
  constructor(params) {
    this.first = params.first
    this.last = params.last
  }
}
 
const person = { name: new Name({ first: 'Shin', last: 'Suzuki' }) }
const op = { $restore: { name: Name }, $set: { 'name.first': 'Shun' } }
assert.deepEqual(JSON.parse(JSON.stringify(op)).$restore.name, {}) // classes re converted to {} over serialization
assert.deepEqual(JSON.parse(JSON.stringify(updateOperationToJSON(op))).$restore.name, '')

mergeUpdateOperations()

[Experimental] Merge UpdateOperations into one UpdateOperation.

import { mergeOperations } from 'power-assign'
const merged = mergeOperations(
  { $set: { foo: 123 } },
  { $inc: { count: 1 } }
)
assert.deepEqual(merged, {
  $set: { foo: 123 },
  $inc: { count: 1 }
})

normalizeUpdateOperation()

Convert SetOperator to normalized operation.

import { normalizeOperation } from 'power-assign'
const op = { 'baz.biz': 3 })
assert.deepEqual(normalizeOperation(op), { $set: { 'baz.biz': 3 } })

findOperationToJSON()

Convert FindOperation to Restorable JSON format.

import { findOperationToJSON } from 'oad-utils'
const where = {
  name: { $regex: /^John/ }
}
assert.deepEqual(JSON.parse(JSON.stringify(where)).name.$regex, {}) // regex are converted to {} over serialization
assert.deepEqual(JSON.parse(JSON.stringify(findOperationToJSON(op))).name.$regex, '^John')

visitFindOperation()

Modify FindOperation by passing visitor functions.

Visit with simpleFindOperation visitor:

import { visitFindOperation } from 'oad-utils'
const where = {
  $or: [
    { email: '[e-mail]', password: 'foo-bar' },
    { email: '[e-mail]', password: 'foo-bar' },
  ]
}
const modifiedWhere = visitFindOperation(where, {
  simpleFindOperation: op => {
    return Object.assign({}, op, { isUser: true })
  }
})
assert.deepEqual(modifiedWhere, {
  $or: [
    { email: '[e-mail]', password: 'foo-bar', isUser: true },
    { email: '[e-mail]', password: 'foo-bar', isUser: true },
  ]
})

Visit with queryCondition visitor:

const where = {
  name: { $regex: /foo/ }
}
const modifiedWhere = visitFindOperation(where, {
  queryCondition: cond => {
    if (cond.$regex) {
      return Object.assign({}, cond, { $options: 'i' })
    }
    return cond
  }
})
assert.deepEqual(modifiedWhere, {
  name: { $regex: /foo/, $options: 'i' }
})

parseDocumentPath()

Parse DocumentPath into an array of property names.

import { parseDocumentPath } from 'oad-utils'
const docPath = 'user.favorites[1].music[30000]'
const attributes = parseDocumentPath(docPath)
assert.deepEqual(attributes, ['user', 'favorites', 1, 'music', 30000])

createDocumentPath()

Create DocumentPath from arguments.

import { createDocumentPath } from 'oad-utils'
const docPath = createDocumentPath('users', 1, 'favorites', 'musics', 24, 'title', '3', 'value')
assert(docPath === 'users[1].favorites.musics[24].title.3.value')

convertToDotNotationString()

Convert DocumentPath to MongoDB's Dot Notation.

import { convertToDotNotationString } from 'oad-utils'
const docPath = 'user.favorites[1].music[30000]'
const dotNotationString = convertToDotNotationString(docPath)
assert(dotNotationString === 'user.favorites.1.music.30000')

LICENSE

Apache License 2.0