@powell0/transformalizer v1.1.4

transformalizer

a bare bones node module for transforming raw data into JSON API v1.0 compliant payloads.

this module:

• makes no assumption regarding the shape of your data or the datastores/sdks used.
• supports the full JSON API v1.0 specification
• supports dynamic transformations, links, and meta at all levels of a document

Installing

$ npm install --save transformalizer

Getting Started

Create a new transformalizer and register schemas

import createTransformalizer from 'transformalizer';

// create a new transformalizer
const transformalizer = createTransformalizer();

// register a schema
transformalizer.register({
  name: 'article',
  schema: { /* see below for schema details and examples */ },
});

// transform raw data into a valid JSON API v1.0 document
const document = transformalizer.transform({ name: 'article', source });
console.log(JSON.stringify(document));

Examples

See examples in the examples folder of this repository.

• basic

API

createTransformalizer(options) => transformalizer

Create a new transformalizer object

Parameters

Examples

const createTransformalizer = require('transformalizer')

const transformalizer = createTransformalizer()

transformalizer.register(params)

Register a new document schema.

Parameters

Examples

transformalizer.register({
  name: 'blog-post',
  schema: {
    // ..
  }
})

transformalizer.transform(params) => Object

Build a json api document using the schema with specified name and with the given source data.

Parameters

Examples

const blogPost = { title: 'Hello, World!', body: 'To be continued...', createdAt: new Date() }
const document = transformalizer.transform({ name: 'blog-post', source: blogPost })

transformalizer.untransform(params) => Object

Reconstruct data objects from a json api document.

Parameters

Examples

const payload = { data: { id: '1', type: 'blog-post', attributes: { title: 'Hello, World!', body: 'To be continued...', createdAt: '2017-09-19T13:10:00' } } }
const data = transformalizer.untransform({ document: payload })

Options

Global options are passed in when creating a new transformalizer object. Options can also be passed in when transforming source objects to the json-api format or untransforming a json-api document back to data objects.

Options for Untransforming Json-Api Documents

Schema

A schema object defines a set of functions used to transform your raw data into a valid JSON API document. It has the following basic structure (that closely resembles a json api document), which is described in more detail below

{
  links({ source, options, data, included }) {
    return { /* top level links */ };
  },
  meta({ source, options, data, included }) {
    return { /* top level meta */ };
  },
  data: {
    dataSchema({ source, options, data }) {
      return 'other-schema-name';
    },
    untransformDataSchema({ type, resource, document, options }) {
      return 'my-type';
    },
    type({ source, options, data, state }) {
      return 'my-type';
    },
    id({ source, options, data, type, state }) {
      return data.id.toString();
    },
    untransformId({ id, type, options }) {
      return parseInt(id, 10);
    },
    attributes({ source, options, data, type, id, state }) {
      return { /* resource attributes */ }
    },
    untransformAttributes({ id, type, attributes, resource, options }) {
      return { /* resource attributes */ }
    },
    relationships: {
      // ..
      [key]({ source, options, data, type, id, attributes, state }) {
        return {
          data: {
            name: 'related-schema',
            data: { /* relationship data to be passed to other schema */ },
            included: true,
          },
          links: { /* relationship links if available */ },
          meta: { /* relationship meta if available */ }
        }
      },
      // ..
    },
    links({ source, options, data, type, id, attributes, relationships, state }) {
      return { /* resource links if available */ }
    },
    meta({ source, options, data, type, id, attributes, relationships, state }) {
      return { /* resource meta if available */ }
    }
  }
}

links(params) => Object optional

A function that should return the top level links object.

Parameters

meta(params) => Object optional

A function that should return the top level meta object.

Parameters

data.type(params) => String optional

A function that should return the type of the resource being processed. If this is not provided, the name of the schema will be used as the resource type.

Parameters

data.id(params) => String optional

A function that should return the id of the data object being processed. If this is not provided, it is assumed that the "id" of the resource is simply the "id" property of the source object.

Parameters

data.untransformId(params) => Object optional

A function that should return the id of the resource being processed. If this is not provided, it is assumed that the "id" of the data object is simply the "id" property of the resource.

Parameters

data.attributes(params) => Object optional

A function that should return the attributes portion of the resource being processed. If a null or undefined value is returned, no attributes will be included on the resource.

Parameters

data.untransformAttributes(params) => Object optional

A function that should return the attributes portion of the data object being processed. If this is not provided, it is assumed that the attributes of the data object are simply the "attributes" property of the resource.

Parameters

data.relationships.key(params) => Object optional

A map of relationship keys to functions that should return a valid relationship object with one caveat outlined below. If a null or undefined value is returned, that relationship will be excluded from the relationships object.

Caveat: The data property of the relationship object should either be a single object or an array of objects in the form shown below

{
  name: 'schemaName', // the name of the related schema to use to transform the related item
  data: { /* the "data" param to be passed to the related schema's functions */ },
  included: true, // optional, required if the related item should be included
  meta: { /* a meta object to be included on the resource identifier object */ }
}

Parameters

data.links(params) => Object optional

A function that should return the links object for the current resource. If a null or undefined value is returned, no links will be included on the resource.

Parameters

data.meta(params) => Object optional

A function that should return the meta object for the current resource. If a null or undefined value is returned, no attributes will be included on the resource.

Parameters

data.dataSchema(params) => String optional

A function that should return the name of a schema to use to transform the current source object. Useful for building documents who's primary data is a collection of multiple types.

Parameters

data.untransformDataSchema(params) => String optional

A function that should return the name of a schema to use to untransform the current resource.

Parameters

Test

Run the test suite

$ npm test

Run coverage

$ npm run coverage

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

Copyright (c) 2017 Gaia. Licensed under the MIT license.