dt-toolbox 5.0.0 → 7.0.0

package/README.md

@@ -1,24 +1,52 @@
-# DT Toolbox  
-*Note: Document is valid for v.5.x.x, v.4.x.x and v.3.x.x*
+# DT Toolbox v.7.x.x
 
-- [Documentation for old v.2.x.x is here](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.2.x.x.md)
+![version](https://img.shields.io/github/package-json/v/peterNaydenov/dt-toolbox)
+![license](https://img.shields.io/github/license/peterNaydenov/dt-toolbox)
 
-Execute operations over deep object structures without worries. Compare, modify, reshape or extract data. Immutability is taken as consideration by this library.
+ - [Documentatation for old v.6.x.x is here](htts://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.6.x.x.md)
 
-What you can do:
-  - Library knows some data-types and supports conversion among them;
-  - Modify objects: add/update/overwrite/insert/combine/append/prepend;
-  - Compare objects: identical/change/same/different/missing;
-  - Accumulative data selections: find/parent/folder;
-  - Accumulative filter selection: limit/keep/remove/deep;
-  - Extract and manipulate data chunks;
 
 
-## Installation
+## Breaking changes 
+* In version 7 look functions have 2 new arguments: Function `finish` and `next`;
+* Instead of returning a string 'next'(in version 6) to stop iteration on current dt-line, now you have to `return next()`;
+* Function `finish` is a new option. Call `return finish()` to stop iteration on all dt-lines;
+* Method `insert` was renamed to `insertSegment` to be clear that data is not mixed. Segments are separated peaces of data;
+
+
+
+## Other changes
+* Method `listSegments` was added to show list of all segments in dt-object;
+* Method `insertSegment` expect the incoming data as dt-object, but if is not - will assume it as a standard javascript object and will convert it to dt-object automatically;
+
+
+## Description
+
+DT-Toolbox is created to simplify the work with deep nested javascript objects. The library was created as an immutable data-storage(dt-object), internally 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 of the current dt-line;
+// edges: string[]. List of breadcrumbs of the related dt-lines;
+```
+
+This data-description is easy to read, saved, or transfered.
 
+
+## Installation
 Install for node.js projects by writing in your terminal:
+
 ```
-npm install dt-toolbox --save
+npm install dt-toolbox
 ```
 
 Once it has been installed, it can be used by writing this line of JavaScript:
@@ -28,458 +56,910 @@ import dtbox from 'dt-toolbox'
 
 
 
-## APIs Reference
+## 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. 
 
-Dtbox API methods with a short description:
+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
-const API = {
-    // DT I/O Operations
-		        init       : 'Convert any object to flat data-type'
-	        , load       : 'Load a flat data-type'
-          , loadFast   : 'Important! Method is depricated. Use load instead'
+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
+                        })
+        })
+```
 
-          , preprocess : 'Apply custom modifier to initial data.
-          , add        : 'Add data and keep existing data'
-          , update     : 'Updates only existing data fields'
-          , overwrite  : 'Add new data to DT object. Overwrite existing fields'
-          , insert     : 'Insert data on specified key, when the key represents an array'
-          , combine    : 'Combine values for simular keys in arrays'
-          , append     : 'Combine values for duplicated keys. main + update'
-          , prepend    : 'Combine values for duplicated keys. update + main'
-          , log        : 'Executes callback with errors list as argument'
-          , empty      : 'Empty object with export methods'
+Take a look on the library APIs and see the '**Examples**' section bellow.
 
-    // Provide Results      
-          , replace    : 'Get this._selection.result as a main data'
-          , attach     : 'Attach this._selection.result to the main data. Set point of connection'
-          , spread     : 'Returns result of selection in a calback function'
-          , spreadAll  : 'Select all and returns it with one command in a callback function'
-          , export     : 'Returns result of selection'
-          , exportAll  : 'Select all and returns it with one command'
+### dt-toolbox API Fast Reference
 
-    // Compare Operations
-         , identical  :  'Value compare. Reduce data to identical key/value pairs'
-         , change     :  'Value compare. Reduce to key/value pairs with different values'
-         , same       :  'Key compare. Returns key/value pairs where keys are the same'
-         , different  :  'Key compare. Returns key/value pairs where key does not exist'
-         , missing    :  'Key compare. Returns key/value pairs that are missing'
-    
-    // Selectors
-          , select     : 'Initialize a new selection'
-          , parent     : 'Selector. Apply conditions starting from parent level'
-          , find        : 'Selector. Fullfil select with list of arguments that contain specific string'
-          , all        : "Selector. Same as find ('root')"
-          , folder     : "Selector. Fullfil selection with 'midFlat' object props"
-          , space      : "Selector. Same as 'folder'"
-          , deepObject : "Selector. Fullfil '_select' with deepest object elements"
-          , deepArray  : "Selector. Fullfil '_select' with deepest array elements"
-          , invert     : 'Selector. Invert existing selection'
-          , assemble   : "Converts selection into 'array of objects' or 'single flat object'"
-          , purify     : 'Removes all empty structures ( no props ) from the selection'
+```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'
+```
 
-    // Filters      
-          , limit      : 'Filter.   Reduces amount of records in the selection'
-          , keep       : 'Filter.   Keeps records in selection if check function returns true'
-          , remove     : 'Filter.   Removes records from selection if check function returns true'
-          , deep       : "Filter.   Arguments ( num, direction - optional). Num mean level of deep. Deep '0' mean root members"
+### dt-object API Fast Reference
 
-    // Modifiers
-          , withData      : 'Generate "this._select.result" from the official data. Modifier will work with this data'
-          , withSelection : 'Generate "this._select.result" content. Modifier will work with this data'
-          , flatten        : 'Mix existing objects in a single object'
-          , mix           : 'Mix objects in order. Start with a host and provide guests list []'
-          , keyPrefix      : 'Modify key as object name+key. Separator-symbol default: emptySpace. It can be modified'
-          , reverse       : 'Change place of keys and values'
-}; // API   
+```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'
 ```
 
+### 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'
 
-# How it works?
+```
 
-1. First: Insert data in dt-toolbox. Use `load` for `flat` data-type or `init` for other data-types. Mix with other objects by using 'add/update/overwrite/combine' if you need. Use 'preprocess' to change data-type before assimilate it.
 
-2. Select! Without selection, dt-toolbox will return an empty object. Selection respresents the information that should be extracted from the data. Result of selectors is accumulative. Filters will be applied to already selected data.
 
-3. Spread/Export the result. Create new data structure according selection and provide it in required data-type.
+## DT Toolbox API
 
-DT Toolbox supports chaining syntax and is that simple. Let's see some examples...
+### 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.
 
-## Examples
+```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',
+    []
+  ]
+]
+ */
+
+```
 
-Here are some use cases, but if you're interested, test-cases are on your disposal. 
-### Basics
-Let's have a standard JS object:
+
+
+### dtbox.convert ()
+Direct convertion from model to model without creation of dt-object.
 
 ```js
