data-point v3.5.0

DataPoint

JavaScript Utility for collecting, processing and transforming data.

DataPoint helps you reason with and streamline your data processing layer. With it you can collect, process, and transform data from multiple sources, and deliver the output in a tailored format to your end consumer.

Prerequisites

Node v8 LTS or higher

Installing

npm install --save data-point

Table of Contents

• Getting Started
  • Hello World Example
  • Fetching remote services
• API
  • create
  • createReducer
  • resolve
  • transform
  • addEntities
  • addValue
• Accumulator
• Reducers
  • function
  • object
  • entity
  • entity-id
  • list
• Reducer Helpers
  • assign
  • map
  • filter
  • find
  • constant
  • parallel
  • withDefault
• Entities
  • Instance Entity
  • Registered Entity
  • Entity Base API
  • Entity type check
  • Entity types
    • Reducer
    • Model
    • Entry
    • Request
    • Hash
    • Collection
    • Control
    • Schema
  • Entity ComposeReducer
  • Extending Entities
  • Global Entity Options
• Middleware
  • dataPoint.use
• Custom Entity Types
• Tracing DataPoint calls
• Integrations
• Patterns and Best Practices
• Contributing
• License

Getting Started

DataPoint provides the following mechanisms for transforming data:

• Reducers - these are the simplest transformations; think of them as DataPoint "primitives"

• Entities - these are more complex transformations that are defined using one or more reducers

• Middleware - middleware functions give the user more control when resolving entities; they're useful to implement caching and other metatasks

The following examples demonstrate some of these concepts. For detailed API documentation, you can jump into the DataPoint.create section and move from there.

Additionally, there is a Hello World YouTube tutorial that explains the basics of DataPoint.

Hello World Example

Trivial example of transforming a given input with a function reducer.

const DataPoint = require('data-point')
// create DataPoint instance
const dataPoint = DataPoint.create()

// function reducer that concatenates
// accumulator.value with 'World'
const reducer = (input) => {
  return input + ' World'
}

// applies reducer to input
dataPoint
  .resolve(reducer, 'Hello')
  .then((output) => {
    // 'Hello World'
    console.log(output) 
  })

Example at: examples/hello-world.js

Fetching remote services

Based on an initial feed, fetch and aggregate results from multiple remote services.

Using the amazing swapi.co service, the example below gets information about a planet and the residents of that planet.

const DataPoint = require('data-point')

// create DataPoint instance
const dataPoint = DataPoint.create()

const {
  Request,
  Model,
  Schema,
  map
} = DataPoint

// schema to verify data input
const PlanetSchema = Schema('PlanetSchema', {
  schema: {
    type: 'object',
    properties: {
      planetId: {
        $id: '/properties/planet',
        type: 'integer'
      }
    }
  }
})

// remote service request
const PlanetRequest = Request('Planet', {
  // {value.planetId} injects the
  // value from the accumulator
  // creates: https://swapi.co/api/planets/1/
  url: 'https://swapi.co/api/planets/{value.planetId}'
})

const ResidentRequest = Request('Resident', {
  // check input is string
  inputType: 'string',
  url: '{value}'
})

// model entity to resolve a Planet
const ResidentModel = Model('Resident', {
  inputType: 'string',
  value: [
    // hit request:Resident
    ResidentRequest,
    // extract data
    {
      name: '$name',
      gender: '$gender',
      birthYear: '$birth_year'
    }
  ]
})

// model entity to resolve a Planet
const PlanetModel = Model('Planet', {
  inputType: PlanetSchema,
  value: [
    // hit request:Planet data source
    PlanetRequest,
    // map result to an object reducer
    {
      // map name key
      name: '$name',
      population: '$population',
      // residents is an array of urls
      // eg. https://swapi.co/api/people/1/
      // where each url gets mapped
      // to a model:Resident
      residents: ['$residents', map(ResidentModel)]
    }
  ]
})

const input = {
  planetId: 1
}

dataPoint.resolve(PlanetModel, input)
  .then((output) => {
    console.log(output)
    /*
    output -> 
    { 
      name: 'Tatooine',
      population: 200000,
      residents:
      [ 
        { name: 'Luke Skywalker', gender: 'male', birthYear: '19BBY' },
        { name: 'C-3PO', gender: 'n/a', birthYear: '112BBY' },
        { name: 'Darth Vader', gender: 'male', birthYear: '41.9BBY' },
        ...
      ] 
    }
    */
  })

