dt-toolbox 6.0.0 → 7.0.0

package/Changelog.md

@@ -1,5 +1,16 @@
 ## Release History
 
+### 7.0.0 (2023-07-15)
+- [x] Method `look` has new arguments: functions `next` and `finish`;
+- [x] To stop iteration on current dt-line `return next()`;
+- [x] To stop iteration on all dt-lines `return finish()`;
+- [x] Method `insert` was renamed to `insertSegment`;
+- [x] Method `listSegments` was added to show list of all segments in dt-object;
+- [x] 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;
+- [] Method `insertSegment` can recognize a dt model object.
+
+
+
 ### 6.0.0 (2023-05-12)
 - [x] Version 5 is full rethinking of the idea and rewrite from scratch;
 - [x] Simplified API interface;
@@ -8,6 +19,8 @@
 - [x] Predefined and custom filters for faster data scan;
 - [x] Model and query functions to shape the results;
 
+
+
 ### 4.0.7 (2022-03-03)
 - [x] Library '@peter.naydenov/walk' was included as a dependency;
 - [x] Cleaning: Method 'help.generateObject' was removed. Not in use anymore;

package/Migration.guide.md

@@ -1,9 +1,58 @@
 # Migration Guides
 
+## From v.6.x.x  - v.7.x.x
+Look function can return `next` and `finish` functions. This functions are used to control the flow of the "**look**" function. If you `return next()`, the look function will continue to execute callback with next dt-line object. If you `return finish()`, the look function will end. 
 
-## From v.4.x.x  - v.5.x.x
 
-The library "dt-toolbox" exist for a full 7 years and now version 5 is coming as full rewrite of the original idea. Difference are more then similarity and better aproach is to read a version 5 documentation first. Then you will find that:
+```js
+// was:
+dt.query ( (store) => {
+    store.look ( ({name, flatData, breadcrumbs}) => {
+        if ( flatData.includes('something') ) {
+                // do something
+                // return string 'next' to stop iteration on this dt-line
+                return 'next'
+        }
+    })
+})
+
+// become:
+dt.query ( (store) => {
+    store.look ( ({name, flatData, breadcrumbs, next, finish}) => {
+        if ( flatData.includes('something') ) {
+                // do something
+                // return `next()` to stop iteration on current dt-line
+                return next ()
+                // return `finish()` to stop iteration on all dt-lines (it's a new option)
+        }
+    })
+})
+
+```
+
+Method `insert` was renamed to `insertSegment` to be clear that data is not mixed. Segments are separated peaces of data.
+
+```js 
+// before
+  const dt = dtbox.init ( a );
+  dt.insert ( 'specificDataName' b ) // b is a dt-object
+
+// after
+  const dt = dtbox.init ( a );
+  dt.insertSegment ( 'specificDataName' b ) // b is a dt-object
+// it's possible to insert a standard js object but it's not recomended
+// dt.insertSegment ( 'specialDataName', a )  // a is a standard js object
+// also possible to insert a dt model object directly
+// dt.insertSegment ( 'specialDataName', c )  // Where c = b.export(). A dt model object. 
+```
+
+Method `listSegments` was added to show list of all segments in dt-object.
+
+
+
+## From v.4.x.x  - v.6.x.x
+
+The library "dt-toolbox" exist for a full 7 years and now version 6 is coming as full rewrite of the original idea. Difference are more then similarity and better aproach is to read a version 6 documentation first. Then you will find that:
 
  - Data creation is very simular;
  - Dt-Object becomes a storage and you can add more data to it;

package/README.md

@@ -1,20 +1,27 @@
-# DT Toolbox v.6.x.x
+# DT Toolbox v.7.x.x
 
- - [Documentation for old v.4.x.x and 3.x.x is here](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.4.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)
 
