@yodata/transform

declarative, composable JSON transformation utility.

Installation

> npm install --save @yodata/transform

Usage

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

Table of Contents

• fromString
  • Parameters
• compileContext
  • Parameters
• map
  • Parameters
• pathArray
  • Parameters
• Context
  • Parameters
  • parseContext
    • Parameters
  • extend
    • Parameters
  • toJSON
  • toJS
  • setOption
    • Parameters
  • getOption
    • Parameters
  • has
    • Parameters
  • get
    • Parameters
  • isRemoved
    • Parameters
  • isRedacted
    • Parameters
  • allowsAdditionalProperties
  • isAllowed
    • Parameters
  • mapKey
    • Parameters
  • mapKeys
    • Parameters
  • mapValue
    • Parameters
  • map
    • Parameters
  • transformEntry
    • Parameters
  • use
    • Parameters
  • dispatch
    • Parameters
  • fromYaml
    • Parameters
  • mapEntry
    • Parameters
• isExpression
  • Parameters
• Events
• getContext
  • Parameters
• loadContext
  • Parameters
• loadData
  • Parameters
• fromFile
  • Parameters
• isURL
  • Parameters

fromString

Attempt to parse a string as yaml or json

Parameters

• value string the value to parse
• options 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
• contextOptions object?

Returns Promise<function>

map

Parameters

• object

pathArray

Converts a path expression a.b.c to a path array [a,b,c]

Parameters

• key (string | Array<string>) the path or path array

Returns Array<string> pathArray

Context

Creates a new Context

Parameters

• contextDefinition object? a valid ContextDefinition object (optional, default {})
• options object? configuration options (optional, default {})

parseContext

Parse & normalize a context definition JSON string

Parameters

• contextDefinition object a valid ContextDefinition

Returns object normalized ContextDefinition document

extend

Creates a new context from the current + the provided context definition document.

Parameters

• cdef object a valid context definition object
• options object? optional configuration and plugin options

Returns Context a new Context

toJSON

Returns JSON representation of the Context Definition

Returns string JSON ContextDefinition

toJS

Returns a plain javascript object representation of the current context

Returns object JavaScript object representation of the current context

setOption

Sets or creates a context.options.key value

Parameters

• key string option.name
• value any option.value

Returns Context Context

getOption

Get an option value

Parameters

• key string option.name
• defaultValue any? optional defaultValue

Returns any option.value | defaultValue

has

Checks the current context for key

Parameters

• key (string | Array<string>) key to find

Returns boolean true if the current context contains key

get

Returns the value of key from the current context

Parameters

• key (string | Array<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 | Array<string>) the property to find

Returns boolean true if the property found in the current context

isRedacted

True if the provided key will be redacted on transform

Parameters

• key (string | Array<string>) the property to find

Returns boolean true if property.redact = true

allowsAdditionalProperties

True if the context allows out-of-context values

isAllowed

Parameters

• key (string | Array<string>)

Returns boolean

mapKey

Returns the context name of key

Parameters

• key (string | Array<string>)
• defaultValue any?

Returns string

mapKeys

Returns a new copy of object with the keys renamed by the active context (this)

Parameters

• object object

Returns object

mapValue

Executes the current context for the key/value pair and returns the resulting value

Parameters

• value any the value
• key (string | Array<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 (optional, default {})
• initialValue object?

Returns 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 the object being transformed
• value any the value to add to target.key
• key string the key
• object any the original (source) object

Returns object the next state of target

use

Adds a plugin to the context

Parameters

• plugin function
• options object?

Returns Context the new context with plugin installed

dispatch

Emits event to plug-in handlers

Parameters

• event string
• data object? (optional, default {})
• context any?

Returns Context the current context

fromYaml

Create a new context from a YAML string

Parameters

• yaml 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 | object)
• contextOptions object?

Returns Promise

loadContext

Parameters

• filePath string
• contextOptions 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

Returns Promise<object>

fromFile

Loads a javascript object from a filepath

Parameters

• target string source pathname or href

Returns object parsed json or yaml object

isURL

Checks if value is a string starting with http

Parameters

• value string the string to test

Returns boolean true if string starts with 'http'

License

MIT © Dave Duran