transformalizer - npm Package Compare versions

Comparing version 0.0.1 to 0.1.0

.eslintrc.json

 {
   "extends": "airbnb-base",
   "rules": {
-    "import/no-extraneous-dependencies": ["error", { "devDependencies": ["**/test/**/*.js"] }],
+    "import/no-extraneous-dependencies": [
+      "error",
+      {
+        "devDependencies": [
+          "**/test/**/*.js",
+          "**/examples/**/*.js"
+        ]
+      }
+    ],
+    "max-len": "off",
+    "no-multi-assign": "off",
     "no-param-reassign": "off",
     "no-underscore-dangle": "off",
-    "semi": ["error", "never"]
+    "no-use-before-define": "off",
+    "semi": [
+      "error",
+      "never"
+    ]
   }
 }

package.json

 {
   "name": "transformalizer",
-  "version": "0.0.1",
-  "description": "",
+  "version": "0.1.0",
+  "description": "a bare bones node module for building JSON API v1.0 compliant payloads",
   "main": "index.js",
+  "keywords": [
+    "json-api",
+    "json api",
+    "json",
+    "api",
+    "serialize",
+    "serializer",
+    "transform",
+    "transformalizer"
+  ],
   "scripts": {
+    "build": "rm -rf dist/* && babel lib -d dist",
+    "coverage": "./node_modules/.bin/babel-node ./node_modules/.bin/babel-istanbul cover ./node_modules/.bin/_mocha test/tests/*.test.js",
+    "postversion": "npm run build",
+    "release": "npm run build && standard-version",
     "test": "mocha --compilers js:babel-register test/tests/**/*.test.js"
   },
-  "author": "",
+  "contributors": [
+    {
+      "name": "Chris Ludden",
+      "url": "https://github.com/cludden"
+    },
+    {
+      "name": "Jason Sites",
+      "url": "https://github.com/jasonsites"
+    },
+    {
+      "name": "Joshua Wynn",
+      "url": "https://github.com/joshuarwynn"
+    },
+    {
+      "name": "Dave Smith",
+      "url": "https://github.com/davesmitty"
+    }
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GaiamTV/transformalizer"
+  },
   "devDependencies": {
@@ -26,11 +61,13 @@ "babel-cli": "^6.22.2",
     "json-pretty": "0.0.1",
+    "lodash": "^4.17.4",
     "mocha": "^3.2.0",
     "qs": "^6.3.0",
-    "sinon": "^1.17.7"
+    "ramda": "^0.23.0",
+    "sinon": "^1.17.7",
+    "standard-version": "^4.0.0"
   },
   "dependencies": {
-    "bluebird": "^3.4.7",
-    "ramda": "^0.23.0",
+    "clone": "^2.1.0",
     "source-map-support": "^0.4.11"
   }
 }

README.md

 # 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
+
+```shell
+$ npm install --save transformalizer
+```
+
+
+
+## Getting Started
+
+Create a new transformalizer and register schemas
+```javascript
+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](/examples/basic.js)
+
+
+
 ## API
 
-### Transformalizer()
+### createTransformalizer([options]) => transformalizer
 
-### transformalizer.register({ type, schema })
+Create a new transformalizer object
 
@@ -12,15 +58,108 @@ ###### Parameters
 | --- | --- | --- |
-| type* | String | json api type |
-| schema* | Object | mappings for type |
+| [options={}] | Object | global options shared between all schemas |
 
-### transformalizer.transform({ type, source, options }) => Object
+###### Examples
+```javascript
+const createTransformalizer = require('transformalizer')
 
+const transformalizer = createTransformalizer()
+```
 
+---
+
+### transformalizer.register(params)
+
+Register a new document schema.
+
+###### Parameters
+| Name | Type | Description |
+| --- | --- | --- |
+| params | Object | |
+| params.name | String | schema name |
+| params.schema | Object | mappings for type, see [Schema](#schema) for more details |
+
+###### Examples
+```javascript
+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
+| Name | Type | Description |
+| --- | --- | --- |
+| params | Object | |
+| params.name | String | the name of the schema to use |
+| params.source | Object|Object[] | source data |
+| [params.options={}] | Object | additional data to be passed to transform functions, this will be merged with the global options |
+
+###### Examples
+```javascript
+const blogPost = { title: 'Hello, World!', body: 'To be continued...', createdAt: new Date() }
+const document = transformalizer.transform({ name: 'blog-post', source: blogPost })
+```
+
+
+
 ## Schema
-A schema object defines a set of functions used to transform your raw data into a valid JSON API document.
 
+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
+```javascript
+{
+  links({ source, options, document }) {
+    return { /* top level links */ };
+  },
+  meta({ source, options, document }) {
+    return { /* top level meta */ };
+  },
+  data: {
+    dataSchema({ source, options, data }) {
+      return 'other-schema-name'
+    },
+    type({ source, options, data }) {
+      return 'my-type';
+    },
+    id({ source, options, data, type }) {
+      return data.id.toString();
+    },
+    attributes({ source, options, data, type, id }) {
+      return { /* resource attributes */ }
+    },
+    relationships: {
+      // ..
+      [key]({ source, options, data, type, id, attributes }) {
+        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 }) {
+      return { /* resource links if available */ }
+    },
+    meta({ source, options, data, type, id, attributes, relationships }) {
+      return { /* resource meta if available */ }
+    }
+  }
+}
+```
 
+### links(params) => Object <small>optional</small>
 
-### type({ source, options, data }) => String
-A function that should return the type of the resource being processed. If this returns a type other than the schema type, the other schema will be used in place of the current schema.
+A function that should return the top level links object.
 
@@ -30,10 +169,13 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function, merged with the global options object |
+| params.data | Object | the json api document data after transform |
+| params.included | Object[] | the json api document included data after transform |
 
