DT Toolbox v.7.x.x

Last Updates

• After version 7.3.0 extractList options.as can receive a dt-model and dt-object;
• After version 7.1.x dt-object api has a new method extractList that helps to extract a multiple segments or properties, defined as a list. Use 'options'(the second argument) to define a model of extracted data if needed. Reed about extractList bellow.

Description

DT-Toolbox is a tool, created to simplify the work with deep nested javascript objects. The library creates an immutable data-storage(dt-object). Storage data representation is based on data-model called DT-model.

What is DT-model?

It's an internal 'dt-object' data description. Data is an array of lines where each line has 4 components:

[  // dt-model
      [ name, flatData, breadcrumbs, edges ]  // dt-line
    , [ name, flatData, breadcrumbs, edges ]  // dt-line
    // ...
]
// Where ->
// name: string. Name of the dt-line;
// flatData:  object or array of primitive types;
// breadcrumbs: string. Bredcrumbs description(identifier) of the current dt-line;
// edges: string[]. List of breadcrumbs of the related dt-lines(children);

This data-description is easy to read, saved, or transfered.

DT-model can become a storage for multiple data blocks - data-segments. Each data-segment can be extracted but also can be queried and modeled together with other data-segments in a way to create a new dt-object.

Concept state - A specific shape of DT-model where all primitive states are stored in 'root' object and the other states as separated data-segments. Root data-segment is a flat object (single row without edges).

There is a library @peter.naydenov/dt-queries that contains query functions that can be useful with data manipulation:

• splitSegments: Splits a solid data into multiple data-segments;
• joinSegments : Consolidate multiple data-segments in a single solid data;
• updateState : Updates the state with new data. Takes only declared data-segments and root data properties;

Installation

Install for node.js projects by writing in your terminal:

npm install dt-toolbox

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

import dtbox from 'dt-toolbox'

How it works?

Use Dt-toolbox methods(init and load) to create a dt-object.

DT-object:

• Provides multiple insertion of data-segments. Data from each insertion stays differentiated;
• Has prebuilded filters for fast search of data;
• Can create and register a customized filters for fast search of data;
• Can apply query functions to find, extract and reshape the data;
• Can apply model function to reshape the final result;
• Can executes 'query' and 'model' function over all available data in the storage (All data segments);
• Execution of query/model functions will not change anything inside the host dt-object;

The dt-object contains internally a dt-storage object, that is available during call of the 'query' or 'model' functions. Dt-storage have couple of methods for searching data as well can create a new DT-model structures and fill them with data.

Query functions are returning a new instance of dt-object with the result, created by dt-storage. Remember - data inside dt-object never get modified.

Filters can significantly improve the speed of searching information inside dt-objects by creating a shorter scan-list according some specific preferences. Library is coming with list of predefined filters:

  'list'        : 'Scan only dt-lines where flatData is an array'
, 'listObject'  : 'Scan objects that are members of array'
, 'object'      : 'Scan just dt-lines where flatData is an object'
, 'root'        : 'Scan only root dt-lines of each data segment'

Filters are very simple functions to build. Here is one example of how we can create filter for finding object with specific key and value in it.

function findBlueEyesFn ({ // We have named arguments
                      name        // Name of dt-line
                    , flatData     // The data. Flat object or array
                    , breadcrumbs // Location description
                    , edges       // List of breadcrumbs related to this dt-line
                }) {
    if ( flatData.eyes === 'blue' )   return true   // confirm that dt-line should be in that filter list 
    return false // ignore this dt-line
 }

 // Register a filter to some dt-object:
 dt.setupFilter ( 
                     'blueEyes'     // filter name
                    , findBlueEyesFn // provide a filter function
                )
// Filter function will be executed on each dt-line to create a filter scan-list

 // Using the filter during execution of query/model functions:
 dt.query ( store => {
                store
                  .use ( 'blueEyes' ) // Set the name of the filter 
                  .look ( ({}) => {
                            // ... will scan only dt-lines selected by filter
                        })
        })