-let st = {
-              name    : { 
-                            firstName  : 'Peter' 
-                          , surname : 'Naydenov'
-                        }
-            , friends : [ 'Tisho', 'Dibo', 'Ivo', 'Vasil' ]
-         }
 
+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'
+            }
+ */
 ```
-Put the **st** data into dt-toolbox:
+
+
+
+### dtbox.getWalk ()
+Dt-Toolbox is using "walk" library. If you need to use it directly - get the version used by Dt-Toolbox.
 
 ```js
-let dt = dtbox.init ( standard )
+const walk = dtbox.getWalk ();
+
 ```
 
-Internal representation of data is based on `flat` data-type. Type `flat` has two elements: value and structure.
-**Value** represents primitive values and their location. **Structure** represents existing flat objects and their relations.
-Our standard object inside the library will look like:
+
+
+
+
+## DT-object API
+
+
+### dt.insertSegment ()
+Extend the dt-object with a new data segment. Insertion should be provided as dt-object.
 
 ```js
-dt.structure = [
-              //   type      i   object descriptors [i, name]
-              [ 'object',    0,  [1, name], [2, friends]   ]  // Root object and relation with other objects
-            , [ 'object',    1   ]   // st.name object. Object has only primitive values.
-            , [ 'array' ,    2   ]   // st.friends array. Array has only primitive values.
+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.value = {    // Represents a primitive props and their location
-              'root/1/firstName'  : 'Peter'
-            , 'root/1/surname'   : 'Naydenov'
-            , 'root/2/0'         : 'Tisho'
-            , 'root/2/1'         : 'Dibo'
-            , 'root/2/2'         : 'Ivo'
-            , 'root/2/3'         : 'Vasil'
-        }
-}
+ */
 ```
 
-::: warning
-Internal representation is '*LIKE*' flat data-type but not the data-type itself. Type `flat` is array with two elements: structure and value `[structure, value]`. Internal representation has these two elements but they are like props. `dt = { structure, value }`.
-:::
 
 
+### dt.export ()
+Returns DT-model from dt-object.
 
-Extract a flat information:
 ```js
