@yodata/transform
Version:
declarative, JSON transformation library
440 lines (277 loc) • 15.6 kB
Markdown
# @yodata/transform
declarative, composable JSON transformation utility.
## Installation
```sh
> npm install --save @yodata/transform
```
## Usage
```javascript
const {Context, pluginDefaultValues} = require('@yodata/transform')
const input = {
Name: 'Bruce Wayne',
Address: '1007 Mountain Drive',
City: 'Gotham City',
State: 'NJ',
Zip: '00001',
Phone: '1-800-4-BATMAN'
}
const toPerson = new Context({
Name: 'name',
Address: 'streetAddress',
City: 'addressLocality',
State: 'addressRegion',
Zip: 'postalCode',
Phone: 'telephone'
})
toPerson.map(input)
// result
{
name: 'Bruce Wayne',
streetAddress: '1007 Mountain Drive',
addressRegion: 'NJ',
addressLocality: 'Gotham City',
postalCode: '00001',
telephone: '1-800-4-BATMAN'
}
```
## Features
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
- [fromString](#fromstring)
- [Parameters](#parameters)
- [compileContext](#compilecontext)
- [Parameters](#parameters-1)
- [map](#map)
- [Parameters](#parameters-2)
- [pathArray](#patharray)
- [Parameters](#parameters-3)
- [Context](#context)
- [Parameters](#parameters-4)
- [parseContext](#parsecontext)
- [Parameters](#parameters-5)
- [extend](#extend)
- [Parameters](#parameters-6)
- [toJSON](#tojson)
- [toJS](#tojs)
- [setOption](#setoption)
- [Parameters](#parameters-7)
- [getOption](#getoption)
- [Parameters](#parameters-8)
- [has](#has)
- [Parameters](#parameters-9)
- [get](#get)
- [Parameters](#parameters-10)
- [isRemoved](#isremoved)
- [Parameters](#parameters-11)
- [isRedacted](#isredacted)
- [Parameters](#parameters-12)
- [allowsAdditionalProperties](#allowsadditionalproperties)
- [isAllowed](#isallowed)
- [Parameters](#parameters-13)
- [mapKey](#mapkey)
- [Parameters](#parameters-14)
- [mapKeys](#mapkeys)
- [Parameters](#parameters-15)
- [mapValue](#mapvalue)
- [Parameters](#parameters-16)
- [map](#map-1)
- [Parameters](#parameters-17)
- [transformEntry](#transformentry)
- [Parameters](#parameters-18)
- [use](#use)
- [Parameters](#parameters-19)
- [dispatch](#dispatch)
- [Parameters](#parameters-20)
- [fromYaml](#fromyaml)
- [Parameters](#parameters-21)
- [mapEntry](#mapentry)
- [Parameters](#parameters-22)
- [isExpression](#isexpression)
- [Parameters](#parameters-23)
- [Events](#events)
- [getContext](#getcontext)
- [Parameters](#parameters-24)
- [loadContext](#loadcontext)
- [Parameters](#parameters-25)
- [loadData](#loaddata)
- [Parameters](#parameters-26)
- [fromFile](#fromfile)
- [Parameters](#parameters-27)
- [isURL](#isurl)
- [Parameters](#parameters-28)
### fromString
Attempt to parse a string as yaml or json
#### Parameters
- `value` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the value to parse
- `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** optionsal js-yaml parserOptions (optional, default `{json:true}`)
### compileContext
Fetch a conext by path or url and return an async context.map helper function
#### Parameters
- `target` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `contextOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**
Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)>**
### map
#### Parameters
- `object`
### pathArray
Converts a path expression a.b.c to a path array [a,b,c]
#### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** the path or path array
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** pathArray
### Context
Creates a new Context
#### Parameters
- `contextDefinition` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** a valid ContextDefinition object (optional, default `{}`)
- `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** configuration options (optional, default `{}`)
#### parseContext
Parse & normalize a context definition JSON string
##### Parameters
- `contextDefinition` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** a valid ContextDefinition
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** normalized ContextDefinition document
#### extend
Creates a new context from the current + the provided context definition document.
##### Parameters
- `cdef` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** a valid context definition object
- `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** optional configuration and plugin options
Returns **[Context](#context)** a new Context
#### toJSON
Returns JSON representation of the Context Definition
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** JSON ContextDefinition
#### toJS
Returns a plain javascript object representation of the current context
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** JavaScript object representation of the current context
#### setOption
Sets or creates a context.options.key value
##### Parameters
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** option.name
- `value` **any** option.value
Returns **[Context](#context)** Context
#### getOption
Get an option value
##### Parameters
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** option.name
- `defaultValue` **any?** optional defaultValue
Returns **any** option.value | defaultValue
#### has
Checks the current context for key
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** key to find
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the current context contains key
#### get
Returns the value of key from the current context
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** the property to find
- `defaultValue` **any?** optional defaultValue
Returns **any** key.value | defaultValue
#### isRemoved
True if the provided key will be removed on transform
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** the property to find
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the property found in the current context
#### isRedacted
True if the provided key will be redacted on transform
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** the property to find
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if property.redact = true
#### allowsAdditionalProperties
True if the context allows out-of-context values
#### isAllowed
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)**
#### mapKey
Returns the context name of key
##### Parameters
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
- `defaultValue` **any?**
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
#### mapKeys
Returns a new copy of object with the keys renamed by the active context (this)
##### Parameters
- `object` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
#### mapValue
Executes the current context for the key/value pair and returns the resulting value
##### Parameters
- `value` **any** the value
- `key` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** the key
- `object` **any?** (optional, default `{}`)
- `context` **any?**
#### map
Process object with the current context
non-destructive - always returns a new object
##### Parameters
- `object` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`)
- `initialValue` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the resulting state of object
#### transformEntry
Adds value to target.key.
if target.key does not exist it will be created.
if target.key is a scalar, it will be converted to an array and the new value will be pushed
if target.key is an array, the new value is pushed to target.key
if target.key is an object and value is an object, target.key will be recursively processed in the same manor
##### Parameters
- `target` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the object being transformed
- `value` **any** the value to add to target.key
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the key
- `object` **any** the original (source) object
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the next state of target
#### use
Adds a plugin to the context
##### Parameters
- `plugin` **[function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)**
- `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**
Returns **[Context](#context)** the new context with plugin installed
#### dispatch
Emits event to plug-in handlers
##### Parameters
- `event` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `data` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** (optional, default `{}`)
- `context` **any?**
Returns **[Context](#context)** the current context
#### fromYaml
Create a new context from a YAML string
##### Parameters
- `yaml` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
Returns **any**
#### mapEntry
Processes the key/value pair with the current context and returns the resulting key/value pair or void if the key is not allowed
##### Parameters
- `entry` **any**
Returns **any** [{string},{*}]
### isExpression
Check for jsonata expression syntax
#### Parameters
- `value` **any**
Returns **any** true if the value is a jsonata expression
### Events
Context events used by plugins
### getContext
Fetch context from path or object
#### Parameters
- `source` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))**
- `contextOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**
Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
### loadContext
#### Parameters
- `filePath` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `contextOptions` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**
Returns **any** @instance Context
### loadData
Load data from a path to a yaml, json, js, or href
or, if not a path, try to parse the string as yaml/json
#### Parameters
- `source` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>**
### fromFile
Loads a javascript object from a filepath
#### Parameters
- `target` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** source pathname or href
Returns **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** parsed json or yaml object
### isURL
Checks if value is a string starting with http
#### Parameters
- `value` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the string to test
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if string starts with 'http'
## License
MIT © [Dave Duran](mailto:dave@yodata.io)