Take a look on the library APIs and see the 'Examples' section bellow.

dt-toolbox API Fast Reference

    init    : 'Create a new dt-object from data that is not a DT-model and needs a convertion'
  , load    : 'Create a new dt-object from data that is a DT-model'
  , flat     : 'Convert a data to DT-model without creation of dt-object'
  , convert : 'Direct convertion from model to model without creation of dt-object'
  , getWalk : 'Returns a instance of "walk" library'

dt-object API Fast Reference

    insertSegment  : 'Inserts a new data-segment in the dt-object. Insertion should be provided as a dt-object.'
  , 'export' : 'Returns the DT-model from dt-object - part or full'
  , copy     : 'Creates a copy of original provided data'
  , query    : 'Executes a "query" function on the dt-object. Returns a new dt-object with the result'
  , model    : 'Executes a "model" function on the dt-object. Returns a data model'
  , setupFilter : 'Evaluate data according "filter" function and create a shorter scan list that can be used by "dt-storage" during execution of query and model functions'
  , index    : 'Provides a copy of specified dt-line by breadcrumbs'
  , listSegments : 'Returns a list of all segments in dt-object'
  , extractList : 'Extracts a list of segments and/or properties from dt-object'

dt-storage API Fast Reference

Object dt-storage is available as argument to 'query' and 'model' functions. Methods of 'dt-storage' can scan DT-model for data and build a new DT-model structure and fields.

Important: Result of building a DT-model returns as a separate dt-object and will not modify anything inside actual dt-object.

 // Scan methods
, from : 'Scan deeper from specified dt-line by location(breadcrumbs)'
, use  : 'Use filter name to execute `look` on shorter list of dt-lines.'
, get  : 'Take a single dt-line with specific breadcrumbs'
, find  : 'String search for exact object name'
, like : 'String search in dt-line name'
, look : 'Executes on each object property in the selection list'

// DT-model structure and fields creation:
  set     : 'Define new dt-line record'
, connect : 'Creates a list of connections between two already existing dt-lines'
, save    : 'Save a property to flatData object in existing dt-line'
, push    : 'Save a value to flatData array of existing dt-line'

DT Toolbox API

dtbox.init ()

Create a new dt-object from data that is not a DT-model and needs a convertion. Please take a look on section Init/Export Data-Models for more details.

const data = {  // Standard JS object
                      name: 'Peter'
                    , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
                    , shoes : {
                                      winter : [ 'Keen', 'Head']
                                    , summer : [ 'Lotto', 'Asics' ]
                            }
            };

