reference.md

API Reference

• Bumpover
  • Rules
    • match
    • update
    • struct
    • childKey
  • Options
    • defaultValue
    • ignoreUnknown
    • childKey
    • beforeMatch
    • onUnmatch
    • serializer
    • deserializer
• bumper
  • bump
  • assert
  • test
• JSONBumpover
• XMLBumpover

Bumpover exposes the following API:

import {
  Bumpover,
  JSONBumpover,
  XMLBumpover
} from 'bumpover'

Bumpover

new Bumpover(rules: Array, options: Object) => bumper

The Bumpover class receives rules validating and converting data, and optional options to customize bumping behaviors.

Rules

const Rule = struct({
  match: 'function',
  update: 'function',
  struct: 'function?',
  childKey: 'string?'
})

const Rules = struct([Rule])

Each rule should provide its match and update props, with an optional struct.

match

(node: Node) => shouldUpdate: boolean

Decide if a rule should be applied to current node. For each node, only the first rule matching it can be applied. So it makes sense putting the "universal" rules back in the rules array as fallback.

update

(node: Node) => Promise<{ node: NewNode, action?: 'next'|'stop' }>

Update the selected node into new shape inside promise, resolve your new node in the node field, with an optional action specifying whether continue traversing children of current node. If not, children of current node will be preserved by default.

struct

Function

Optional struct validating NewNode.

childKey

string

Optional key string referencing children of a node matched by the rule. This will overwrite options.childKey.

Options

const Options = struct({
  defaultValue: 'any',
  ignoreUnknown: 'boolean',
  childKey: 'string',
  beforeMatch: 'function',
  onUnmatch: 'function',
  serializer: 'function',
  deserializer: 'function'
})

Following options are supported for bumping data.

defaultValue

Default value when bumper.bump resolves void data, null by default.

ignoreUnknown

Decide if current node should be ignored when no rule is matched, false by default.

childKey

Key string referencing children of a node. 'children' by default.

beforeMatch

Called before matching rules for current node. This handler does not affect subsequent traversing. (node) => {} by default.

onUnmatch

Called when no rule is found for current node and ignoreKnown === false. This handler does not affect subsequent traversing. (node) => {} by default.

Providing wrong childKey may result in weird data shape.

serializer

Function serializing JSON data into your data structure. (a) => a by default.

deserializer

Function parsing your data structure into JSON. (a) => a by default.

bumper

Object

Instance of Bumpover class.

bump

(input: any) => Promise<output: any>

Bump input data into output.

assert

(input: any, expected: any) => Promise

Compare whether input can be bumped into expected.

test

(input: any) => Promise

Test if input can be bumped without rejection.

XMLBumpover

Conform to same API as Bumpover, with its bump method receives and yields XML string.

JSONBumpover

Conform to same API as Bumpover, with deserializer and serializer replaced into JSON.parse and JSON.stringify.