Example at: examples/full-example-instances.js

API

create

Static method that creates a DataPoint instance.

SYNOPSIS

DataPoint.create([options])

Arguments

The following table describes the properties of the options argument.

RETURNS

DataPoint instance.

DataPoint.create example

createReducer

Static method that creates a reducer, which can be executed with resolve or transform.

SYNOPSIS

DataPoint.createReducer(source:*, [options:Object]):Reducer

ARGUMENTS

Options

resolve

Execute a Reducer against an input value. This function supports currying and will be executed when at least the first 2 parameters are provided.

SYNOPSIS

dataPoint.resolve(reducer:Reducer, input:*, options:Object):Promise(output:*)

This method returns a Promise with the final output value.

ARGUMENTS

EXAMPLES:

• Hello World example.
• With options example.

transform

This method is similar to dataPoint.resolve. The differences between the methods are:

• .transform() accepts an optional third parameter for node style callback.
• .transform() returns a Promise that resolves to the full Accumulator object instead of accumulator.value. This may come in handy if you want to inspect other values from the transformation.

SYNOPSIS

// as promise
dataPoint.transform(reducer:Reducer, input:*, options:Object):Promise(acc:*)
// as nodejs callback function
dataPoint.transform(reducer:Reducer, input:*, options:Object, done:Function)

This method will return a Promise if done is omitted.

ARGUMENTS

transform options

The following table describes the properties of the options argument.

resolveFromAccumulator

Execute a Reducer from a provided Accumulator. This function will attempt at resolving a reducer providing an already constructed Accumulator Object. It will take the value provided in the Accumulator object to use as the input.

SYNOPSIS

dataPoint.resolveFromAccumulator(reducer:Reducer, acc:Accumulator):Promise(acc:Accumulator)

This method returns a Promise with the final output value.

ARGUMENTS

addEntities

This method adds new entities to a DataPoint instance.

SYNOPSIS

When defining new entities, <EntityType> must refer to either a built-in type like 'model' or a custom entity type. <EntityId> should be unique for each type; for example, model:foo and hash:foo can both use the foo ID, but an error is thrown if model:foo is defined twice.

dataPoint.addEntities({
  '<EntityType>:<EntityId>': { ... },
  '<EntityType>:<EntityId>': { ... },
  ...
})

OPTIONS

addValue

Stores any value to be accessible via Accumulator.values. This object can also be set by passing a values property to DataPoint.create.

SYNOPSIS

dataPoint.addValue(objectPath, value)

ARGUMENTS

Accumulator

This object is passed to reducers and middleware callbacks; it has contextual information about the current transformation or middleware that's being resolved.

The accumulator.value property is the current input data. This property should be treated as a read-only immutable object. This helps ensure that your reducers are pure functions that produce no side effects. If the value is an object, use it as your initial source for creating a new object.

Properties exposed:

Reducers

Reducers are used to transform values asynchronously. DataPoint supports the following reducer types:

1. path
2. function
3. object
4. entity
5. entity-id
6. list

Path Reducer

A path reducer is a string that extracts a path from the current Accumulator value (which must be an Object). It uses lodash's _.get behind the scenes.

SYNOPSIS

'$[.|..|<path>]'

OPTIONS

Root path $

EXAMPLES:

const DataPoint = require('data-point')
const dataPoint = DataPoint.create()

const input = {
  a: {
    b: [
      'Hello World'
    ]
  }
}

dataPoint
  .resolve('$', input)
  .then((output) => {
    assert.strictEqual(output, input)
  })

Access accumulator reference

const DataPoint = require('data-point')
const dataPoint = DataPoint.create()

const input = {
  a: {
    b: [
      'Hello World'
    ]
  }
}

dataPoint
  .resolve('$..value', input)
  .then(output => {
    assert.strictEqual(output input)
  })

Object Path

Example at: examples/reducer-path.js

Object Map

Function Reducer

A function reducer allows you to use a function to apply a transformation. There are several ways to define a function reducer:

• Synchronous function that returns new value
• Asynchronous function that returns a Promise
• Asynchronous function with callback parameter
• Asynchronous function through async/await (only if your environment supports it)