const midData = { // Midflat model object
                      'root' : { name: 'Peter' }
                    , 'familyMembers' :  ['Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
                    , 'shoes/winter' : [ 'Keen', 'Head' ]
                    , 'shoes/summer' : [ 'Lotto', 'Asics' ] 
                }

 const dtS = dtbox.init ( data ) // Creates dt-object from 'standard'(std) data-model
 // it's equal to this:  const dtS = dtbox.init ( data, { model:'std' })
 const dtMid = dtbox.init ( midData, { model : 'midFlat' }) // Creates a dt-object from midFlat data.

dtbox.load ()

Create a new dt-object from data that is a DT-model.

const dtData = [
  [
    'root',
    { city: 'Varna', desc: 'Big city on the Black-sea seaside' },
    'root',
    [ 'root/location', 'root/extra' ]
  ],
  [
    'location',
    { continent: 'Europe', country: 'Bulgaria' },
    'root/location',
    []
  ],
  [
    'extra',
    { port: 'Yes', airport: 'Yes' },
    'root/extra',
    [ 'root/extra/nearTo' ]
  ],
  [
    'nearTo',
    [ 'Burgas', 'Shumen', 'Dobrich' ],
    'root/extra/nearTo',
    []
  ]
];

const dtStore = dtbox.load ( dtData );   // Load DT-model data to dt-object

dtbox.flat ()

Convert a data to DT-model without creation of dt-object.

const a = {
    city : 'Varna'
  , desc: 'Big city on the Black-sea seaside'
  , location : {
                    continent: 'Europe'
                  , country : 'Bulgaria'
      
          }
  , extra : {
                port    : 'Yes'
              , airport : 'Yes'
              , 'nearTo' : [ 'Burgas', 'Shumen', 'Dobrich' ]
          }
};

const inFlatModel = dtbox.flat ( a ) // Default data-model is set to 'standard'(std)
// it's equal to: const inFlatModel = dtbox.flat ( a, {model: 'std'})
/**
 *   inFlatModel = [
  [
    'root',
    { city: 'Varna', desc: 'Big city on the Black-sea seaside' },
    'root',
    [ 'root/location', 'root/extra' ]
  ],
  [
    'location',
    { continent: 'Europe', country: 'Bulgaria' },
    'root/location',
    []
  ],
  [
    'extra',
    { port: 'Yes', airport: 'Yes' },
    'root/extra',
    [ 'root/extra/nearTo' ]
  ],
  [
    'nearTo',
    [ 'Burgas', 'Shumen', 'Dobrich' ],
    'root/extra/nearTo',
    []
  ]
]
 */

dtbox.convert ()

Direct convertion from model to model without creation of dt-object.

let result = dtbox.convert ( a, {
                                      model : 'std'         // Model: Source data-model
                                    , as    : 'breadcrumbs' // as: Convert data to this data-model
                                })

/** 
   result = {
              'city': 'Varna'
            , 'desc': 'Big city on the Black-sea seaside'
            , 'location/continent': 'Europe'
            , 'location/country': 'Bulgaria'
            , 'extra/port': 'Yes'
            , 'extra/airport': 'Yes'
            , 'extra/nearTo/0': 'Burgas'
            , 'extra/nearTo/1': 'Shumen'
            , 'extra/nearTo/2': 'Dobrich'
            }
 */

dtbox.getWalk ()

Dt-Toolbox is using "walk" library. If you need to use it directly - get the version used by Dt-Toolbox.

const walk = dtbox.getWalk ();

DT-object API

dt.insertSegment ()

Extend the dt-object with a new data segment. Insertion should be provided as dt-object.

const a = [ // it's a 'file' data-model
              'name/Peter'
            , 'familyMembers/Veselina'
            , 'familyMembers/Iskra'
            , 'familyMembers/Maria'
            , 'familyMembers/Vasil'
            , 'familyMembers/Vladimir'
            , 'familyMembers/Petya'
            , 'shoes/winter/Keen'
            , 'shoes/winter/Head'
            , 'shoes/summer/Lotto'
            , 'shoes/summer/Asics'
    ];
const b = { shoes: [ 'Puma', 'UA' ]}
const dt = dtbox.init ( a, { model : 'file' })  // create a dt-object
dt.insertSegment ( 
         'extra'        // object name
        , dtbox.init(b) // the extra object
    ) // insert to 'dt' storage data segment named 'extra' with data from 'b' object

/**
   dt internal interpretation:
[
      [ 
          'root' // -> dt-line name
        , {name:'Peter'} // -> flatData
        , 'root' // -> location. For top element of each data segment breadcrumbs === name
        , [ 'root/familyMembers', 'root/shoes' ] // -> edges
      ]
    , [ 
        'familyMembers' // -> dt-line name
        , [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ] // -> flatData
        , 'root/familyMembers' // -> location
        , [] // -> edges
      ]
    , [
         'shoes' // -> dt-line name
        , {} // -> flatData
        , 'root/shoes' // -> location
        , [ 'root/shoes/winter', 'root/shoes/summer' ] // -> edges
      ]
    , [
            'winter' // -> dt-line name
            , [ 'Keen', 'Head' ] // -> flatData
            , 'root/shoes/winter' // -> location
            , [] // -> edges
        ]
    , [
            'summer' // -> dt-line name
            , [ 'Lotto', 'Asics' ] // -> flatData
            , 'root/shoes/summer' // -> location
            , [] // -> edges
        ]
     // ---> Here are the elements that are coming from 'insertSegment'   
    , [
            'extra' // -> dt-line name. Object name of insert will become root element for data segment.
            , {} // -> flatData
            ,'extra' // -> location. For top element of each data segment breadcrumbs === name
            , [ 'extra/shoes' ] // -> edges
        ]
    , [
            'shoes' // -> dt-line name
            , [ 'Puma', 'UA'] // -> flatData
            , 'extra/shoes' // -> location
            , [] // -> edges
        ]
]

 */

dt.export ()

Returns DT-model from dt-object.

const all = dt.export ()  // will return all data from the storage
const root = dt.export ( 'root' ) // will return only initial data segment
const extra = dt.export ( 'extra' ) // will return only 'extra' data segment
/**
   extra = [
    , [
            'root' // -> dt-line name was changed to 'root'. Name 'extra' has meaning just inside dt-object
            , {} // -> flatData
            ,'root' // -> location. For top element of each data segment breadcrumbs === name
            , [ 'root/shoes' ] // -> edges
        ]
    , [
            'shoes' // -> dt-line name
            , [ 'Puma', 'UA'] // -> flatData
            , 'root/shoes' // -> location
            , [] // -> edges
        ]
   ]
 */

dt.copy ()

During the initialization process dt-object will save a deep copy of original data inside and can provide a deep copy in any time. Function copy can't provide copy of all data segments together because they are not related to each other. By default, when there is no name as argument, function will return the copy of 'root' object.

const 
      b = { shoes: [ 'Puma', 'UA' ]}
    , c = { vitamins : [ 'a', 'b', 'c' ]}
    , dt = dtbox.init ( b )
    ;
dt.insertSegment ( 'extra', c )
const deepCopy = dt.copy ()
// it equal to: const deepCopy = dt.copy ('root')
const onlyExtra = dt.copy ( 'extra' )
// onlyExtra = { vitamins : [ 'a', 'b', 'c' ]}

dt.query ()

Executes a "query" function on the dt-object. If there is something new, will return it. If there are no changes, it will return itself. For more details take a look on store API and especially store.set(), store.save(), store.push(), store.connect().

  function queryFn ( store, a, b ) { // optional arguments will come directly after 'store' api
            // ... body of queryFn
    }
  const dtOther = dt.query ( queryFn, a, b ) // queryFn is required arguments. All other arguments are optional

dt.model ()

Executes a "model" function on the dt-object. Returns a data-model. Default choice is DT-model object. Change the response representation by returning an object as in example below:

function modelFn ( store, a,v,g ) { // optional arguments will come directly after 'store' api
            // ... body of modelFn
            // to convert result in some of predefined and supported models, function should return an object
            return {
                as : 'std' // property 'as' will execute final conversion. Model name should be from supported list of the library.
                }
    }
// Supported model-names are:
// 'standard', 'std', 'midFlat', 'tuple', 'tuples', 'breadcrumb', 'breadcrumbs'

const result = dt.model ( modelFn, a,v,g ) // modelFn is the only required argument. All other arguments are optional.

dt.setupFilter ()

Evaluate data according "filter" function and create a shorter scan list that can be used by dt-storage API during the execution of query or model functions. For more details about filters look at function store.use() function.

function blueFn ({
                      name        // Name of dt-line
                    , flatData     // The flat data
                    , breadcrumbs // Location description
                    , edges       // List of breadcrumbs related to this dt-line
                }) {
            if ( flatData.hasOwnProperty('eyes') && flatData.eyes === 'blue' )   return true   // confirm that dt-line should be in that filter list 
            return false // ignore this dt-line
    // dt-lines that are 
}

dt.setupFilter (
          'blue'   // Name of the filter
        , blueFn   // Provide a filter function
    )

dt.index ()

Provides a copy of specified by breadcrumbs DT-line.

const br = 'root/friends'
const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            }
const [ name, flatData, breadcrumbs, edges ] = dt.index ( br )
// name = friends
// flatData = [ 'Ivan', 'Dobroslav', 'Stefan' ]
// breadcrumbs === br
// edges === []

