README_v.1.x.x.md

DT Shape v.1.x.x

Build data structures by using data-shapes. The data-shape should looks like that:

const dtShape = require ( 'dt-shape' )
let shape  = {
                'name' : [ 'firstName' , 'name' ]
/*                ^            ^            ^
                  |            |            +---> top priority is always in the end
                  |            +---> search for values in these keys
                  |
      Create property with this name
                     
*/
                 }
     // Important! Data should be in DT format. If is not - convert it first.
     // Use dt-toolbox library.:
     let dt = dtbox.init(data).value
     
     // Build data according shape. Result will be in DT format.
     let resultDT = dtShape ( dt , shape )

     // If want result as a standard javascript object:
     let result = dtShape ( dt, shape ).build ()

What is DT?

DT format is a flatten version of the standard javascript object. Read more about DT on dt-toolbox page.

Installation

Node

Install node package:

npm install dt-shape --save

Once it has been installed, it can be used by writing this line of JavaScript code:

let dtShape = require ( 'dt-shape' )

Browsers

Copy 'dt-shape.min.js' from 'dist/' folder. Add script tag

<script src='js/dt-shape.min.js'></script>
// -> dtShape is available

// dt-toolbox is part of this script file.
dtbox = dtShape.getDTtoolbox ()

How it works?

dtShape is simple function that have two arguments - (source data, data shape) and returns a result DT object. Methods available for DT object are described in exportAPI of dt-toolbox.

Source Data

Source data should be DT object. Any standard javascript structure can be converted to DT by single row of code.

// use dt-toolbox
let dt = dtbox.init( jsObject ).value

Data Shape

Data shape represents connection between source data and result object. Keys will become a result property names. Values are source data keys where dtShape function will search for data. Values of the shape object are always array. Simple example:

let shape = { 'newName' : ['firstName']}

This shape creates object with property 'newName'. Value for 'newName' is taken from source data object, property 'firstName' . Shape values can contain more than one member.

let shape = { 'newName' : ['firstName','name'] }

This example says that result should have property 'newName' and value should be in keys 'firstName' or 'name' of the source data. This make possible to use same data shape with large variety of source data structures and result will be the same. Priority is always on last member of the array.

Data Shape - Key Prefixes

Keys can contain prefixes like list!, fold!, and load!.

• fold! prefix will search for properties and will fold them inside object. Example:

// shape with fold
let shape = { 'fold!name' : ['firstName','lastName']}
/*
 expected result should have
      {
          name : {
                      firstName : 'someValue'
                    , lastName : 'someOtherValue'
                }
      }
*/
 

• list! prefix will return list of values

// shape with fold
let shape = { 'list!family' : ['spouse','wife','kid']}
/*
 expected result should have
 {
    family : [ 'spouseName', 'wifeName', 'eventualKidName' , 'OtherKidName' ]
 }
*/
 

• load! prefix loads data from external source. Source could be function, primitive or object.

let name = 'Peter'
let shape = { 'load!firstName' : [ name ] }
let sourceData = { 'root/name' : 'Ivo' }
let result = dtShape ( sourceData, shape )
/*
 ->
      {
         firstName : 'Peter'
      }
 */

Examples

Simple example

const 
        dtShape = require ( 'dt-shape' )
     ,  dtbox   = dtShape.getDTtoolbox ()
     ;

let source = {
                firstName : 'Peter'
              , familyName : 'Naydenov'
           };

// convert object to DT
let dtSource = dtbox.init(source).value;

// Prepare the shape
let userShape = {
        'userName'         : [ 'firstName' ]
        'profile/name'     : [ 'firstName' ]
      , 'profile/lastName' : [ 'familyName']
    }

let user = dtShape ( dtSource, userShape ).build()

/*
  user should be:
  { 
      userName: 'Peter'
    , profile: { 
                   name: 'Peter'
                 , lastName: 'Naydenov' 
               } 
  }
*/

Find some examples in ./test folder.

Tips

• DT format not depends on dt-toolbox! Building data directly in DT format can save time for format conversion operations;

Known bugs

(Nothing yet)

Release History

1.0.2 (2019-06-02)

• Update dependencies: Dt-toolbox v.2.1.0;
• Upgrade dependencies: Webpack v.4.32.2;
• Browser version update;
• Documentation update;

1.0.0 (2017-12-28)

• Project folder reorganization;
• Test coverage. Istanbul;
• Test coverage on 100%;
• Version for browsers. Dt-toolbox included;
• Documentation update;

0.1.6 (2017-04-22)

• Update dependency dt-toolbox to 1.6.0;

0.1.5 (2017-03-28)

• Update dependency dt-toolbox to 1.4.0;

0.1.4 (2017-02-24)

• Documentation update only;

0.1.2 (2017-02-21)

• Fix: Problematic updates with wrong values;

0.1.0 (2017-02-20)

• Prefix load! loads data from external source;
• Error: Problematic updates with wrong values;

0.0.3 (2017-02-17)

• Just documentation update;

0.0.1 (2017-02-05)

• Initial code;
• Test package;
• Documentation;

Credits

'dt-shape' was created by Peter Naydenov.

License

'dt-shape' is released under the MIT License.