+ - [Documentatation for old v.6.x.x is here](htts://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.6.x.x.md)
 
 
-## About version 6.x.x
-* Version 5 is full rethinking of the idea and rewrite from scratch;
-* Simplified API interface;
-* New internal data-model;
-* Multiple data inserts;
-* Predefined and custom filters for faster data scan;
-* Model and query functions to shape results;
 
+## 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?
@@ -37,6 +44,7 @@ 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
 ```
@@ -53,12 +61,12 @@ import dtbox from 'dt-toolbox'
 Use Dt-toolbox methods(init and load) to create a `dt-object`. 
 
 DT-object:
-- Provides multiple insertion of data chunks. Data from each insertion stays differentiated;
+- 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 insertions);
+- 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. 
@@ -70,7 +78,7 @@ Query functions are returning a **new instance of dt-object** with the result, c
   '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 insert'
+, '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
@@ -116,13 +124,14 @@ Take a look on the library APIs and see the '**Examples**' section bellow.
 ### dt-object API Fast Reference
 
 ```js
-    insert   : 'Inserts a new data in the dt-object. Insertion should be provided as dt-object.'
+    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
@@ -312,8 +321,8 @@ const walk = dtbox.getWalk ();
 ## DT-object API
 
 
-### dt.insert ()
-Extend the dt-object with a new data. Insertion should be provided as dt-object.
+### 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
@@ -331,10 +340,10 @@ const a = [ // it's a 'file' data-model
     ];
 const b = { shoes: [ 'Puma', 'UA' ]}
 const dt = dtbox.init ( a, { model : 'file' })  // create a dt-object
-dt.insert ( 
-         'extra' // object name
+dt.insertSegment ( 
+         'extra'        // object name
         , dtbox.init(b) // the extra object
-    ) // insert to 'dt' storage extra 
+    ) // insert to 'dt' storage data segment named 'extra' with data from 'b' object
 
 /**
    dt internal interpretation:
@@ -369,7 +378,7 @@ dt.insert (
             , 'root/shoes/summer' // -> location
             , [] // -> edges
         ]
-     // ---> Here are the elements that are coming from 'insert'   
+     // ---> 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
@@ -425,7 +434,7 @@ const
     , c = { vitamins : [ 'a', 'b', 'c' ]}
     , dt = dtbox.init ( b )
     ;
-dt.insert ( 'extra', c )
+dt.insertSegment ( 'extra', c )
 const deepCopy = dt.copy ()
 // it equal to: const deepCopy = dt.copy ('root')
 const onlyExtra = dt.copy ( 'extra' )
@@ -505,7 +514,14 @@ const [ name, flatData, breadcrumbs, edges ] = dt.index ( 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' ]
+```
 
 
 
@@ -547,11 +563,13 @@ const result = dt.query ( store => {
                                             , 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
+                                                        return next ()
+                                                        // unconditional `return next()` will executes the 'look' function once per dt-line
                                             })
                     })
 ```
@@ -578,10 +596,10 @@ const
     , res = dt.query ( store => {
                           store
                               .from ( 'root/personal/hobbies' )
-                              .look ( ({name}) => {
+                              .look ( ({name, next }) => {
                                                 console.log ( name )
                                                 // -> hobbies, music, sport
-                                                return 'next' // because we want to iterate once on each dt-line
+                                                return next () // because we want to iterate once on each dt-line
                                         })
                     });
 ```
@@ -593,7 +611,7 @@ 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 insert;
+ - 'root'        : Scan only root dt-lines of each data segment;
 
 If filter do not exist, look function will be executed on each dt-line.
 
@@ -616,10 +634,10 @@ const
     , res = dt.query ( store => {
                             store
                               .use ( 'object' )   // predefined filter 'object'
-                              .look ( ({name}) => {
+                              .look ( ({name, next }) => {
                                                 console.log ( name )
                                                 // -> root, personal, hobbies
-                                                return 'next' // because we want to iterate once on each dt-line
+                                                return next () // because we want to iterate once on each dt-line
                                         })
                     });
 ```
@@ -650,10 +668,10 @@ const
     , res = dt.query ( store => {
                             store
                               .get ( 'root/friends' )
-                              .look ( ({flatData}) => {
+                              .look ( ({ flatData, next }) => {
                                                 console.log ( flatData )
                                                 // -> [ 'Ivan', 'Dobroslav', 'Stefan' ]
-                                                return 'next' // because we want to iterate once on each dt-line
+                                                return next ()   // because we want to iterate once on each dt-line
                                         })
                     });
 ```
@@ -682,10 +700,10 @@ const
     , res = dt.query ( store => {
                             store
                               .find ( 'music' )
-                              .look ( ({flatData}) => {
+                              .look ( ({flatData, next }) => {
                                                 console.log ( flatData )
                                                 // -> [ 'punk', 'ska', 'metal', 'guitar' ]
-                                                return 'next' // because we want to iterate once on each dt-line
+                                                return next () // because we want to iterate once on each dt-line
                                         })
                     });
 ```
@@ -714,12 +732,12 @@ const
     , res = dt.query ( store => {
                             store
                               .like ( 'per' )
-                              .look ( ({flatData, breadcrumbs}) => {
+                              .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
+                                                return next ()   // because we want to iterate once on each dt-line
                                         })
                     });
 ```
@@ -1009,13 +1027,13 @@ const result = dt.query ( store => {
                             store.set ( 'root', [])  // setup a root array element
                             store
                                 .use ( 'listObject' ) // use only objects that are members of array
-                                .look ( ({ name, flatData }) => {
+                                .look ( ({ name, flatData, next }) => {
                                             if ( flatData.age < 40 ) {  
                                                     store.set ( i, flatData )
                                                     connectBuffer.push ( `root/${i}` )
                                                     i++
                                                 }
-                                            return 'next'
+                                            return next ()
                                         })
                             store.connect ( connectBuffer )
                     })
@@ -1044,9 +1062,9 @@ const result = dt.query ( store => {
                                 store.set ( 'root', [])
                                 store
                                    .use ( 'listObject' ) // use only objects that are members of array
-                                   .look ( ({ flatData }) => {
+                                   .look ( ({ flatData, next }) => {
                                                if ( flatData.age < 40 )   store.push ( 'root', flatData.name )
-                                               return 'next'
+                                               return next ()
                                            })
                     })
                  .model ( () => ({as:'std'})   )
@@ -1075,10 +1093,10 @@ Return an object with two groups
                                store.connect ([ 'root/under40', 'root/over40' ])
                                store
                                    .use ( 'listObject' ) // use only objects that are members of array
-                                   .look ( ({ flatData }) => {
+                                   .look ( ({ flatData, next }) => {
                                                let location = ( flatData.age > 40 ) ? 'over40' : 'under40';
                                                store.push ( location, flatData.name )
-                                               return 'next'
+                                               return next ()
                                            })
                        })
                      .model ( () => ({ as : 'std'}))
@@ -1102,10 +1120,10 @@ console.log ( result )
 
 ```js
 const result = dt.query ( store => {
-                               store.look ( ({ name, flatData, breadcrumbs }) => {
+                               store.look ( ({ name, flatData, breadcrumbs, next }) => {
                                                store.set ( name, flatData )
                                                if ( breadcrumbs.includes('/') )   store.connect ([breadcrumbs])
-                                               return 'next'
+                                               return next ()
                                         })
                         })
                     .model ( () => ({as:'std'}))
@@ -1141,6 +1159,7 @@ console.log ( result )
 ## 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)