- dt.spreadAll ( 'flat', res => { 
-                        // Data-type 'Flat': An array with 2 entries: [structure, value] 
-                })
- // other way to receive same result:
- let myFlat = dt.exportAll ( 'flat' )
+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' ]}
+```
 
-Let's play with DT Toolbox:
 
+
+### 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
-let 
-    dtResult
-  , stResult
-  , friendList
-  ;
+  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.
+                }
+    }
+
+const result = dt.model ( modelFn, a,v,g ) // modelFn is the only required argument. All other arguments are optional.
 
-dtbox
-    .init(st) // Init data. Converts ST to DT
-    .select() // Starting new selection
-    .all()    // Select all data
-    .spread ( 'flat', dt => dtResult = dt   ) // Returns as `flat` data-type
-    .spread ( 'std', dt => stResult = dt   ) // Convert back to original 'st' object
-    .select () // Start new selection. Will remove previous selection.
-    .find ( 'friends' ) // select keys that contain 'friends'
-    .spread ( 'std', dt => friendList = dt ) //= { friends :[ 'Tisho', 'Dibo', 'Ivo', 'Vasil' ] }
-    .assemble ()
-    .spread ( 'std' => friendList = dt ) // = [ 'Tisho', 'Dibo', 'Ivo', 'Vasil' ]
-    // 'assemble' removes all duplicated elements in the keys and simplifies the result.
-    
 ```
 
-### Convert ST to DT objects
+### 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
-let result; 
-dtbox
-  .init(st)
-  .spreadAll ( 'flat', dt => result = dt );
+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
+    )
 ```
 
-### Mixing objects - Add/Update/Overwrite
 
-Add and update will consider existing data:
-- 'Add' method will be applied only for non-existing properties;
-- 'Update' method will works only on existing properties;
+### 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 ()
 
-Overwrite will 'add' and 'update'.
+Returns a list of all data segment names. Result is always an array with at least one element - 'root'.
 
 ```js
+dt.listSegments () 
+// [ 'root', 'extra' ]
+```
 
-let user = { 
-                name : 'Peter'
-              , age  : 42
-           }
 
-dtbox
-   .init ( user )
-   .add  ({
-                age : 25         // 'add' will ignore this. Age is already defined.
-              , gender : 'male'  // Will add this.
-          }, { type: 'std'})
-   .update ({
-               age  : 50         // Will update
-               eyes : 'blue'     // Will ignore this.
-          }, { type: 'std'})
-  .overwrite ({
-                age   : 43         // Will update
-              , hobby : 'skating'  // Will add
-          }, { type: 'std'})
 
-  // The object (dtbox.value) will look like:
-  /*
-    {
-        'root/0/name'   : 'Peter'
-      , 'root/0/age'    : 43
-      , 'root/0/gender' : 'male'
-      , 'root/0/hobby'  : 'skating'
-    }
 
-  /*
 
+
+
+## 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
+                                        })
+                    });
 ```
 
 
