v3.0.2 (#24)

* tests: adde some query and find tests

* docs: added core concepts

explains logic

* fix!(SBTree): .insertDocument to return array on single inclusion

* chore: update dependencies

* doc: additional primitives doc

* doc: improve navigation

* fix: improve fieldName fetching from query

* fix: finding recursive

* fix: proper $in search

CHANGELOG.md

@@ -1,2 +1,10 @@
 # Changelog 
 
+## 3.0.2
+
+- fix!(SBTree): .insertDocument to return array on single inclusion
+- fix: improve fieldName fetching from query
+- fix: finding recursive and $in
+- tests: added some query and find tests
+- doc: primitives documentation
+- doc: improved navigation

README.md

@@ -9,7 +9,7 @@
 
 > State : Optimisation, features and stability works in progress.
 
-> Documentation : https://alex-werner.github.io/SBTree
+Documentation : https://alex-werner.github.io/SBTree
 
 This library's goal is to provide a way to quickly store document-based data in-memory or on the filesystem. 
 It uses a field-specific indexing system relaying on B+Tree structure. 

docs/_sidebar.md

@@ -1,5 +1,21 @@
+- Getting Started
+ - [Core Concepts](getting-started/core-concepts.md) 
 - Primitives 
- - [SBTree](primitives/SBTree.md)
+ - [SBTree](primitives/SBTree/SBTree.md)
+ - [deleteDocuments](primitives/SBTree/methods/deleteDocuments)
+ - [findDocuments](primitives/SBTree/methods/findDocuments)
+ - [getDocument](primitives/SBTree/methods/getDocument)
+ - [insertDocuments](primitives/SBTree/methods/insertDocuments)
+ - [toJSON](primitives/SBTree/methods/toJSON)
+ - [SBFTree](primitives/SBFTree/SBFTree.md)
+ - [find](primitives/SBFTree/methods/find)
+ - [get](primitives/SBFTree/methods/get)
+ - [insert](primitives/SBFTree/methods/insert)
+ - [remove](primitives/SBFTree/methods/remove)
+ - [replace](primitives/SBFTree/methods/replace)
+ - [SBFRoot](primitives/SBFRoot/SBFRoot.md)
+ - [SBFNode](primitives/SBFNode/SBFNode.md)
+ - [SBFLeaf](primitives/SBFLeaf/SBFLeaf.md)
 - Usage
  - [Events](usage/events.md)
  - [Queries](usage/queries.md)

docs/getting-started/core-concepts.md

@@ -0,0 +1,25 @@
+## Core Concepts
+
+SBTree allows you to insert, delete, update, replace and find withing a balance B+ tree supporting uniqueness, and optional fields.
+
+SBTree holds set of SBFTree (F stands for Field). 
+
+On each insertion of a document, we parse all individual field, if we did not yet have a SBFTree with this fieldName, we creates. 
+
+All further instruction (finding, inserting,...) are directed to this tree manager.
+
+## SBFTree
+
+A SBFTree is unique for each fields, for nested object, each field of this object also have their own SBFTree.
+
+Using B+Tree, we have a root, that lead to leaf, or intermediaries node (holding leafs) and we manage indexing this way. 
+
+In those nodes (SBFRoot, SBFLeaf, SBFNode), we hold childrens reference (half splitting), set of keys (in a SBFTree of names, that would be ["Jean Valjean",...]) and identifiers (_id of the document).
+
+The logic is then that we parse query into those fieldTrees to output identifiers, and we resolves those identifiers by looking for a get of those document by Id.
+
+## Adapters
+
+This system allows to have a indices db locally, that support a MongoDB style command (but without any thing to install). 
+
+Due to the fact that it request persistance on a key-value way (via document id), it can be adaptable to a range of usage (local memory with single file save persistance, fs-adapter with single file / id, localstorage, mongodb,...);

docs/primitives/SBFLeaf/SBFLeaf.md

@@ -0,0 +1,6 @@
+### SBFLeaf
+
+SBFLeaf represents the end of the tree. 
+They contain a size, the identifier array, and the set of keys. 
+
+They rely on the adapter to fetch these informations back. 

docs/primitives/SBFNode/SBFNode.md

@@ -0,0 +1,5 @@
+### SBFNode
+
+SBFNode represents a part of the tree that is not a Leaf (intermediary nodes). 
+
+They contains the splitting keys (split of keys in the form of a binary search) and the references to the childrens nodes.

docs/primitives/SBFRoot/SBFRoot.md

@@ -0,0 +1,6 @@
+### SBFRoot
+
+SBFRoot represents the first node of our tree, the starting point from which we perform the insertion, replacement, deletion or search. 
+
+It contains multiples SBFNode (or Leaf) childrens, and a tiny subset of data in a keys and identifiers array.
+

docs/primitives/SBFTree/SBFTree.md

@@ -0,0 +1,29 @@
+### SBFTree API 
+
+```js
+const fielTree = new SBFTree([props]);
+```
+- Constructor options :
+ - `adapter` Adapter - (def: MemoryAdapter) : Allow to specific another adapter to use
+ - `order` Number - (def: 511) : Primordial for the performance, the closest to L1 the better. Chose below 2^n. 
+ - `fillFactor` Float - (def: 0.5) : Used for balancing the tree. Should not be less than 0.5 (50%). 
+ - `verbose` Bool - (def: false)
+ - `isUnique` Bool - (def: false)
+ - `root` SBFRoot - (def: null) - Allow to set a root to the fieldTree.
+ - `exclude` Array - (def: []) - Allow to exclude from indexing some field (important if you expect field value to be huge or nested).
+ - `id` FieldId - Allow to identify a FieldTree by an id; useful especially for adapter.
+
+### Usage
+
+The SBFTree is an interface instance specific to a field. For a document {age, name}, you would have two SBFTree, one for age, one for name. 
+
+The Tree has two components, an identifier (of the document), and a value and use a B+Tree.
+
+
+### Methods 
+
+- [find](primitives/SBFTree/methods/find)
+- [get](primitives/SBFTree/methods/get)
+- [insert](primitives/SBFTree/methods/insert)
+- [remove](primitives/SBFTree/methods/remove)
+- [replace](primitives/SBFTree/methods/replace)

docs/primitives/SBFTree/methods/find.md

@@ -0,0 +1,8 @@
+#### async tree.find(value, operator)
+
+Will find a value using a specific operator.
+
+```js
+ await tree.find(33, '$eq'); // Return set of identifiers and keys matching the find query.
+```
+

docs/primitives/SBFTree/methods/get.md

@@ -0,0 +1,8 @@
+#### async tree.get(identifier)
+
+Will get back a specific identifier's value
+
+```js
+ await tree.get('5d6755b71f9edbc997c8d156');
+```
+

docs/primitives/SBFTree/methods/insert.md

@@ -0,0 +1,8 @@
+#### async tree.insert(identifier, value)
+
+Will insert a set of identifier and value into the fieldTree.
+
+```js
+ await tree.insert('5d6755b71f9edbc997c8d156', 33);
+```
+

docs/primitives/SBFTree/methods/remove.md

@@ -0,0 +1,10 @@
+#### async tree.remove(identifier)
+
+Will remove a document from an identifier. 
+The RemoveCommand instance holds the different fields to delete the identifiers from.
+
+```js
+ const removeCommand = new RemoveCommand()
+ await tree.remove(removeCommand);
+```
+

docs/primitives/SBFTree/methods/replace.md

@@ -0,0 +1,8 @@
+#### async tree.replace(identifier, value)
+
+Will replace the value for an identifier.
+
+```js
+ await tree.replace('5d6755b71f9edbc997c8d156', 60);
+```
+

docs/primitives/SBTree/SBTree.md

@@ -0,0 +1,26 @@
+### SBTree 
+
+```js
+const tree = new SBTree([props]);
+```
+
+- Constructor options :
+ - `adapter` Adapter - (def: MemoryAdapter) : Allow to specific another adapter to use
+ - `order` Number - (def: 511) : Primordial for the performance, the closest to L1 the better. Chose below 2^n. 
+ - `fillFactor` Float - (def: 0.5) : Used for balancing the tree. Should not be less than 0.5 (50%). 
+ - `verbose` Bool - (def: false)
+ - `uniques` Array - (def: []) - Allow to set some field unique by adding them to this array
+ - `exclude` Array - (def: []) - Allow to exclude from indexing some field (important if you expect field value to be huge or nested).
+
+### Usage
+
+The SBTree is the instance that will allow you to insert, get, find, replace or delete documents.
+It internally hold multiple instances of [SBFTree](primitives/SBFTree.md) and works as a router, interfacing with the users.
+
+### Methods 
+
+- [deleteDocuments](primitives/SBTree/methods/deleteDocuments)
+- [findDocuments](primitives/SBTree/methods/findDocuments)
+- [getDocument](primitives/SBTree/methods/getDocument)
+- [insertDocuments](primitives/SBTree/methods/insertDocuments)
+- [toJSON](primitives/SBTree/methods/toJSON)

docs/primitives/SBTree/methods/deleteDocuments.md

@@ -0,0 +1,10 @@
+#### async tree.deleteDocuments(query)
+
+Will delete all documents matching the query.
+
+See more info on [queries](/docs/usage/queries.md)
+
+```js
+ await tree.deleteDocuments({age:33});
+```
+

docs/primitives/SBTree/methods/findDocuments.md

@@ -0,0 +1,11 @@
+#### async tree.findDocuments(query)
+
+Allow to find all documents matching the query
+
+See more info on [queries](/docs/usage/queries.md)
+
+
+```js
+ await tree.findDocuments({age:33});
+```
+

docs/primitives/SBTree/methods/getDocument.md

@@ -0,0 +1,9 @@
+
+#### async tree.getDocument(_id)
+
+Allow to fetch a specific document by it's specific id.
+
+```js
+ await tree.getDocument('507f191e810c19729de860ea')
+```
+

docs/primitives/SBTree/methods/insertDocuments.md

@@ -0,0 +1,9 @@
+#### async tree.insertDocuments(documents)
+
+Allow to process an array (or unique) of documents and get them inserted. 
+It returns the inserted array containing mutated (with their _id if not specified in document) values.
+
+```js
+ await tree.insertDocuments({age:33, name:"Jean",_id:'507f191e810c19729de860ea'})
+```
+

docs/primitives/SBTree/methods/toJSON.md

@@ -0,0 +1,7 @@
+#### tree.toJSON()
+
+Allow to return a representation in JSON of the tree. Useful for storing it, as it's result are valid params for the SBTree constructor.
+
+```js
+ tree.toJSON()
+```

docs/usage/events.md

@@ -1,8 +1,8 @@
-## Events
+### Events
 
-### SBTree Events
+#### SBTree Events
 
-#### tree.on(event)
+##### tree.on(event)
 
 - eventTypes : 
  - ready : Emitted when the Tree has a parent attached and is ready for usage

docs/usage/queries.md

@@ -1,10 +1,10 @@
-## Queries
+### Queries
 
 Most of the methods in SBTree are straightforward `insert` expect a document to insert, `get` a document id to fetch. 
 
 However the only exception might be for the query syntax, which is actually a subset of the MongoDB query syntax. 
 
-### Comparators 
+#### Comparators 
 
 | Name | Description | Examples |
 |-------------- |------------------------------------------------------------------------- |------------------------------------------------ |
@@ -19,7 +19,7 @@ However the only exception might be for the query syntax, which is actually a su
 | $nin | Matches documents that do not have any elements of the specified array. | `.findDocuments({country:{$nin:["Antarctica"]})` |
 
 
-### Additionals 
+#### Additionals 
 
 N.B : Not available yet. Only comparators are available to use. This documentation documents forthcoming features.
 
@@ -32,6 +32,6 @@ TODO
 - $exists
 - $regex
 
-### Caveats 
+#### Caveats 
 
 Nested object query is not yet an available feature, but it is high on our priority list.