dt.listSegments ()

Returns a list of all data segment names. Result is always an array with at least one element - 'root'.

dt.listSegments () 
// [ 'root', 'extra' ]

dt.extractList ()

After version 7.1.x method extractList was added. Method can extract a list of segments and properties as a single instruction. Options are coming as a second argument. Use optioins(the second argument) to define a model of extracted data if needed. Modeling is applied only on objects.

If requested segment or property is not available, response will be 'null'. Segments have priority over properties. If there is a segment with the same name as a property, segment will be extracted.

const 
    first = { name: 'first', data: 'first data' }
  , second = { name: 'second', data: 'second data' }
  , third = { name: 'third', data: 'third data' }
  ;
const storage = dtbox.init ( first );   // first will become a root segment
storage.insertSegment ( 'second', second );
storage.insertSegment ( 'third', third );

const [ a, b c, firstData, otherData ] = storage.extractList ( ['first', 'second', 'third', 'data', 'secondData' ], { as: 'std' } ));
// a -> { name: 'first', data: 'first data' }
// b -> { name: 'second', data: 'second data' }
// c -> { name: 'third', data: 'third data' }
// firstData -> 'first data' // Field 'data' from main dt-line of 'root' segment.
// otherData -> null // There is no 'secondData' in 'root' segment. No segment 'secondData' as well.