IMPORTANT: Be careful with the parameters passed to your function reducer; DataPoint relies on the number of arguments to detect the type of function reducer it should expect.

Returning a value

The returned value is used as the new value of the transformation.

SYNOPSIS

const name = (input:*, acc:Accumulator) => {
  return newValue
}

Reducer's arguments

Example at: examples/reducer-function-sync.js

Returning a Promise

If you return a Promise its resolution will be used as the new value of the transformation. Use this pattern to resolve asynchronous logic inside your reducer.

SYNOPSIS

const name = (input:*, acc:Accumulator) => {
  return Promise.resolve(newValue)
}

Reducer's arguments

Example at: examples/reducer-function-promise.js

With a callback parameter

Accepting a third parameter as a callback allows you to execute an asynchronous block of code. This should be an error-first, Node.js style callback with the arguments (error, value), where value will be the value passed to the next transform; this value becomes the new value of the transformation.

SYNOPSIS

const name = (input:*, acc:Accumulator, next:function) => {
  next(error:Error, newValue:*)
}

Reducer's arguments

Example at: examples/reducer-function-with-callback.js

Example at: examples/reducer-function-error.js

Object Reducer

These are plain objects where the value of each key is a Reducer. They're used to aggregate data or transform objects. You can add constants with the constant reducer helper, which is more performant than using a function reducer:

const { constant } = require('data-point')

const objectReducer = {
  // in this case, x and y both resolve to 42, but DataPoint
  // can optimize the resolution of the constant value
  x: () => 42,
  y: constant(42)
}

Each of the reducers, including the nested ones, are resolved against the same accumulator value. This means that input objects can be rearranged at any level:

Each of the reducers might contain more object reducers (which might contain other reducers, and so on). Notice how the output changes based on the position of the object reducers in the two expressions:

An empty object reducer will resolve to an empty object:

const reducer = {}

const input = { a: 1 }

dataPoint.resolve(reducer, input) // => {}

Entity Reducer

An entity instance reducer is used to apply a given entity with to the current Accumulator.

See the Entities section for information about the supported entity types.

OPTIONS

const {
  Model,
  Request
} = require('data-point')

const PersonRequest = Request('PersonRequest', {
  url: 'https://swapi.co/api/people/{value}'
})

const PersonModel = Model('PersonModel', {
  value: {
    name: '$name',
    birthYear: '$birth_year'
  }
})

dataPoint
  .resolve([PersonRequest, PersonModel], 1)
  .then((output) => {
    assert.deepStrictEqual(output, {
      name: 'Luke Skywalker',
      birthYear: '19BBY'
    })
  })

Example at: examples/reducer-entity-instance.js

Entity By Id Reducer

An entity reducer is used to execute an entity with the current Accumulator as the input.

Appending [] to an entity reducer will map the given entity to each element of an input array. If the current accumulator value is not an array, the reducer will return undefined.

See the Entities section for information about the supported entity types.

SYNOPSIS

'[?]<EntityType>:<EntityId>[[]]'

OPTIONS

const input = {
  a: {
    b: 'Hello World'
  }
}

const toUpperCase = (input) => {
  return input.toUpperCase()
}

dataPoint.addEntities({
  'reducer:getGreeting': '$a.b',
  'reducer:toUpperCase': toUpperCase,
})

// resolve `reducer:getGreeting`,
// pipe value to `reducer:toUpperCase`
dataPoint
  .resolve(['reducer:getGreeting | reducer:toUpperCase'], input)
  .then((output) => {
    assert.strictEqual(output, 'HELLO WORLD')
  })

const input = {
  a: [
    'Hello World',
    'Hello Laia',
    'Hello Darek',
    'Hello Italy',
  ]
}

const toUpperCase = (input) => {
  return input.toUpperCase()
}

dataPoint.addEntities({
  'reducer:toUpperCase': toUpperCase
})

dataPoint
  .resolve(['$a | reducer:toUpperCase[]'], input)
  .then((output) => {
    assert.strictEqual(output[0], 'HELLO WORLD')
    assert.strictEqual(output[1], 'HELLO LAIA')
    assert.strictEqual(output[2], 'HELLO DAREK')
    assert.strictEqual(output[3], 'HELLO ITALY')
  })

List Reducer