-### Parent
+### 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
+                                        })
+                    });
+```
 
-let result;
-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 }
-                ]
-    , '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 }
-                                 ]
-                 }
-  }
 
-// Let's create list of all contacts uder 40 years old:
-
-dtbox
-   .init ( data )
-   .select ()
-   .parent ( 'name', person => person.age < 40 )
-   .assemble ()
-   .spread ( 'std' , dt => result = dt   )
-
-/*
-   result will look like this:
-
-   [ 
-      { name: 'Tzvetan', age: 19 },
-      { name: 'Ivan', age: 14 },
-      { name: 'Iva', age: 28 },
-      { name: 'Hristo', age: 38 },
-      { name: 'Georgy', age: 15 },
-      { name: 'Stoyan', age: 36 },
-      { name: 'Lachezar', age: 33 },
-      { name: 'Adi', age: 11 },
-      { name: 'Veselina', age: 35 },
-      { name: 'Kati', age: 11 } 
-  ]
 
-*/
+
+
+### 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
+                                        })
+                    });
 ```
 
 
 
-### Purify
+### 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
+                                        })
+                    });
+```
 
-Cleaning empty structures till version 3 of the library was without alternative. Keep empty structures was recognized as a need and it's now a default behaviour. Remove empty structures by using 'purify' function as in this example:
+
+
+### store.like ()
+String search in dt-line name
 
 ```js
-const test = {
-                          name : 'Peter'
-                        , arr  : [ 1, 15 ]
-                        , de   : { me: ['eho', 'ha'] }
-                        , se   : { le: {} }
-                        , ze   : []
-                };
-    dtbox
-        .init ( test )
-        .select ()
-        .all ()
-        .purify ()
-        .spread ( 'std', x => {
-                            /** Result after purify will be:
-                             *   x = {
-                             *             name: Peter
-                             *           , arr  : [1,15]
-                             *           , de : { me: ['eho','ha']}
-                             *       }
-                            */
-                    })
-    }) // it purify
+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
+                                        })
+                    });
 ```
 
 
-## Data-types
 
-The library can spread data-selection as different data-types. Let's see how initial data will be interpreted in available data-types. Here is our initial `standard`(std) data:
+// DT-model structure and fields creation:
+### store.set ()
+Define new dt-line record
+
 ```js
 const data = {
-                      name: 'Peter'
-                    , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
-                    , shoes : {
-                                      winter : [ 'Keen', 'Head']
-                                    , summer : [ 'Lotto', 'Asics' ]
-                            }
+              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' ]
+                                        }
+                        }
             }
+ */
 ```
 
-### Standard ( std )
-Standard data-type will look exactly as initial data.
+
+
+### store.connect ()
+Creates a list of connections between two already existing dt-lines
+
 ```js
-{
-      name: 'Peter'
-    , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]
-    , shoes : {
-                  winter : [ 'Keen', 'Head']
-                , summer : [ 'Lotto', 'Asics' ]
-            }
-}
+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' ]
+    }
+ */ 
 ```
 
 
-### Flat ( shortFlat )
-It's a flat description of the object. It's an array with two elements. First element describes the structure of the object, second element - the values.
-**Structure**: Array of flatDescriptions. FlatDescription is array where first element is the type of the object (object or array), second is the index. If there are  more then 2 elements, we have connection descriptions. ConnectionDescription is array of 2 elements. First is the index of connected other object, second is the property name of the connection. 
- In our example: We have object, that have property `familyMembers` that is array and other property `shoes` that is an object. Object `shoes` have 2 properties (winter,summer) that are arrays.
- **Value**: Key describes the position of the property that have a primitive value. Value is just that primitive value. Key always have 3 elements separated by '/'. First element is always `root`, second is the `id` of the object (from structure description), third is the name of the property. If structure object is 'array' then property name will be a number representing the position into the array.
+
+### store.push ()
+Save a value to flatData of existing dt-line. FlatData should be an array.
+
 ```js