DT-store API

As we already mentioned, store is available in query/model functions and coming as the first argument.

store.look ()

Function that will be executed on each object key/value from the selection list. If selection is not explicitly mentioned, executes function on each dt-line data segments.

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const dt = dtbox.init ( data );

const result = dt.query ( store => {
                            // Direct call of look on store will be executed on each dt-line
                            store.look ( ({ // Named arguments. All available argument-names are listed here:
                                              value 
                                            , key
                                            , name         // dt-line name;
                                            , flatData      // full flatData for specified dt-line;
                                            , breadcrumbs  // breadcrumbs for dt-line;
                                            , links        // List of tuples [[parent, child],...]. Parent and child are the dt-line names;
                                            , empty        // Will present only if object has no properties. Empty flatData for dt-line.
                                            , next         // Function that can be returned to move to next dt-line
                                            , finish       // Function that can be returned to stop execution of look function
                                            }) => {
                                                        //... body of look function
                                                        // Move fast to next dt-line by returning a string 'next'
                                                        return next ()
                                                        // unconditional `return next()` will executes the 'look' function once per dt-line
                                            })
                    })

store.from ()

Scan deeper from specified dt-line by location(breadcrumbs).

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const 
      dt = dtbox.init ( data )
    , res = dt.query ( store => {
                          store
                              .from ( 'root/personal/hobbies' )
                              .look ( ({name, next }) => {
                                                console.log ( name )
                                                // -> hobbies, music, sport
                                                return next () // because we want to iterate once on each dt-line
                                        })
                    });

store.use ()

Use filter to execute look on shorter list of dt-lines. Use the predefined or your own filters. List of predefined filters:

• 'list' : Scan only dt-lines where flatData is an array;
• 'listObject' : Scan objects that are members of array;
• 'object' : Scan just dt-lines where flatData is an object;
• 'root' : Scan only root dt-lines of each data segment;

If filter do not exist, look function will be executed on each dt-line.

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const 
      dt = dtbox.init ( data )
    , res = dt.query ( store => {
                            store
                              .use ( 'object' )   // predefined filter 'object'
                              .look ( ({name, next }) => {
                                                console.log ( name )
                                                // -> root, personal, hobbies
                                                return next () // because we want to iterate once on each dt-line
                                        })
                    });