A list reducer is an array of reducers where the result of each reducer becomes the input to the next reducer. The reducers are executed serially and asynchronously. It's possible for a list reducer to contain other list reducers.

IMPORTANT: an empty list reducer will resolve to undefined. This mirrors the behavior of empty functions.

const reducer = []

const input = 'INPUT'

dataPoint.resolve(reducer, input) // => undefined

Conditionally execute an entity

Only execute an entity if the accumulator value is not equal to false, null or undefined. If the conditional is not met, the entity will not be executed and the value will remain the same.

const people = [
  {
    name: 'Luke Skywalker',
    swapiId: '1'
  },
  {
    name: 'Yoda',
    swapiId: null
  }
]

dataPoint.addEntities({
  'request:getPerson': {
    url: 'https://swapi.co/api/people/{value}'
  },
  'reducer:getPerson': {
    name: '$name',
    // request:getPerson will only
    // be executed if swapiId is
    // not false, null or undefined
    birthYear: '$swapiId | ?request:getPerson | $birth_year'
  }
})

dataPoint
  .resolve('reducer:getPerson[]', people)
  .then((output) => {
    assert.deepStrictEqual(output, [
      {
        name: 'Luke Skywalker',
        birthYear: '19BBY'
      },
      {
        name: 'Yoda',
        birthYear: undefined
      }
    ])
  })

Example at: examples/reducer-conditional-operator.js

Reducer Helpers

Reducer helpers are factory functions for creating reducers. They're accessed through the DataPoint Object:

const {
  assign,
  constant,
  filter,
  find,
  map,
  parallel,
  withDefault
} = require('data-point')

assign

The assign reducer creates a new Object by resolving the provided Reducer and merging the result with the current accumulator value. It uses Object.assign internally.

SYNOPSIS

assign(reducer:Reducer):Object

Reducer's arguments

EXAMPLE:

const input = {
  a: 1
}

// merges the object reducer with
// accumulator.value
const reducer = DataPoint.assign({
  c: '$b.c'
})

dataPoint
  .resolve(reducer, input)
  .then(output => {
    /*
     output --> {
      a: 1,
      b: {
        c: 2
      },
      c: 2
    }
    */
  })

Example at: examples/reducer-helper-assign.js

map

The map reducer creates a new array with the results of applying the provided Reducer to every element in the input array.

SYNOPSIS

map(reducer:Reducer):Array

Reducer's arguments

EXAMPLE:

const input = [{
  a: 1
}, {
  a: 2
}]

// get path `a` then multiply by 2
const reducer = DataPoint.map(
  ['$a', (input) => input * 2]
)

dataPoint
  .resolve(reducer, input)
  .then(output => {
    // output -> [2, 4]
  })

Example at: examples/reducer-helper-map.js

filter

The filter reducer creates a new array with elements that resolve as truthy when passed to the given Reducer.

SYNOPSIS

filter(reducer:Reducer):Array

Reducer's arguments

EXAMPLE:

const input = [{ a: 1 }, { a: 2 }]

// filters array elements that are not
// truthy for the given list reducer
const reducer = DataPoint.filter(
  ['$a', (input) => input > 1]
)

dataPoint
  .resolve(reducer, input) 
  .then(output => {
    // output ->  [{ a: 2 }]
  })  

Example at: examples/reducer-helper-filter.js

find

The find reducer returns the first element of an array that resolves to truthy when passed through the provided Reducer. It returns undefined if no match is found.

SYNOPSIS

find(reducer:Reducer):*

Reducer's arguments

EXAMPLE:

const input = [{ a: 1 }, { b: 2 }]

// the $b reducer is truthy for the
// second element in the array
const reducer = DataPoint.find('$b')

dataPoint
  .resolve(reducer, input) 
  .then(output => {
    // output -> { b: 2 }
  })

Example at: examples/reducer-helper-find.js

constant

The constant reducer always returns the given value. If a reducer is passed it will not be evaluated. This is primarily meant to be used in object reducers.

SYNOPSIS

constant(value:*):*

Reducer's arguments

EXAMPLE:

const input = {
  a: 1,
  b: 2
}

const reducer = {
  a: '$a',
  b: DataPoint.constant({
    a: '$a',
    b: 3
  })
}

