{"id":19714382,"url":"https://github.com/peternaydenov/dt-toolbox","last_synced_at":"2025-08-17T20:11:26.539Z","repository":{"id":15893947,"uuid":"78941045","full_name":"PeterNaydenov/dt-toolbox","owner":"PeterNaydenov","description":"Data manipulation tool","archived":false,"fork":false,"pushed_at":"2025-08-07T04:51:45.000Z","size":803,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-07T06:28:59.577Z","etag":null,"topics":["immutable","model","query-the-storage","segments","storage"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PeterNaydenov.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-14T13:13:10.000Z","updated_at":"2025-08-07T04:51:48.000Z","dependencies_parsed_at":"2023-01-13T18:36:56.159Z","dependency_job_id":"9d1064e1-79c3-42bb-bb9d-34c28a45d54d","html_url":"https://github.com/PeterNaydenov/dt-toolbox","commit_stats":{"total_commits":203,"total_committers":2,"mean_commits":101.5,"dds":"0.40886699507389157","last_synced_commit":"cf9c58e6b664231b4a591955dbf190fc6880fba4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PeterNaydenov/dt-toolbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fdt-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fdt-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fdt-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fdt-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PeterNaydenov","download_url":"https://codeload.github.com/PeterNaydenov/dt-toolbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterNaydenov%2Fdt-toolbox/sbom","scorecard":{"id":109404,"data":{"date":"2025-08-11","repo":{"name":"github.com/PeterNaydenov/dt-toolbox","commit":"bce593ca9bea391afcfd209e8f4b510d8eda17d8"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":9,"reason":"11 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-15T11:45:33.181Z","repository_id":15893947,"created_at":"2025-08-15T11:45:33.181Z","updated_at":"2025-08-15T11:45:33.181Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270899582,"owners_count":24664720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["immutable","model","query-the-storage","segments","storage"],"created_at":"2024-11-11T22:31:21.776Z","updated_at":"2025-08-17T20:11:26.517Z","avatar_url":"https://github.com/PeterNaydenov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DT Toolbox v.7.x.x\n\n![version](https://img.shields.io/github/package-json/v/peterNaydenov/dt-toolbox)\n![license](https://img.shields.io/github/license/peterNaydenov/dt-toolbox)\n![npm](https://img.shields.io/npm/dt/dt-toolbox)\n![issues](https://img.shields.io/github/issues/peterNaydenov/dt-toolbox)\n![language](https://img.shields.io/github/languages/top/peterNaydenov/dt-toolbox)\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/peterNaydenov/dt-toolbox)\n![npm bundle size](https://img.shields.io/bundlephobia/min/dt-toolbox)\n\n\n\n\n## Last Updates\n- After version 7.4.2 - load the library with `require` or `import`. Folder '**dist**' contains the library in commonjs, esm and umd formats;\n- After version 7.3.0 extractList options.as can receive a `dt-model` and `dt-object`;\n- 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.\n\n\n\n## Description\n\nDT-Toolbox is a tool, created to simplify the work with deep nested javascript objects. \nThe library creates an immutable data-storage(dt-object). Storage data representation is based on data-model called `DT-model`.\n\n ## What is DT-model?\nIt's an internal 'dt-object' data description. Data is an array of lines where each line has 4 components:\n```js\n[ // dt-model\n [ name, flatData, breadcrumbs, edges ] // dt-line\n , [ name, flatData, breadcrumbs, edges ] // dt-line\n // ...\n]\n// Where -\u003e\n// name: string. Name of the dt-line;\n// flatData: object or array of primitive types;\n// breadcrumbs: string. Bredcrumbs description(identifier) of the current dt-line;\n// edges: string[]. List of breadcrumbs of the related dt-lines(children);\n```\n\nThis data-description is easy to read, saved, or transfered.\n\nDT-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.\n\nConcept `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).\n\nThere is a library [@peter.naydenov/dt-queries](https://github.com/PeterNaydenov/dt-queries) that contains query functions that can be useful with data manipulation:\n- splitSegments: Splits a solid data into multiple data-segments;\n- joinSegments : Consolidate multiple data-segments in a single solid data;\n- updateState : Updates the state with new data. Takes only declared data-segments and root data properties;\n\n\n## Installation\nInstall for node.js projects by writing in your terminal:\n\n```\nnpm install dt-toolbox\n```\n\nOnce it has been installed, it can be used by writing this line of JavaScript:\n```js\n// if you are using es6 modules:\nimport dtbox from 'dt-toolbox'\n// if you are using commonjs:\nconst dtbox = require ( 'dt-toolbox' );\n```\n\n\n\n## How it works?\n\nUse Dt-toolbox methods(init and load) to create a `dt-object`. \n\nDT-object:\n- Provides multiple insertion of data-segments. Data from each insertion stays differentiated;\n- Has prebuilded filters for fast search of data;\n- Can create and register a customized filters for fast search of data;\n- Can apply `query functions` to find, extract and reshape the data;\n- Can apply `model function` to reshape the final result;\n- Can executes 'query' and 'model' function over all available data in the storage (All data segments);\n- Execution of query/model functions will not change anything inside the host dt-object;\n\nThe **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. \n\nQuery functions are returning a **new instance of dt-object** with the result, created by dt-storage. Remember - **data inside dt-object never get modified**.\n\n**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`:\n```js\n 'list' : 'Scan only dt-lines where flatData is an array'\n, 'listObject' : 'Scan objects that are members of array'\n, 'object' : 'Scan just dt-lines where flatData is an object'\n, 'root' : 'Scan only root dt-lines of each data segment'\n```\nFilters 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.\n```js\nfunction findBlueEyesFn ({ // We have named arguments\n name // Name of dt-line\n , flatData // The data. Flat object or array\n , breadcrumbs // Location description\n , edges // List of breadcrumbs related to this dt-line\n }) {\n if ( flatData.eyes === 'blue' ) return true // confirm that dt-line should be in that filter list \n return false // ignore this dt-line\n }\n\n // Register a filter to some dt-object:\n dt.setupFilter ( \n 'blueEyes' // filter name\n , findBlueEyesFn // provide a filter function\n )\n// Filter function will be executed on each dt-line to create a filter scan-list\n\n // Using the filter during execution of query/model functions:\n dt.query ( store =\u003e {\n store\n .use ( 'blueEyes' ) // Set the name of the filter \n .look ( ({}) =\u003e {\n // ... will scan only dt-lines selected by filter\n })\n })\n```\n\nTake a look on the library APIs and see the '**Examples**' section bellow.\n\n### dt-toolbox API Fast Reference\n\n```js\n init : 'Create a new dt-object from data that is not a DT-model and needs a convertion'\n , load : 'Create a new dt-object from data that is a DT-model'\n , flat : 'Convert a data to DT-model without creation of dt-object'\n , convert : 'Direct convertion from model to model without creation of dt-object'\n , getWalk : 'Returns a instance of \"walk\" library'\n```\n\n### dt-object API Fast Reference\n\n```js\n insertSegment : 'Inserts a new data-segment in the dt-object. Insertion should be provided as a dt-object.'\n , 'export' : 'Returns the DT-model from dt-object - part or full'\n , copy : 'Creates a copy of original provided data'\n , query : 'Executes a \"query\" function on the dt-object. Returns a new dt-object with the result'\n , model : 'Executes a \"model\" function on the dt-object. Returns a data model'\n , 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'\n , index : 'Provides a copy of specified dt-line by breadcrumbs'\n , listSegments : 'Returns a list of all segments in dt-object'\n , extractList : 'Extracts a list of segments and/or properties from dt-object'\n```\n\n### dt-storage API Fast Reference\n\nObject `dt-storage` is available as argument to '**query**' and '**model**' functions. Methods of \n'dt-storage' can scan DT-model for data and build a new DT-model structure and fields. \n\n*Important*: Result of building a DT-model returns as a separate dt-object and will not modify anything inside actual dt-object.\n\n```js\n // Scan methods\n, from : 'Scan deeper from specified dt-line by location(breadcrumbs)'\n, use : 'Use filter name to execute `look` on shorter list of dt-lines.'\n, get : 'Take a single dt-line with specific breadcrumbs'\n, find : 'String search for exact object name'\n, like : 'String search in dt-line name'\n, look : 'Executes on each object property in the selection list'\n\n// DT-model structure and fields creation:\n set : 'Define new dt-line record'\n, connect : 'Creates a list of connections between two already existing dt-lines'\n, save : 'Save a property to flatData object in existing dt-line'\n, push : 'Save a value to flatData array of existing dt-line'\n\n```\n\n\n\n## DT Toolbox API\n\n### dtbox.init ()\nCreate 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.\n\n```js\nconst data = { // Standard JS object\n name: 'Peter'\n , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]\n , shoes : {\n winter : [ 'Keen', 'Head']\n , summer : [ 'Lotto', 'Asics' ]\n }\n };\n\nconst midData = { // Midflat model object\n 'root' : { name: 'Peter' }\n , 'familyMembers' : ['Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]\n , 'shoes/winter' : [ 'Keen', 'Head' ]\n , 'shoes/summer' : [ 'Lotto', 'Asics' ] \n }\n\n const dtS = dtbox.init ( data ) // Creates dt-object from 'standard'(std) data-model\n // it's equal to this: const dtS = dtbox.init ( data, { model:'std' })\n const dtMid = dtbox.init ( midData, { model : 'midFlat' }) // Creates a dt-object from midFlat data.\n```\n\n\n\n### dtbox.load ()\nCreate a new dt-object from data that is a DT-model.\n\n```js\nconst dtData = [\n [\n 'root',\n { city: 'Varna', desc: 'Big city on the Black-sea seaside' },\n 'root',\n [ 'root/location', 'root/extra' ]\n ],\n [\n 'location',\n { continent: 'Europe', country: 'Bulgaria' },\n 'root/location',\n []\n ],\n [\n 'extra',\n { port: 'Yes', airport: 'Yes' },\n 'root/extra',\n [ 'root/extra/nearTo' ]\n ],\n [\n 'nearTo',\n [ 'Burgas', 'Shumen', 'Dobrich' ],\n 'root/extra/nearTo',\n []\n ]\n];\n\nconst dtStore = dtbox.load ( dtData ); // Load DT-model data to dt-object\n```\n\n\n\n### dtbox.flat ()\nConvert a data to DT-model without creation of dt-object.\n\n```js\nconst a = {\n city : 'Varna'\n , desc: 'Big city on the Black-sea seaside'\n , location : {\n continent: 'Europe'\n , country : 'Bulgaria'\n \n }\n , extra : {\n port : 'Yes'\n , airport : 'Yes'\n , 'nearTo' : [ 'Burgas', 'Shumen', 'Dobrich' ]\n }\n};\n\nconst inFlatModel = dtbox.flat ( a ) // Default data-model is set to 'standard'(std)\n// it's equal to: const inFlatModel = dtbox.flat ( a, {model: 'std'})\n/**\n * inFlatModel = [\n [\n 'root',\n { city: 'Varna', desc: 'Big city on the Black-sea seaside' },\n 'root',\n [ 'root/location', 'root/extra' ]\n ],\n [\n 'location',\n { continent: 'Europe', country: 'Bulgaria' },\n 'root/location',\n []\n ],\n [\n 'extra',\n { port: 'Yes', airport: 'Yes' },\n 'root/extra',\n [ 'root/extra/nearTo' ]\n ],\n [\n 'nearTo',\n [ 'Burgas', 'Shumen', 'Dobrich' ],\n 'root/extra/nearTo',\n []\n ]\n]\n */\n\n```\n\n\n\n### dtbox.convert ()\nDirect convertion from model to model without creation of dt-object.\n\n```js\n\nlet result = dtbox.convert ( a, {\n model : 'std' // Model: Source data-model\n , as : 'breadcrumbs' // as: Convert data to this data-model\n })\n\n/** \n result = {\n 'city': 'Varna'\n , 'desc': 'Big city on the Black-sea seaside'\n , 'location/continent': 'Europe'\n , 'location/country': 'Bulgaria'\n , 'extra/port': 'Yes'\n , 'extra/airport': 'Yes'\n , 'extra/nearTo/0': 'Burgas'\n , 'extra/nearTo/1': 'Shumen'\n , 'extra/nearTo/2': 'Dobrich'\n }\n */\n```\n\n\n\n### dtbox.getWalk ()\nDt-Toolbox is using \"walk\" library. If you need to use it directly - get the version used by Dt-Toolbox.\n\n```js\nconst walk = dtbox.getWalk ();\n\n```\n\n\n\n\n\n## DT-object API\n\n\n### dt.insertSegment ()\nExtend the dt-object with a new data segment. Insertion should be provided as dt-object.\n\n```js\nconst a = [ // it's a 'file' data-model\n 'name/Peter'\n , 'familyMembers/Veselina'\n , 'familyMembers/Iskra'\n , 'familyMembers/Maria'\n , 'familyMembers/Vasil'\n , 'familyMembers/Vladimir'\n , 'familyMembers/Petya'\n , 'shoes/winter/Keen'\n , 'shoes/winter/Head'\n , 'shoes/summer/Lotto'\n , 'shoes/summer/Asics'\n ];\nconst b = { shoes: [ 'Puma', 'UA' ]}\nconst dt = dtbox.init ( a, { model : 'file' }) // create a dt-object\ndt.insertSegment ( \n 'extra' // object name\n , dtbox.init(b) // the extra object\n ) // insert to 'dt' storage data segment named 'extra' with data from 'b' object\n\n/**\n dt internal interpretation:\n[\n [ \n 'root' // -\u003e dt-line name\n , {name:'Peter'} // -\u003e flatData\n , 'root' // -\u003e location. For top element of each data segment breadcrumbs === name\n , [ 'root/familyMembers', 'root/shoes' ] // -\u003e edges\n ]\n , [ \n 'familyMembers' // -\u003e dt-line name\n , [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ] // -\u003e flatData\n , 'root/familyMembers' // -\u003e location\n , [] // -\u003e edges\n ]\n , [\n 'shoes' // -\u003e dt-line name\n , {} // -\u003e flatData\n , 'root/shoes' // -\u003e location\n , [ 'root/shoes/winter', 'root/shoes/summer' ] // -\u003e edges\n ]\n , [\n 'winter' // -\u003e dt-line name\n , [ 'Keen', 'Head' ] // -\u003e flatData\n , 'root/shoes/winter' // -\u003e location\n , [] // -\u003e edges\n ]\n , [\n 'summer' // -\u003e dt-line name\n , [ 'Lotto', 'Asics' ] // -\u003e flatData\n , 'root/shoes/summer' // -\u003e location\n , [] // -\u003e edges\n ]\n // ---\u003e Here are the elements that are coming from 'insertSegment' \n , [\n 'extra' // -\u003e dt-line name. Object name of insert will become root element for data segment.\n , {} // -\u003e flatData\n ,'extra' // -\u003e location. For top element of each data segment breadcrumbs === name\n , [ 'extra/shoes' ] // -\u003e edges\n ]\n , [\n 'shoes' // -\u003e dt-line name\n , [ 'Puma', 'UA'] // -\u003e flatData\n , 'extra/shoes' // -\u003e location\n , [] // -\u003e edges\n ]\n]\n\n */\n```\n\n\n\n### dt.export ()\nReturns DT-model from dt-object.\n\n```js\nconst all = dt.export () // will return all data from the storage\nconst root = dt.export ( 'root' ) // will return only initial data segment\nconst extra = dt.export ( 'extra' ) // will return only 'extra' data segment\n/**\n extra = [\n , [\n 'root' // -\u003e dt-line name was changed to 'root'. Name 'extra' has meaning just inside dt-object\n , {} // -\u003e flatData\n ,'root' // -\u003e location. For top element of each data segment breadcrumbs === name\n , [ 'root/shoes' ] // -\u003e edges\n ]\n , [\n 'shoes' // -\u003e dt-line name\n , [ 'Puma', 'UA'] // -\u003e flatData\n , 'root/shoes' // -\u003e location\n , [] // -\u003e edges\n ]\n ]\n */\n\n```\n\n\n### dt.copy ()\nDuring the initialization process `dt-object` will save a deep copy of original data inside and can provide a deep copy in any time.\nFunction `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.\n```js\nconst \n b = { shoes: [ 'Puma', 'UA' ]}\n , c = { vitamins : [ 'a', 'b', 'c' ]}\n , dt = dtbox.init ( b )\n ;\ndt.insertSegment ( 'extra', c )\nconst deepCopy = dt.copy ()\n// it equal to: const deepCopy = dt.copy ('root')\nconst onlyExtra = dt.copy ( 'extra' )\n// onlyExtra = { vitamins : [ 'a', 'b', 'c' ]}\n```\n\n\n\n### dt.query ()\nExecutes 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()**.\n```js\n function queryFn ( store, a, b ) { // optional arguments will come directly after 'store' api\n // ... body of queryFn\n }\n const dtOther = dt.query ( queryFn, a, b ) // queryFn is required arguments. All other arguments are optional\n```\n\n\n### dt.model ()\nExecutes 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: \n```js\nfunction modelFn ( store, a,v,g ) { // optional arguments will come directly after 'store' api\n // ... body of modelFn\n // to convert result in some of predefined and supported models, function should return an object\n return {\n as : 'std' // property 'as' will execute final conversion. Model name should be from supported list of the library.\n }\n }\n// Supported model-names are:\n// 'standard', 'std', 'midFlat', 'tuple', 'tuples', 'breadcrumb', 'breadcrumbs'\n\nconst result = dt.model ( modelFn, a,v,g ) // modelFn is the only required argument. All other arguments are optional.\n```\n\n### dt.setupFilter ()\nEvaluate 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. \n\n```js\nfunction blueFn ({\n name // Name of dt-line\n , flatData // The flat data\n , breadcrumbs // Location description\n , edges // List of breadcrumbs related to this dt-line\n }) {\n if ( flatData.hasOwnProperty('eyes') \u0026\u0026 flatData.eyes === 'blue' ) return true // confirm that dt-line should be in that filter list \n return false // ignore this dt-line\n // dt-lines that are \n}\n\ndt.setupFilter (\n 'blue' // Name of the filter\n , blueFn // Provide a filter function\n )\n```\n\n\n### dt.index ()\nProvides a copy of specified by breadcrumbs DT-line.\n```js\nconst br = 'root/friends'\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n }\nconst [ name, flatData, breadcrumbs, edges ] = dt.index ( br )\n// name = friends\n// flatData = [ 'Ivan', 'Dobroslav', 'Stefan' ]\n// breadcrumbs === br\n// edges === []\n```\n\n### dt.listSegments ()\n\nReturns a list of all data segment names. Result is always an array with at least one element - 'root'.\n\n```js\ndt.listSegments () \n// [ 'root', 'extra' ]\n```\n\n### dt.extractList ()\n\nAfter 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. \n\nIf requested segment or property is not available, response will be '**null**'.\nSegments have priority over properties. If there is a segment with the same name as a property, segment will be extracted.\n\n```js\nconst \n first = { name: 'first', data: 'first data' }\n , second = { name: 'second', data: 'second data' }\n , third = { name: 'third', data: 'third data' }\n ;\nconst storage = dtbox.init ( first ); // first will become a root segment\nstorage.insertSegment ( 'second', second );\nstorage.insertSegment ( 'third', third );\n\nconst [ a, b c, firstData, otherData ] = storage.extractList ( ['first', 'second', 'third', 'data', 'secondData' ], { as: 'std' } ));\n// a -\u003e { name: 'first', data: 'first data' }\n// b -\u003e { name: 'second', data: 'second data' }\n// c -\u003e { name: 'third', data: 'third data' }\n// firstData -\u003e 'first data' // Field 'data' from main dt-line of 'root' segment.\n// otherData -\u003e null // There is no 'secondData' in 'root' segment. No segment 'secondData' as well.\n```\n\n\n\n\n\n\n## DT-store API\n\nAs we already mentioned, store is available in query/model functions and coming as the first argument.\n\n### store.look ()\nFunction that will be executed on each object key/value from the selection list. \nIf selection is not explicitly mentioned, executes function on each dt-line data segments.\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst dt = dtbox.init ( data );\n\nconst result = dt.query ( store =\u003e {\n // Direct call of look on store will be executed on each dt-line\n store.look ( ({ // Named arguments. All available argument-names are listed here:\n value \n , key\n , name // dt-line name;\n , flatData // full flatData for specified dt-line;\n , breadcrumbs // breadcrumbs for dt-line;\n , links // List of tuples [[parent, child],...]. Parent and child are the dt-line names;\n , empty // Will present only if object has no properties. Empty flatData for dt-line.\n , next // Function that can be returned to move to next dt-line\n , finish // Function that can be returned to stop execution of look function\n }) =\u003e {\n //... body of look function\n // Move fast to next dt-line by returning a string 'next'\n return next ()\n // unconditional `return next()` will executes the 'look' function once per dt-line\n })\n })\n```\n\n### store.from ()\nScan deeper from specified dt-line by location(breadcrumbs). \n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst \n dt = dtbox.init ( data )\n , res = dt.query ( store =\u003e {\n store\n .from ( 'root/personal/hobbies' )\n .look ( ({name, next }) =\u003e {\n console.log ( name )\n // -\u003e hobbies, music, sport\n return next () // because we want to iterate once on each dt-line\n })\n });\n```\n\n\n### store.use ()\nUse filter to execute `look` on shorter list of dt-lines. Use the predefined or your own filters.\nList of predefined filters:\n - 'list' : Scan only dt-lines where flatData is an array;\n - 'listObject' : Scan objects that are members of array;\n - 'object' : Scan just dt-lines where flatData is an object;\n - 'root' : Scan only root dt-lines of each data segment;\n\nIf filter do not exist, look function will be executed on each dt-line.\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst \n dt = dtbox.init ( data )\n , res = dt.query ( store =\u003e {\n store\n .use ( 'object' ) // predefined filter 'object'\n .look ( ({name, next }) =\u003e {\n console.log ( name )\n // -\u003e root, personal, hobbies\n return next () // because we want to iterate once on each dt-line\n })\n });\n```\n\n\n\n\n\n### store.get ()\nTake a single dt-line with specific breadcrumbs.\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst \n dt = dtbox.init ( data )\n , res = dt.query ( store =\u003e {\n store\n .get ( 'root/friends' )\n .look ( ({ flatData, next }) =\u003e {\n console.log ( flatData )\n // -\u003e [ 'Ivan', 'Dobroslav', 'Stefan' ]\n return next () // because we want to iterate once on each dt-line\n })\n });\n```\n\n\n\n### store.find ()\nString search for exact object name\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst \n dt = dtbox.init ( data )\n , res = dt.query ( store =\u003e {\n store\n .find ( 'music' )\n .look ( ({flatData, next }) =\u003e {\n console.log ( flatData )\n // -\u003e [ 'punk', 'ska', 'metal', 'guitar' ]\n return next () // because we want to iterate once on each dt-line\n })\n });\n```\n\n\n\n### store.like ()\nString search in dt-line name\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst \n dt = dtbox.init ( data )\n , res = dt.query ( store =\u003e {\n store\n .like ( 'per' )\n .look ( ({flatData, breadcrumbs, next }) =\u003e {\n console.log ( flatData )\n // -\u003e { age: 49, eyes: 'blue' }\n console.log ( breadcrumbs )\n // -\u003e 'root/personal'\n return next () // because we want to iterate once on each dt-line\n })\n });\n```\n\n\n\n// DT-model structure and fields creation:\n### store.set ()\nDefine new dt-line record\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n };\nconst dt = dtbox.init ( data );\n\nconst result = dt\n .query ( store =\u003e {\n store.set ( 'root', [2,4,15]) // new dt-line structure was created\n })\n .model ( () =\u003e ({as:'std'}) )\nconsole.log ( result )\n// -\u003e [2,4,15]\n\nconst result2 = dt\n .query ( store =\u003e {}) // If there is no new dt-line, query will return itself\n .model ( () =\u003e ({as:'std'}) )\nconsole.log ( result2 )\n/**\n {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n , personal : {\n age : 49\n , eyes : 'blue'\n , sizes : [ 10, 44, 'm', 'mid' ]\n , hobbies : { \n music : [ 'punk', 'ska', 'metal', 'guitar' ]\n , sport : [ 'fencing', 'skating', 'ski' ]\n }\n }\n }\n */\n```\n\n\n\n### store.connect ()\nCreates a list of connections between two already existing dt-lines\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n };\nconst \n dt = dtbox.init ( data )\n , result = dt\n .query ( store =\u003e {\n store.set ( 'root', { name: Stefan })\n store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )\n store.connect (['root/friends'])\n })\n .model ( () =\u003e ({as:'std'}))\n ;\nconsole.log ( result )\n/**\n { \n name: Stefan\n , friends: ['Stefan', 'Tommy', 'Maria' ]\n }\n */ \n```\n\n\n\n### store.save ()\nSave a property to flatData object in existing dt-line.\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n };\nconst \n dt = dtbox.init ( data )\n , result = dt\n .query ( store =\u003e {\n store.set ( 'root', { name: Stefan })\n store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )\n store.connect (['root/friends'])\n store.save ( 'root', 'age', 35 )\n })\n .model ( () =\u003e ({as:'std'}))\n ;\nconsole.log ( result )\n/**\n { \n name: Stefan\n , age : 35\n , friends: ['Stefan', 'Tommy', 'Maria' ]\n }\n */ \n```\n\n\n\n### store.push ()\nSave a value to flatData of existing dt-line. FlatData should be an array.\n\n```js\nconst data = {\n name: 'Peter'\n , friends : [ 'Ivan', 'Dobroslav', 'Stefan' ]\n };\nconst \n dt = dtbox.init ( data )\n , result = dt\n .query ( store =\u003e {\n store.set ( 'root', { name: Stefan })\n store.set ( 'friends', [ 'Stefan', 'Tommy', 'Maria'] )\n store.connect (['root/friends'])\n store.push ( 'friends', 'Lily' )\n })\n .model ( () =\u003e ({as:'std'}))\n ;\nconsole.log ( result )\n/**\n { \n name: Stefan\n , friends: ['Stefan', 'Tommy', 'Maria', 'Lily' ]\n }\n */ \n```\n\n\n\n\n\n\n\n\n\n\n## Init/Export Data-Models\nThe library has some predefined data-models and can read and convert data among them. \n\n### Standard ( std )\nStandard data model is a standard deep javascript object.\n```js\nconst data = {\n name: 'Peter'\n , familyMembers : [ 'Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]\n , shoes : {\n winter : [ 'Keen', 'Head']\n , summer : [ 'Lotto', 'Asics' ]\n }\n }\n```\n\n### MidFlat\nIt's a two level deep javascript object. First object properties represent the location of the data, value is a flat object or array:\n\n```js\n{\n 'root' : { name: 'Peter' }\n , 'familyMembers' : ['Veselina', 'Iskra', 'Maria', 'Vasil', 'Vladimir', 'Petya' ]\n , 'shoes/winter' : [ 'Keen', 'Head' ]\n , 'shoes/summer' : [ 'Lotto', 'Asics' ] \n}\n```\n\n\n\n### Breadcrumbs\nIt's a flat interpratation of the data and looks like this:\n\n```js\n{\n 'name' : 'Peter'\n , 'familyMembers/0' : 'Veselina'\n , 'familyMembers/1' : 'Iskra'\n , 'familyMembers/2' : 'Maria'\n , 'familyMembers/3' : 'Vasil'\n , 'familyMembers/4' : 'Vladimir'\n , 'familyMembers/5' : 'Petya'\n , 'shoes/winter/0' : 'Keen'\n , 'shoes/winter/1' : 'Head'\n , 'shoes/summer/0' : 'Lotto'\n , 'shoes/summer/1' : 'Asics'\n}\n```\n\n### Files\nData is interpreted like file/folder description.\n\n```js\n[\n 'name/Peter'\n , 'familyMembers/Veselina'\n , 'familyMembers/Iskra'\n , 'familyMembers/Maria'\n , 'familyMembers/Vasil'\n , 'familyMembers/Vladimir'\n , 'familyMembers/Petya'\n , 'shoes/winter/Keen'\n , 'shoes/winter/Head'\n , 'shoes/summer/Lotto'\n , 'shoes/summer/Asics'\n]\n```\n\n### Tuples\n\nArray of tuples. First element represents location + property name, second is the value.\n\n```js\n[\n ['name', 'Peter' ]\n , ['familyMembers', 'Veselina']\n , ['familyMembers', 'Iskra']\n , ['familyMembers', 'Maria']\n , ['familyMembers', 'Vasil']\n , ['familyMembers', 'Vladimir']\n , ['familyMembers', 'Petya']\n , ['shoes/winter' , 'Keen']\n , ['shoes/winter' , 'Head']\n , ['shoes/summer' , 'Lotto']\n , ['shoes/summer' , 'Asics']\n]\n```\n\n\n## Examples\n\n### Find people under 40\n\nFind a people that are under 40 years old and provide the result as a list.\n\n```js\nlet data = {\n 'school' : [\n { name: 'Ivan', age: 14 }\n , { name: 'Georgy', age: 15 }\n , { name: 'Adi', age: 11 }\n , { name: 'Kati', age: 11 }\n ]\n , 'sports' : [\n { name: 'Iva', age: 28 }\n , { name: 'Stoyan', age: 36, sport: 'fencing' }\n ]\n , 'work' : [\n { name: 'Hristo', age: 38 }\n , { name: 'Lachezar', age: 33 }\n , { name: 'Veselina', age: 35 }\n \n ]\n , 'recent' : {\n 'classmates' : [\n { name: 'Anton', age: 42 }\n , { name: 'Miroslava', age: 42 }\n ]\n , 'social' : [\n { name: 'Iliana', age: 61 }\n , { name: 'Tzvetan', age: 19 }\n ]\n }\n }\n\nconst dt = dtbox.init ( data ); // creates a dt-object\n\nconst result = dt.query ( store =\u003e {\n let \n i = 0\n , connectBuffer = []\n ;\n store.set ( 'root', []) // setup a root array element\n store\n .use ( 'listObject' ) // use only objects that are members of array\n .look ( ({ name, flatData, next }) =\u003e {\n if ( flatData.age \u003c 40 ) { \n store.set ( i, flatData )\n connectBuffer.push ( `root/${i}` )\n i++\n }\n return next ()\n })\n store.connect ( connectBuffer )\n })\n .model ( () =\u003e ({ as : 'std'}))\nconsole.log ( result )\n/** -\u003e\n [\n { name: 'Ivan', age: 14 },\n { name: 'Georgy', age: 15 },\n { name: 'Adi', age: 11 },\n { name: 'Kati', age: 11 },\n { name: 'Iva', age: 28 },\n { name: 'Stoyan', age: 36, sport: 'fencing' },\n { name: 'Hristo', age: 38 },\n { name: 'Lachezar', age: 33 },\n { name: 'Veselina', age: 35 },\n { name: 'Tzvetan', age: 19 }\n] \n*/ \n```\n### Provide just a list of names\nUse the same data from previous example but return only the list of names.\n\n```js\nconst result = dt.query ( store =\u003e {\n store.set ( 'root', [])\n store\n .use ( 'listObject' ) // use only objects that are members of array\n .look ( ({ flatData, next }) =\u003e {\n if ( flatData.age \u003c 40 ) store.push ( 'root', flatData.name )\n return next ()\n })\n })\n .model ( () =\u003e ({as:'std'}) )\nconsole.log ( result )\n/** -\u003e\n [\n 'Ivan', 'Georgy',\n 'Adi', 'Kati',\n 'Iva', 'Stoyan',\n 'Hristo', 'Lachezar',\n 'Veselina', 'Tzvetan'\n]\n */\n```\n\n### Organize people in two groups\nReturn an object with two groups\n - 'over40' \n - 'under40'\n Provide only the names.\n ```js\n const result = dt.query ( store =\u003e {\n store.set ( 'root', {} )\n store.set ( 'under40', [])\n store.set ( 'over40' , [])\n store.connect ([ 'root/under40', 'root/over40' ])\n store\n .use ( 'listObject' ) // use only objects that are members of array\n .look ( ({ flatData, next }) =\u003e {\n let location = ( flatData.age \u003e 40 ) ? 'over40' : 'under40';\n store.push ( location, flatData.name )\n return next ()\n })\n })\n .model ( () =\u003e ({ as : 'std'}))\nconsole.log ( result )\n/** -\u003e\n {\n 'under40': [\n 'Ivan', 'Georgy',\n 'Adi', 'Kati',\n 'Iva', 'Stoyan',\n 'Hristo', 'Lachezar',\n 'Veselina', 'Tzvetan'\n ],\n 'over40': [ 'Anton', 'Miroslava', 'Iliana' ]\n}\n*/\n```\n\n\n### Create a deep copy of dt-object\n\n```js\nconst result = dt.query ( store =\u003e {\n store.look ( ({ name, flatData, breadcrumbs, next }) =\u003e {\n store.set ( name, flatData )\n if ( breadcrumbs.includes('/') ) store.connect ([breadcrumbs])\n return next ()\n })\n })\n .model ( () =\u003e ({as:'std'}))\nconsole.log ( result )\n/** -\u003e\n {\n school: [\n { name: 'Ivan', age: 14 },\n { name: 'Georgy', age: 15 },\n { name: 'Adi', age: 11 },\n { name: 'Kati', age: 11 }\n ],\n sports: [\n { name: 'Iva', age: 28 },\n { name: 'Stoyan', age: 36, sport: 'fencing' }\n ],\n work: [\n { name: 'Hristo', age: 38 },\n { name: 'Lachezar', age: 33 },\n { name: 'Veselina', age: 35 }\n ],\n recent: {\n classmates: [ { name: 'Anton', age: 42 }, { name: 'Miroslava', age: 42 } ],\n social: [ { name: 'Iliana', age: 61 }, { name: 'Tzvetan', age: 19 } ]\n }\n}\n */\n```\n\n\n\n\n## External Links\n- [DT-Queries. Some useful query functions for DT-Toolbox](https://github.com/PeterNaydenov/dt-queries)\n- [History of changes](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Changelog.md)\n- [Migration guide](https://github.com/PeterNaydenov/dt-toolbox/blob/master/Migration.guide.md)\n- [Documentation v.4.x.x](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.4.x.x.md)\n- [Documentation v.2.x.x](https://github.com/PeterNaydenov/dt-toolbox/blob/master/README_v.2.x.x.md)\n\n\n\n## Credits\n'dt-toolbox' was created and supported by Peter Naydenov.\n\n\n\n## License\n'dt-toolbox' is released under the [MIT License](http://opensource.org/licenses/MIT).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeternaydenov%2Fdt-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeternaydenov%2Fdt-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeternaydenov%2Fdt-toolbox/lists"}