store.get ()

Take a single dt-line with specific breadcrumbs.

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const 
      dt = dtbox.init ( data )
    , res = dt.query ( store => {
                            store
                              .get ( 'root/friends' )
                              .look ( ({ flatData, next }) => {
                                                console.log ( flatData )
                                                // -> [ 'Ivan', 'Dobroslav', 'Stefan' ]
                                                return next ()   // because we want to iterate once on each dt-line
                                        })
                    });

store.find ()

String search for exact object name

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const 
      dt = dtbox.init ( data )
    , res = dt.query ( store => {
                            store
                              .find ( 'music' )
                              .look ( ({flatData, next }) => {
                                                console.log ( flatData )
                                                // -> [ 'punk', 'ska', 'metal', 'guitar' ]
                                                return next () // because we want to iterate once on each dt-line
                                        })
                    });

store.like ()

String search in dt-line name

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const 
      dt = dtbox.init ( data )
    , res = dt.query ( store => {
                            store
                              .like ( 'per' )
                              .look ( ({flatData, breadcrumbs, next }) => {
                                                console.log ( flatData )
                                                // -> { age: 49, eyes: 'blue' }
                                                console.log ( breadcrumbs )
                                                // -> 'root/personal'
                                                return next ()   // because we want to iterate once on each dt-line
                                        })
                    });

// DT-model structure and fields creation:

store.set ()

Define new dt-line record

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            };
const dt = dtbox.init ( data );

const result = dt
                .query ( store => {
                            store.set ( 'root', [2,4,15])   // new dt-line structure was created
                        })
                .model (  () => ({as:'std'}) )
console.log ( result )
// -> [2,4,15]

const result2 = dt
                 .query ( store => {})   // If there is no new dt-line, query will return itself
                 .model ( () => ({as:'std'})   )
console.log ( result2 )
/**
 {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            , personal : {
                              age     : 49
                            , eyes    : 'blue'
                            , sizes   : [ 10, 44, 'm', 'mid' ]
                            , hobbies : { 
                                               music : [ 'punk', 'ska', 'metal', 'guitar' ]
                                            , sport  : [ 'fencing', 'skating', 'ski' ]
                                        }
                        }
            }
 */

store.connect ()

Creates a list of connections between two already existing dt-lines

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            };
const 
      dt = dtbox.init ( data )
    , result = dt
              .query ( store => {
                            store.set ( 'root', { name: Stefan })
                            store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )
                            store.connect (['root/friends'])
                    })
              .model ( () => ({as:'std'}))
    ;
console.log ( result )
/**
   { 
          name: Stefan
        , friends: ['Stefan', 'Tommy', 'Maria' ]
    }
 */ 

store.save ()

Save a property to flatData object in existing dt-line.

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            };
const 
      dt = dtbox.init ( data )
    , result = dt
              .query ( store => {
                            store.set ( 'root', { name: Stefan })
                            store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )
                            store.connect (['root/friends'])
                            store.save ( 'root', 'age', 35 )
                    })
              .model ( () => ({as:'std'}))
    ;
console.log ( result )
/**
   { 
          name: Stefan
        , age : 35
        , friends: ['Stefan', 'Tommy', 'Maria' ]
    }
 */ 

store.push ()

Save a value to flatData of existing dt-line. FlatData should be an array.

const data = {
              name: 'Peter'
            , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]
            };
const 
      dt = dtbox.init ( data )
    , result = dt
              .query ( store => {
                            store.set ( 'root', { name: Stefan })
                            store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )
                            store.connect (['root/friends'])
                            store.push ( 'friends', 'Lily' )
                    })
              .model ( () => ({as:'std'}))
    ;
