{"analyzedAt":"2022-07-03T10:25:44.267Z","collected":{"metadata":{"name":"dexteritydb","scope":"unscoped","version":"0.4.5","description":"Node.js driver for DexterityDB","keywords":["dexteritydb","dexdb","dexterity","dex","database","driver","official","api","client"],"date":"2018-02-27T00:42:03.100Z","author":{"name":"Alex Sabella"},"publisher":{"username":"asabs14","email":"asabs14@gmail.com"},"maintainers":[{"username":"asabs14","email":"asabs14@gmail.com"},{"username":"dillonu","email":"dillonu@gmail.com"}],"repository":{"type":"git","url":"git+https://github.com/Savizar/dexteritydb-node.git"},"links":{"npm":"https://www.npmjs.com/package/dexteritydb","homepage":"https://github.com/Savizar/dexteritydb-node#readme","repository":"https://github.com/Savizar/dexteritydb-node","bugs":"https://github.com/Savizar/dexteritydb-node/issues"},"license":"Apache-2.0","dependencies":{"ws":"^3.3.3"},"devDependencies":{"@types/ws":"^3.2.1","hotdoc":"^0.7","jsdoc":"^3.5","typescript":"^2.6"},"releases":[{"from":"2022-06-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-04-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":1},{"from":"2022-01-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":1},{"from":"2021-07-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":1},{"from":"2020-07-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":1}],"readme":"# dexteritydb-node\r\n[![npm](https://img.shields.io/npm/v/dexteritydb.svg)](https://www.npmjs.com/package/dexteritydb)\r\n<img src=\"https://david-dm.org/Savizar/dexteritydb-node.svg\" />\r\n\r\nThe official Node.js driver for DexterityDB. Provides a high-level API for use in node based applications.\r\n\r\n# Getting Started\r\nThe easiest way to start using the DexterityDB Node.js driver is to use the node package manager:\r\n```bash\r\nnpm install dexteritydb\r\n```\r\nThen add the following to your Node.js script:\r\n```javascript\r\nconst { Dex } = require(\"dexteritydb\");\r\n```\r\nThat's it! That's all you need to start using the DexterityDB Node.js driver.\r\n\r\n# Basic Usage\r\n\r\n## Dex Class\r\nThe DexterityDB Node.js driver was designed to be easy to use. It was built to be as dextrous and as flexible as possible, while still providing all of the feature capabilities that you might need to write powerful applications and scripts.\r\n\r\nAll programs written with the DexterityDB node driver begin with an instance of the ```Dex``` class. The ```Dex``` class is a database object that contains all of the methods that you might need to start using DexterityDB. It is recommended to use a single instance of ```Dex``` in any single piece of code.\r\n```javascript\r\nlet db = new Dex('http://localhost:3000');\r\n```\r\nThe ```Dex``` constructor accepts two optional parameters. The first parameter, as shown above, is the endpoint of the DexterityDB instance that you want to connect up to. If an address is given, the driver will attempt to connect immediately upon generation of the ```Dex``` object. The second optional parameter, not shown in the example above, is a flag that indicates whether or not you want the driver to try to reconnect to the database after a disconnection. By default, this parameter is ```true```.\r\n\r\n_Due to how the DexterityDB Node.js driver queues messages, the line of code shown above does not need to complete before queries are run in sequential lines. For this reason, we do not handle, nor do we even create, a promise in the constructor of ```Dex``` instances or in its ```connect``` method. The driver will do the hard work of making sure the database is connected before sending requests._\r\n\r\n## Example Walkthrough\r\nThe following lines of code can be run in the node driver. We will walk through this example and what it does below. It is important to note that the node driver is asynchronous so the example below uses promises to execute syncronously:\r\n```javascript\r\nasync function main() {\r\n    const example = db.collection(\"example\");\r\n    await example.insert({ name: \"John\", age: 35 }, { name: \"Jane\", age: 28 });\r\n    await example.index(\"name\");\r\n    example.find({ name: \"John\" }).fetchAll().then((result) => {\r\n        console.log(results);\r\n    });\r\n}\r\n\r\nmain();\r\n```\r\n\r\n### Collection Class\r\nThe ```Collection``` class is the second most used class in the DexterityDB node driver. The ```Collection``` class is instantiated with a simple ```collection``` function call from a ```Dex``` instance. This can be seen in the first line of the ```main``` function:\r\n```javascript\r\nconst example = db.collection(\"example\");\r\n```\r\nWe pass the ```example``` string to the ```collection``` call to indicate that we are working on the ```example collection```.\r\n\r\n### Insert\r\nThe second line of the ```main``` function shows a simple ```insert``` call:\r\n```javascript\r\nawait example.insert({ name: \"John\", age: 35 }, { name: \"Jane\", age: 28 });\r\n```\r\nAny number of JSON objects can be passed into the ```insert``` function. Simply treat each object as a separate parameter in the function call or pass an array of objects.\r\n\r\n### Indexing\r\nOne of the things that makes DexterityDB special is the requirement of indexing any fields that you may want to search on. Once indexed, a field becomes immediately searchable. Any previously inserted items, as well as any future inserted items will automatically be indexed by the designated field. This is best practice in the database world. It is a bit different than some other databases' approaches, but we feel that encouraging best practices is how we can make everyone's experience with DexterityDB more simple and enjoyable. Usually, we would encourage indexing at the beginning of the script, but for ease of comprehension, we have done it after the insert. The third line of the example reads:\r\n```javascript\r\nawait example.index(\"name\");\r\n```\r\nIndexing is easy. The above example proves that. Simply pass in the field that you want to index and it will become instantly searchable. DexterityDB does the rest.\r\n\r\n### Find and Fetch\r\nThe DexterityDB driver utilizes chained commands to provide the user with a language that is very easy to use and easy to understand. ```Find``` is a key method that can be chained on a ```collection``` call. It can be used to retrieve (or fetch) results, as well as updating and removing items in the database. The fourth line in the ```main``` function shows off this capability:\r\n```javascript\r\nexample.find({ name: \"John\" }).fetchAll().then((result) => {\r\n    console.log(results);\r\n});\r\n```\r\nJust to reiterate, the field that we search on MUST be indexed. If you missed the indexing step, please go up a few mouse scrolls and reread the indexing section. \r\n\r\nTo search for something in the database, first we use ```.find``` and pass the object pattern that we are looking for. The pattern in the example indicates that we are looking for all items that have the name, \"John\", as the value under the indexed field, \"name.\"\r\n\r\nSince there are many things that we can do with a query result on the database side, there are many methods that can be chained onto the ```find``` method. For this example, we use ```fetchAll```, an intuitive function. ```FetchAll``` returns all of the objects that fit the ```find``` query. No parameters required (some allowed!). See the [fetch](./ReadQuery.html#fetch) or [fetchAll](./ReadQuery.html#fetchAll) documentation for more information on optional parameters.\r\n\r\nAlternatively, the above example can be written as such:\r\n```javascript\r\nexample.find({ name: \"John\" }).fetch().then((cursor) => {\r\n    cursor.collect().then((results) => {\r\n        console.log(results);\r\n    })\r\n});\r\n```\r\nThis setup shows off the ```Cursor``` object, which allows for streaming ```fetch``` results. The ```Cursor``` makes retrieving results more efficient, because one or more items can be retrieved and used at a time, when they are needed. In this example we simply ```collect``` all of them to show that this is equivalent to the ```fetchAll``` shown in the last example.\r\n\r\nAs stated earlier, DexterityDB is asynchronous, so we use a ```.then``` to consume the ```promise```s and print the results.\r\n\r\nThat's it! You now have all of the information you need to get started with the DexterityDB Node.js driver. But don't stop there...check out the full [DexterityDB Node.js API Tutorial](https://savizar.github.io/dexteritydb-node/tutorial-1-0-0_TheApproach.html) for all of the options and chainable methods that exist on the driver.\r\n\r\nHappy Dexing!\r\n\r\n## Helpful Links\r\n[DexterityDB](http://dexteritydb.com)<br>\r\n[Node.JS API Tutorial](https://savizar.github.io/dexteritydb-node/tutorial-1-0-0_TheApproach.html)<br>\r\n[Node.JS Driver GitHub](https://github.com/Savizar/dexteritydb-node)\r\n\r\n\r\n# For Contributors\r\nThe DexterityDB Node.js driver is written mostly in [TypeScript](https://www.typescriptlang.org/). It is compiled into Javascript using the Typescript compiler.\r\n\r\nDocumentation is generated using [JSDoc](http://usejsdoc.org/) with the [Docdash](https://github.com/clenemt/docdash) template, customized with [Hotdoc](https://github.com/kmck/hotdoc).\r\n\r\n**_Note: To install necessary npm packages, you will need [Python 2.7.13](https://www.python.org/downloads/release/python-2713/)._**\r\n\r\nTo make changes to driver, download the repository and execute ```npm install``` to get all relevant packages.\r\n\r\nAfter making changes to the TypeScript files or adding/modifying JSDoc documentation, simply execute ```npm run build```.\r\nThis will build all javascript files and all documentation and you'll be good to go!"},"npm":{"downloads":[{"from":"2022-07-02T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-06-26T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-06-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":16},{"from":"2022-04-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":126},{"from":"2022-01-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":186},{"from":"2021-07-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":377}],"starsCount":0},"github":{"homepage":"https://savizar.github.io/dexteritydb-node/","starsCount":1,"forksCount":0,"subscribersCount":4,"issues":{"count":0,"openCount":0,"distribution":{"3600":0,"10800":0,"32400":0,"97200":0,"291600":0,"874800":0,"2624400":0,"7873200":0,"23619600":0,"70858800":0,"212576400":0},"isDisabled":false},"contributors":[{"username":"Dillonu","commitsCount":6},{"username":"asabs14","commitsCount":63}],"commits":[{"from":"2022-06-26T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-06-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-04-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2022-01-04T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0},{"from":"2021-07-03T00:00:00.000Z","to":"2022-07-03T00:00:00.000Z","count":0}],"statuses":[{"context":"github/pages","state":"success"}]},"source":{"files":{"readmeSize":8043,"testsSize":13758},"badges":[{"urls":{"original":"https://img.shields.io/npm/v/dexteritydb.svg","shields":"https://img.shields.io/npm/v/dexteritydb.svg","content":"https://img.shields.io/npm/v/dexteritydb.json"},"info":{"service":"npm","type":"version","modifiers":{"type":"v"}}},{"urls":{"original":"https://david-dm.org/Savizar/dexteritydb-node.svg","service":"https://david-dm.org/Savizar/dexteritydb-node.svg","shields":"https://img.shields.io/david/Savizar/dexteritydb-node.svg","content":"https://img.shields.io/david/Savizar/dexteritydb-node.json"},"info":{"service":"david","type":"dependencies","modifiers":{"statusType":"normal"}}}],"outdatedDependencies":{"ws":{"required":"^3.3.3","stable":"8.8.0","latest":"8.8.0"}}}},"evaluation":{"quality":{"carefulness":0.355,"tests":0.55,"health":0.75,"branding":0.3},"popularity":{"communityInterest":7,"downloadsCount":42,"downloadsAcceleration":-0.12477168949771691,"dependentsCount":0},"maintenance":{"releasesFrequency":0.28664383561643836,"commitsFrequency":0,"openIssues":0.7,"issuesDistribution":0.7}},"score":{"final":0.5407793495659815,"detail":{"quality":0.7891885425163427,"popularity":0.03854282885772369,"maintenance":0.8300937048882155}}}