dataPoint
  .resolve(reducer, input) 
  .then(output => {
    // {
    //   a: 1,
    //   b: {
    //     a: '$a',
    //     b: 3
    //   }
    // }
    }
  })

const input = {
  b: 1
}

// object reducer that contains a path reducer ('$a')
let reducer = {
  a: '$b'
}

dataPoint.resolve(reducer, input) // => { a: 1 }

// both the object and the path will be treated as
// constants instead of being used to create reducers
reducer = DataPoint.constant({
  a: '$b'
})

dataPoint.resolve(reducer, input) // => { a: '$b' }

parallel

This resolves an array of reducers. The output is a new array where each element is the output of a reducer; this contrasts with list reducers, which return the output from the last reducer in the array.

SYNOPSIS

parallel(reducers:Array<Reducer>):Array

Reducer's arguments

EXAMPLE:

const reducer = DataPoint.parallel([
  '$a',
  ['$b', (input) => input + 2] // list reducer
])

const input = {
  a: 1,
  b: 2
}

dataPoint.resolve(reducer, input) // => [1, 4]

withDefault

The withDefault reducer adds a default value to any reducer type. If the reducer resolves to null, undefined, NaN, or '', the default is returned instead.

SYNOPSIS

withDefault(source:*, value:*):*

Reducer's arguments

The default value is not cloned before it's returned, so it's good practice to wrap any Objects in a function.

EXAMPLE:

const input = {
  a: undefined
}

// adds a default to a path reducer
const r1 = DataPoint.withDefault('$a', 50)

dataPoint.resolve(r1, input) // => 50

// passing a function is useful when the default value is
// an object, because it returns a new object every time
const r2 = withDefault('$a', () => {
  return { b: 1 }
})

dataPoint.resolve(r2, input) // => { b: 1 }

Entities

Entities are used to transform data by composing multiple reducers, they can be created as non-registered or registered entities.

• Instance entities - are entity objects created directly with an Entity Factory, they are meant to be used as a entity reducer.
• Registered entities - are entity objects which are registered and cached in a DataPoint instance, they are meant to be used as a registered entity reducer.

Registered entities may be added to DataPoint in two different ways:

1. With the DataPoint.create method (as explained in the setup examples)
2. With the dataPoint.addEntities instance method

See built-in entities for information on what each entity does.

Instance Entity

Entities can be created from these factory functions:

const {
  Entry,
  Model,
  Reducer,
  Collection,
  Hash,
  Request,
  Control,
  Schema
} = require('data-point')

SYNOPSIS

Each factory has the following signature:

Factory(name:String, spec:Object):EntityInstance

ARGUMENTS

Example

const DataPoint = require('data-point')
const { Model } = DataPoint

const dataPoint = DataPoint.create()

const HelloWorld = Model('HelloWorld', {
  value: input => ({
    hello: 'world'
  })
})

// to reference it we use the actual entity instance
dataPoint.resolve(HelloWorld, {})
  .then(value => {
    console.assert(value, {
      hello: 'world'
    })
  })

Registered Entity

You may register an entity through DataPoint.create or dataPoint.addEntities.

Example

const DataPoint = require('data-point')