+---
 
+### meta(params) => Object <small>optional</small>
 
-### id({ source, options, data }) => String
-A function that should return the id of the resource being processed.
+A function that should return the top level meta object.
 
@@ -43,10 +185,13 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function, merged with the global options object |
+| params.data | Object | the json api document data after transform |
+| params.included | Object[] | the json api document included data after transform |
 
+---
 
+### data.type(params) => String <small>optional</small>
 
-### attributes({ source, options, data, id }) => Object
-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.
+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.
 
@@ -56,11 +201,12 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
-| id | String | the id of the current resource |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
 
+---
 
+### data.id(params) => String <small>optional</small>
 
-### relationships.[key]({ source, options, data, id, attributes, include }) => Object
-A map of relationship keys to functions that should return a valid [relationship object](http://jsonapi.org/format/#document-resource-object-relationships). If a null or undefined value is returned, that relationship will be excluded from the resulting object.
+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 resource is simply the "id" property of the source object.
 
@@ -70,13 +216,13 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
-| id | String | the id of the current resource |
-| attributes | Object | the attributes object for the resource being processed |
-| include | Function | TODO
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params.type | String | the resource type determined in the `data.type` step |
 
+---
 
+### data.attributes(params) => Object <small>optional</small>
 
-### links({ source, options, data, id, attributes, relationships }) => Object
-A function that should return the links portion of the resource being processed. If a null or undefined value is returned, no attributes will be included on the resource.
+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.
 
@@ -86,29 +232,41 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
-| id | String | the id of the current resource |
-| attributes | Object | the attributes object for the resource being processed |
-| relationships | Object | the relationships object for the resource being processed |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params.type | String | the resource type determined in the `data.type` step |
+| params.id | String | the id of the current resource, determined in the `data.id` step |
 
+---
 
+### data.relationships.*key*(params) => Object <small>optional</small>
 
-### meta({ source, options, data, id, attributes, relationships, links }) => Object
-A function that should return the meta portion of the resource being processed. If a null or undefined value is returned, no attributes will be included on the resource.
+A map of relationship keys to functions that should return a valid [relationship object](http://jsonapi.org/format/#document-resource-object-relationships) 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
+```javascript
+{
+  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
 | Name | Type | Description |
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| data | Object | the current item being processed when source is an array, or the source itself if not an array |
-| id | String | the id of the current resource |
-| attributes | Object | the attributes object for the resource being processed |
-| relationships | Object | the relationships object for the resource being processed |
-| links | Object | the links object of the resource being processed |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params.type | String | the resource type determined in the `data.type` step |
+| params.id | String | the id of the current resource, determined in the `data.id` step |
+| params.attributes | Object | the attributes object of the current resource, determined in the `data.attributes` step |
 
+---
 
+### data.links(params) => Object <small>optional</small>
 
-### topLevelLinks({ source, options, document }) => Object
-A function that should return the top level links for the current document.
+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.
 
@@ -118,10 +276,16 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| document | Object | the current json api document |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params.type | String | the resource type determined in the `data.type` step |
+| params.id | String | the id of the current resource, determined in the `data.id` step |
+| params.attributes | Object | the attributes object of the current resource, determined in the `data.attributes` step |
+| params.relationships | Object | the relationships object of the current resource, determined in the `data.relationships` step |
 
+---
 
+### data.meta(params) => Object <small>optional</small>
 
-### topLevelMeta({ source, options, document }) => Object
-A function that should return the top level meta for the current document.
+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.
 
@@ -131,4 +295,61 @@ ###### Parameters
 | --- | --- | --- |
-| source | Object[],Object | the source data passed to the #transform function |
-| options | Object | any options passed to the #transform function |
-| document | Object | the current json api document |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+| params.type | String | the resource type determined in the `data.type` step |
+| params.id | String | the id of the current resource, determined in the `data.id` step |
+| params.attributes | Object | the attributes object of the current resource, determined in the `data.attributes` step |
+| params.relationships | Object | the relationships object of the current resource, determined in the `data.relationships` step |
+| params.links | Object | the links object of the current resource, determined in the `data.links` step |
+
+---
+
+### data.dataSchema(params) => String <small>optional</small>
+
+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
+| Name | Type | Description |
+| --- | --- | --- |
+| params | Object | |
+| params.source | Object[],Object | the source data passed to the #transform function |
+| params.options | Object | any options passed to the #transform function |
+| params.data | Object | the current item being processed when source is an array, or the source itself if not an array |
+
+
+
+## Test
+
+Run the test suite
+```shell
+$ npm test
+```
+
+Run coverage
+```shell
+$ npm run coverage
+```
+
+
+
+## Contributing
+
+1. [Fork it](https://github.com/GaiamTV/transformalizer/fork)
+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
+
+
+
+## Semver
+
+Until transformalizer reaches a 1.0 release, breaking changes will be released with a new minor version. For example 0.5.1, and 0.5.4 will have the same API, but 0.6.0 will have breaking changes.
+
+
+
+## License
+
+Copyright (c) 2017 Gaia.  
+Licensed under the [MIT license](LICENSE.md).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

74015

increased by155.24%

Dependency count

2

decreased by-33.33%

Number of low maintenance alerts

2

decreased by-33.33%

Number of lines in readme file

348

increased by174.02%

Number of low supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

20

increased by17.65%

Number of package files

10

decreased by-23.08%

Lines of code

578

decreased by-7.96%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedclone@^2.1.0

• + Addedclone@2.1.2(transitive)

• - Removedbluebird@^3.4.7

• - Removedramda@^0.23.0

• - Removedbluebird@3.7.2(transitive)

• - Removedramda@0.23.0(transitive)