-[
-        // the structure description
-    [
-              [ 'object', 0, [1,'familyMembers'], [2,'shoes'] ]
-            , [ 'array' , 1 ]
-            , [ 'object', 2 , [3, 'winter'], [4, 'summer'] ]
-            , [ 'array' , 3 ]
-            , [ 'array' , 4 ]
-        ]
-        // the value description
-    , {
-              'root/0/name' : 'Peter'
-            , 'root/1/0'   : 'Veselina'
-            , 'root/1/0'   : 'Veselina'
-            , 'root/1/1'   : 'Iskra'
-            , 'root/1/2'   : 'Maria'
-            , 'root/1/3'   : 'Vasil'
-            , 'root/1/4'   : 'Vladimir'
-            , 'root/1/5'   : 'Petya'
-            , 'root/3/0'   : 'Keen'
-            , 'root/3/1'   : 'Head'
-            , 'root/4/0'   : 'Lotto'
-            , 'root/4/1'   : 'Asics'
-        }
-]
+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
-Object where keys represents "location" of the flat object. Value is always an object. Props are names. If data-structure is array, props are numbers:
+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' }
-    , 'root/familyMembers' : { 
-                                  '0' : 'Veselina'
-                                , '1' : 'Iskra'
-                                , '2' : 'Maria'
-                                , '3' : 'Vasil'
-                                , '4' : 'Vladimir'
-                                , '5' : 'Petya' 
-                        }
-    , 'root/shoes/winter' : {
-                                      '0' : 'Keen'
-                                    , '1' : 'Head'
-                                }
-    , 'root/shoes/summer' : {
-                                    '0' : 'Lotto'
-                                    '1' : 'Asics'
-                                }
+    , '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
 {
-      'root/name'            : 'Peter'
-    , 'root/familiMembers/0' : 'Veselina'
-    , 'root/familyMembers/1'  : 'Iskra'
-    , 'root/familyMembers/2'  : 'Maria'
-    , 'root/familyMembers/3'  : 'Vasil'
-    , 'root/familyMembers/4'  : 'Vladimir'
-    , 'root/familyMembers/5'  : 'Petya'
-    , 'root/shoes/winter/0'   : 'Keen'
-    , 'root/shoes/winter/1'   : 'Head'
-    , 'root/shoes/summer/0'   : 'Lotto'
-    , 'root/shoes/summer/1'   : 'Asics'
+      '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
 [
-      'root/name/Peter'
-    , 'root/familiMembers/Veselina'
-    , 'root/familyMembers/Iskra'
-    , 'root/familyMembers/Maria'
-    , 'root/familyMembers/Vasil'
-    , 'root/familyMembers/Vladimir'
-    , 'root/familyMembers/Petya'
-    , 'root/shoes/winter/Keen'
-    , 'root/shoes/winter/Head'
-    , 'root/shoes/summer/Lotto'
-    , 'root/shoes/summer/Asics'
+      '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.
@@ -487,7 +967,7 @@ Array of tuples. First element represents location + property name, second is th
 ```js
 [
       ['name', 'Peter' ]
-    , ['familiMembers', 'Veselina']
+    , ['familyMembers', 'Veselina']
     , ['familyMembers', 'Iskra']
     , ['familyMembers', 'Maria']
     , ['familyMembers', 'Vasil']
@@ -501,25 +981,195 @@ Array of tuples. First element represents location + property name, second is th
 ```
 
 
+## Examples
 
+### Find people under 40
 
+Find a people that are under 40 years old and provide the result as a list.
 
-## External Links
+```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
 - [Migration guide](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Migration.guide.md)
 - [History of changes](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Changelog.md)
+- [DT-Queries. Some useful query functions for DT-Toolbox](https://github.com/PeterNaydenov/dt-queries)
+- [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).