dataPoint = DataPoint.create({
  entities: {
    'model:HelloWorld', {
      value: input => ({
        hello: 'world'
      } 
    }
  }
})

// to reference it we use a string with its registered id
dataPoint.resolve('model:HelloWorld', {})
  .then(value => {
    console.assert(value, {
      hello: 'world'
    })
  })

Entity Base API

All entities share a common API (except for Reducer).

{
  // type checks the entity's input
  inputType: String | Reducer,

  // executes --before-- any modifier
  before: Reducer,
  
  // executes --after-- any modifier
  after: Reducer,
  
  // type checks the entity's output
  outputType: String | Reducer,

  // executes in case there is an error at any
  // point of the entire transformation
  error: Reducer,
  
  // this object allows you to store and eventually
  // access it at any given time on any reducer
  params: Object
}

Properties exposed:

Entity type check

You can use inputType and outputType for type checking an entity's input and output values. Type checking does not mutate the result.

Built in type checks:

To use built-in type checks, you may set the value of inputType or outputType to: 'string', 'number', 'boolean', 'function', 'error', 'array', or 'object'.

This example uses a Model Entity, for information on what a model is please go to the Model Entity section.

const dataPoint = DataPoint.create()

dataPoint.addEntities({
  'model:getName': {
    value: '$name',
    outputType: 'string'
  }
})

const input = {
  name: 'DataPoint'
}

dataPoint.resolve('model:getName', input)
  .then(output => {
    // output -> 'DataPoint'
  })

Custom type checking:

You may also type check with a Schema Entity, or by creating a Reducer with the createTypeCheckReducer function.

SYNOPSIS

DataPoint.createTypeCheckReducer(typeCheckFunction, [expectedType])

ARGUMENTS

  const DataPoint = require('data-point')

  const { createTypeCheckReducer } = DataPoint

  const isNonEmptyArray = input => Array.isArray(input) && input.length > 0

  const dataPoint = DataPoint.create({
    entities: {
      'model:get-first-item': {
        inputType: createTypeCheckReducer(isNonEmptyArray, 'non-empty-array'),
        value: input => input[0]
      }
    }
  })

In this example we are using a Schema Entity to check the inputType.

const dataPoint = DataPoint.create()

dataPoint.addEntities({
  'model:getName': {
    // assume schema:RepoSchema 
    // exists and checks of the
    // existence of name
    inputType: 'schema:RepoSchema',
    value: '$name'
  }
})

const input = {
  name: 'DataPoint'
}

dataPoint.resolve('model:getName', input)
  .then(output => {
    // output -> DataPoint
  })

Entity Types

DataPoint comes with the following built-in entity types:

• Reducer / Transform
• Model
• Entry
• Request
• Hash
• Collection
• Control
• Schema

Reducer

A Reducer entity is a 'snippet' that you can re-use in other entities. It does not expose the before/after/error/params API that other entities have.

IMPORTANT: Reducer Entities do not support extension.

SYNOPSIS

dataPoint.addEntities({
  'reducer:<entityId>': Reducer
})

For backwards compatibility, the keyword transform can be used in place of reducer:

dataPoint.addEntities({
  'reducer:<entityId>': Reducer
})

Model

A Model entity is a generic entity that provides the base methods.

SYNOPSIS

dataPoint.addEntities({
  'model:<entityId>': {
    inputType: String | Reducer,
    before: Reducer,
    value: Reducer,
    after: Reducer,
    outputType: String | Reducer,
    error: Reducer,
    params: Object
  }
})

Properties exposed:

Model.value

Example at: examples/entity-model-basic.js

Model.before

Example at: examples/entity-model-before.js

Model.after

Model.error

Any error that happens within the scope of the Entity can be handled by the error transform. To respect the API, error reducers have the same API.

Error handling

Passing a value as the second argument will stop the propagation of the error.

EXAMPLES:

dataPoint.addEntities({
  'model:getArray': {
    // points to a NON Array value
    value: '$a.b',
    outputType: 'isArray',
    error: (error) => {
      // prints out the error
      // message generated by
      // isArray type check
      console.log(error.message)

      console.log('Value is invalid, resolving to empty array')

      // passing a value will stop
      // the propagation of the error
      return []
    }
  }
})

const input = {
  a: {
    b: 'foo'
  }
}

dataPoint
  .resolve('model:getArray', input)
  .then((output) => {
    assert.deepStrictEqual(output, [])
  })

Example at: examples/entity-model-error-handled.js

dataPoint.addEntities({ 'model:getArray': { value: '$a', outputType: 'isArray', error: logError } })

const input = { a: { b: 'foo' } }

dataPoint .resolve('model:getArray', input) .catch((error) => { console.log(error.toString()) })

</details>


Example at: [examples/entity-model-error-rethrow.js](examples/entity-model-error-rethrow.js)

#### Model.params

The params object is used to pass custom data to your entity. This Object is exposed as a property of the [Accumulator](#accumulator) Object. Which can be accessed via a [function reducer](#function-reducer), as well as through a [path reducer](#path-reducer) expression.

<details>
<summary>On a Function Reducer</summary>

```js
const multiplyValue = (input, acc) => {
  return input * acc.params.multiplier
}

dataPoint.addEntities({
  'model:multiply': {
    value: multiplyValue,
    params: {
      multiplier: 100
    }
  }
})

dataPoint
  .resolve('model:multiply', 200)
  .then((output) => {
    assert.deepStrictEqual(output, 20000)
  })

Entry

This entity is very similar to the Model entity. Its main difference is that this entity will default to an empty object { } as its initial value if none was passed. As a best practice, use it as your starting point, and use it to call more complex entities.

SYNOPSIS

dataPoint.addEntities({
  'entry:<entityId>': {
    inputType: String | Reducer,
    before: Reducer,
    value: Reducer,
    after: Reducer,
    outputType: String | Reducer,
    error: Reducer,
    params: Object
  }
})

Properties exposed:

Request

Requests a remote source, using request-promise behind the scenes. The features supported by request-promise are exposed/supported by Request entity.

SYNOPSIS

dataPoint.addEntities({
  'request:<entityId>': {
    inputType: String | Reducer,
    before: Reducer,
    value: Reducer,
    url: StringTemplate,
    options: Reducer,
    after: Reducer,
    outputType: String | Reducer,
    error: Reducer,
    params: Object
  }
})

Properties exposed:

Request.url

Sets the url to be requested.

NOTE: When Request.url is not defined it will use the current Accumulator.value (if the value is of type string) as the Request's url.

dataPoint.resolve('request:getLuke', {}) .then(output => { / output -> { name: 'Luke Skywalker', height: '172', ... } / })

</details>


Example at: [examples/entity-request-basic.js](examples/entity-request-basic.js)

#### Request.url as StringTemplate

StringTemplate is a string that supports a **minimal** templating system. You may inject any value into the string by enclosing it within `{ObjectPath}` curly braces. **The context of the string is the Request's [Accumulator](#accumulator) Object**, meaning you have access to any property within it. 

Using `acc.value` property to make the url dynamic:

<details>
<summary>`acc.value` Example</summary>

```js
dataPoint.addEntities({
  'request:getLuke': {
    // inject the acc.value.personId
    url: 'https://swapi.co/api/people/{value.personId}/'
  }
})

const input = {
  personId: 1
}

dataPoint.resolve('request:getLuke', input)
  .then(output => {
    /*
    output -> 
    {
      name: 'Luke Skywalker',
      height: '172',
      ...
    }
    */
  })

Example at: examples/entity-request-string-template.js

Using acc.locals property to make the url dynamic:

const options = { locals: { personId: 1 } }

dataPoint.resolve('request:getLuke', {}, options) .then(output => { / output -> { name: 'Luke Skywalker', height: '172', ... } / })

</details>

Example at: [examples/entity-request-options-locals.js](examples/entity-request-options-locals.js)

For more information on acc.locals: [Transform Options](#transform-options) and [Accumulator](#accumulator) Objects.

<a name="options-with-constants" >Using constants in the options reducer:</a>

<details>
<summary>constants example</summary>

```js
const DataPoint = require('data-point')
const dataPoint = DataPoint.create()

dataPoint.addEntities({
  'request:searchPeople': {
    url: 'https://swapi.co/api/people',
    // options is a Reducer, but values
    // at any level can be wrapped as
    // constants (or just wrap the whole
    // object if all the values are static)
    options: {
      'content-type': DataPoint.constant('application/json')
      qs: {
        // get path `searchTerm` from input
        // to dataPoint.resolve
        search: '$searchTerm'
      }
    }
  }
})

const input = {
  searchTerm: 'r2'
}

// the second parameter to transform is the input value
dataPoint
  .resolve('request:searchPeople', input)
  .then(output => {
    assert.strictEqual(output.results[0].name, 'R2-D2')
  })

Example at: examples/entity-request-options.js

For more examples of request entities, see the Examples, the Integration Examples, and the unit tests: Request Definitions.

Inspecting Request Entities

You may inspect a Request entity through the params.inspect property.

note: At the moment this feature is only available on Request entity, PRs are welcome.

SYNOPSIS

dataPoint.addEntities({
  'request:<entityId>': {
    params: {
      inspect: Boolean|Function
    }
  }
})

Boolean

If params.inspect is true, it will output the entity's information to the console.

Function

If params.inspect is a function, it will be called twice: once before the request is made, and once when the request is resolved. It should have the signature (accumulator: Object, data: Object).

The inspect function is first called just before initiating the request. The first argument is the accumulator, and the second is a data object with these properties:

{
  type: 'request',
  // unique ID that is shared with the 'response' object
  debugId: Number,
  // ex: 'GET'
  method: String,
  // fully-formed URI
  uri: String,
  // the value of request.body (or undefined)
  [body]: String
}

It's then called when the request succeeds or fails. The data object will have a type property of either 'response' or 'error'. The debugId can be used to match the response with the corresponding request.

{
  type: 'response|error',
  // unique ID that is shared with the 'request' object
  debugId: Number,
  // http status code
  statusCode: Number,
}

Hash

A Hash entity transforms a Hash like data structure. It enables you to manipulate the keys within a Hash.

To prevent unexpected results, a Hash can only return Plain Objects, which are objects created by the Object constructor. If a hash resolves to a different type, it will throw an error. This type check occurs before the value is passed to the (optional) outputType reducer.

SYNOPSIS

dataPoint.addEntities({
  'hash:<entityId>': {
    inputType: String | Reducer,
    before: Reducer,
    value: Reducer,
    mapKeys: TransformMap,
    omitKeys: String[],
    pickKeys: String[],
    addKeys: TransformMap,
    addValues: Object,
    compose: ComposeReducer[],
    after: Reducer,
    outputType: String | Reducer,
    error: Reducer,
    params: Object,
  }
})

Properties exposed:

Hash entities expose a set of optional reducers: mapKeys, omitKeys, pickKeys, addKeys, and addValues. When using more than one of these reducers, they should be defined through the compose property.

Hash.value

Example at: examples/entity-hash-context.js

Hash.mapKeys

Maps to a new set of key/value pairs through a object reducer, where each value is a Reducer.

Going back to our GitHub API examples, let's map some keys from the result of a request:

const _ = require('lodash')

dataPoint.addEntities({
  'hash:mapKeys': {
    mapKeys: {
      // map to acc.value.name
      name: '$name',
      // uses a list reducer to
      // map to acc.value.name
      // and generate a string with
      // a function reducer
      url: [
        '$name',
        input => {
          return `https://github.com/ViacomInc/${_.kebabCase(input)}`
        }
      ]
    }
  }
})