console.log ( result )
/**
   { 
          name: Stefan
        , friends: ['Stefan', 'Tommy', 'Maria', 'Lily' ]
    }
 */ 

Init/Export Data-Models

The library has some predefined data-models and can read and convert data among them.

Standard ( std )

Standard data model is a standard deep javascript object.

const data = {
                      name: 'Peter'
                    , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
                    , shoes : {
                                      winter : [ 'Keen', 'Head']
                                    , summer : [ 'Lotto', 'Asics' ]
                            }
            }

MidFlat

It's a two level deep javascript object. First object properties represent the location of the data, value is a flat object or array:

{
      'root' : { name: 'Peter' }
    , 'familyMembers' :  ['Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
    , 'shoes/winter' : [ 'Keen', 'Head' ]
    , 'shoes/summer' : [ 'Lotto', 'Asics' ] 
}

Breadcrumbs

It's a flat interpratation of the data and looks like this:

{
      'name'            : 'Peter'
    , 'familyMembers/0' : 'Veselina'
    , 'familyMembers/1'  : 'Iskra'
    , 'familyMembers/2'  : 'Maria'
    , 'familyMembers/3'  : 'Vasil'
    , 'familyMembers/4'  : 'Vladimir'
    , 'familyMembers/5'  : 'Petya'
    , 'shoes/winter/0'   : 'Keen'
    , 'shoes/winter/1'   : 'Head'
    , 'shoes/summer/0'   : 'Lotto'
    , 'shoes/summer/1'   : 'Asics'
}

Files

Data is interpreted like file/folder description.

[
      'name/Peter'
    , 'familyMembers/Veselina'
    , 'familyMembers/Iskra'
    , 'familyMembers/Maria'
    , 'familyMembers/Vasil'
    , 'familyMembers/Vladimir'
    , 'familyMembers/Petya'
    , 'shoes/winter/Keen'
    , 'shoes/winter/Head'
    , 'shoes/summer/Lotto'
    , 'shoes/summer/Asics'
]

Tuples

Array of tuples. First element represents location + property name, second is the value.

[
      ['name', 'Peter' ]
    , ['familyMembers', 'Veselina']
    , ['familyMembers', 'Iskra']
    , ['familyMembers', 'Maria']
    , ['familyMembers', 'Vasil']
    , ['familyMembers', 'Vladimir']
    , ['familyMembers', 'Petya']
    , ['shoes/winter' , 'Keen']
    , ['shoes/winter' , 'Head']
    , ['shoes/summer' , 'Lotto']
    , ['shoes/summer' , 'Asics']
]

Examples

Find people under 40

Find a people that are under 40 years old and provide the result as a list.

let data = {
     'school' : [
                      { name: 'Ivan',   age: 14 }
                    , { name: 'Georgy', age: 15 }
                    , { name: 'Adi',    age: 11 }
                    , { name: 'Kati',   age: 11 }
                ]
    , 'sports' : [
                      { name: 'Iva',    age: 28 }
                    , { name: 'Stoyan', age: 36, sport: 'fencing' }
                ]
    , 'work'   : [
                      { name: 'Hristo',   age: 38 }
                    , { name: 'Lachezar', age: 33 }
                    , { name: 'Veselina', age: 35 }
                    
                ]
    , 'recent' : {
                     'classmates' : [
                                         { name: 'Anton',     age: 42 }
                                       , { name: 'Miroslava', age: 42 }
                                    ]
                    , 'social' : [
                                       { name: 'Iliana', age: 61 }
                                     , { name: 'Tzvetan', age: 19 }
                                 ]
                 }
    }

const dt = dtbox.init ( data ); // creates a dt-object

const result = dt.query ( store => {
                            let 
                                  i = 0
                                , connectBuffer = []
                                ;
                            store.set ( 'root', [])  // setup a root array element
                            store
                                .use ( 'listObject' ) // use only objects that are members of array
                                .look ( ({ name, flatData, next }) => {
                                            if ( flatData.age < 40 ) {  
                                                    store.set ( i, flatData )
                                                    connectBuffer.push ( `root/${i}` )
                                                    i++
                                                }
                                            return next ()
                                        })
                            store.connect ( connectBuffer )
                    })
                  .model ( () => ({ as : 'std'}))
console.log ( result )
/** ->
 [
  { name: 'Ivan', age: 14 },
  { name: 'Georgy', age: 15 },
  { name: 'Adi', age: 11 },
  { name: 'Kati', age: 11 },
  { name: 'Iva', age: 28 },
  { name: 'Stoyan', age: 36, sport: 'fencing' },
  { name: 'Hristo', age: 38 },
  { name: 'Lachezar', age: 33 },
  { name: 'Veselina', age: 35 },
  { name: 'Tzvetan', age: 19 }
] 
*/ 

Provide just a list of names

Use the same data from previous example but return only the list of names.

const result = dt.query ( store => {
                                store.set ( 'root', [])
                                store
                                   .use ( 'listObject' ) // use only objects that are members of array
                                   .look ( ({ flatData, next }) => {
                                               if ( flatData.age < 40 )   store.push ( 'root', flatData.name )
                                               return next ()
                                           })
                    })
                 .model ( () => ({as:'std'})   )
console.log ( result )
/** ->
 [
  'Ivan',     'Georgy',
  'Adi',      'Kati',
  'Iva',      'Stoyan',
  'Hristo',   'Lachezar',
  'Veselina', 'Tzvetan'
]
 */

Organize people in two groups

Return an object with two groups

• 'over40'
• 'under40' Provide only the names.

const result = dt.query ( store => {
                              store.set ( 'root', {} )
                              store.set ( 'under40', [])
                              store.set ( 'over40' , [])
                              store.connect ([ 'root/under40', 'root/over40' ])
                              store
                                  .use ( 'listObject' ) // use only objects that are members of array
                                  .look ( ({ flatData, next }) => {
                                              let location = ( flatData.age > 40 ) ? 'over40' : 'under40';
                                              store.push ( location, flatData.name )
                                              return next ()
                                          })
                      })
                    .model ( () => ({ as : 'std'}))
console.log ( result )
/** ->
{
 'under40': [
   'Ivan',     'Georgy',
   'Adi',      'Kati',
   'Iva',      'Stoyan',
   'Hristo',   'Lachezar',
   'Veselina', 'Tzvetan'
 ],
 'over40': [ 'Anton', 'Miroslava', 'Iliana' ]
}
*/

Create a deep copy of dt-object

const result = dt.query ( store => {
                               store.look ( ({ name, flatData, breadcrumbs, next }) => {
                                               store.set ( name, flatData )
                                               if ( breadcrumbs.includes('/') )   store.connect ([breadcrumbs])
                                               return next ()
                                        })
                        })
                    .model ( () => ({as:'std'}))
console.log ( result )
/** ->
 {
  school: [
    { name: 'Ivan', age: 14 },
    { name: 'Georgy', age: 15 },
    { name: 'Adi', age: 11 },
    { name: 'Kati', age: 11 }
  ],
  sports: [
    { name: 'Iva', age: 28 },
    { name: 'Stoyan', age: 36, sport: 'fencing' }
  ],
  work: [
    { name: 'Hristo', age: 38 },
    { name: 'Lachezar', age: 33 },
    { name: 'Veselina', age: 35 }
  ],
  recent: {
    classmates: [ { name: 'Anton', age: 42 }, { name: 'Miroslava', age: 42 } ],
    social: [ { name: 'Iliana', age: 61 }, { name: 'Tzvetan', age: 19 } ]
  }
}
 */

External Links

• DT-Queries. Some useful query functions for DT-Toolbox
• History of changes
• Migration guide
• Documentation v.4.x.x
• Documentation v.2.x.x

Credits

'dt-toolbox' was created and supported by Peter Naydenov.

License

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