Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/peternaydenov/dt-toolbox
Data manipulation tool
https://github.com/peternaydenov/dt-toolbox
immutable model query-the-storage segments storage
Last synced: 4 days ago
JSON representation
Data manipulation tool
- Host: GitHub
- URL: https://github.com/peternaydenov/dt-toolbox
- Owner: PeterNaydenov
- License: mit
- Created: 2017-01-14T13:13:10.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-11-04T06:12:43.000Z (12 days ago)
- Last Synced: 2024-11-04T07:19:54.421Z (12 days ago)
- Topics: immutable, model, query-the-storage, segments, storage
- Language: JavaScript
- Homepage:
- Size: 588 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# DT Toolbox v.7.x.x
## Last Updates
- After version 7.4.2 - load the library with `require` or `import`. Folder '**dist**' contains the library in commonjs, esm and umd formats;
- 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:
```js
[ // 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](https://github.com/PeterNaydenov/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:
```js
// if you are using es6 modules:
import dtbox from 'dt-toolbox'
// if you are using commonjs:
const dtbox = require ( '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`:
```js
'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.
```js
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
```js
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
```js
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.
```js
// 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.
```js
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.
```js
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.
```js
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.
```js
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.
```js
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.
```js
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.
```js
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.
```js
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()**.
```js
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:
```js
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.
```js
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.
```js
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'.
```js
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.
```js
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.
```js
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).
```js
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.
```js
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.
```js
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
```js
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
```js
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
```js
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
```js
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.
```js
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.
```js
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.
```js
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:
```js
{
'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:
```js
{
'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.
```js
[
'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.
```js
[
['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.
```js
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.
```js
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.
```js
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
```js
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](https://github.com/PeterNaydenov/dt-queries)
- [History of changes](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Changelog.md)
- [Migration guide](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Migration.guide.md)
- [Documentation v.4.x.x](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.4.x.x.md)
- [Documentation v.2.x.x](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.2.x.x.md)
## Credits
'dt-toolbox' was created and supported by Peter Naydenov.
## License
'dt-toolbox' is released under the [MIT License](http://opensource.org/licenses/MIT).