const input = {
  name: 'DataPoint'
}

dataPoint.resolve('hash:mapKeys', input).then(output => {
  assert.deepStrictEqual(output, {
    name: 'DataPoint',
    url: 'https://github.com/ViacomInc/data-point'
  })
})

Example at: examples/entity-hash-mapKeys.js

Hash.addKeys

Adds keys to the current Hash value. If an added key already exists, it will be overridden.

Hash.addKeys is very similar to Hash.mapKeys, but the difference is that mapKeys will ONLY map the keys you give it, whereas addKeys will ADD/APPEND new keys to your existing acc.value. You may think of addKeys as an extend operation.

const input = { name: 'DataPoint' }

dataPoint.resolve('hash:addKeys', input).then(output => { assert.deepStrictEqual(output, { name: 'DataPoint', nameLowerCase: 'datapoint', url: 'https://github.com/ViacomInc/data-point' }) })

</details>


Example at: [examples/entity-hash-addKeys.js](examples/entity-hash-addKeys.js)

#### Hash.pickKeys

Picks a list of keys from the current Hash value.

The next example is similar to the previous example. However, instead of mapping key/value pairs, this example just picks some of the keys.

<details>
<summary>Hash.pickKeys Example</summary>

```js
dataPoint.addEntities({
  'hash:pickKeys': {
    pickKeys: ['url']
  }
})

const input = {
  name: 'DataPoint',
  url: 'https://github.com/ViacomInc/data-point'
}

dataPoint.resolve('hash:pickKeys', input).then(output => {
  // notice how name is no longer 
  // in the object
  assert.deepStrictEqual(output, {
    url: 'https://github.com/ViacomInc/data-point'
  })
})

Example at: examples/entity-hash-pickKeys.js

Hash.omitKeys

Omits keys from the Hash value.

This example will only omit some keys, and let the rest pass through:

// notice how name is no longer in the object const expectedResult = { url: 'https://github.com/ViacomInc/data-point' }

const input = { name: 'DataPoint', url: 'https://github.com/ViacomInc/data-point' }

dataPoint.resolve('hash:omitKeys', input).then(output => { assert.deepStrictEqual(output, expectedResult) })

</details>

Example at: [examples/entity-hash-omitKeys.js](examples/entity-hash-omitKeys.js)

##