![\"StormDB](\"./docs/logo.png\"){kind=logo}
\r\n\r\n đŠī¸ StormDB is a tiny, lightweight, 0 dependency, easy-to-use JSON-based database that allows users to quickly and easily achieve data persistence by provided an engine to store and access JSON data for NodeJS the browser or Electron.
\r\n\r\n \r\n![](\"https://img.shields.io/npm/v/stormdb?color=green\")
\r\n \r\n \r\n ![](\"https://img.shields.io/bundlephobia/minzip/stormdb?color=green\")
\r\n \r\n ![](\"https://img.shields.io/badge/dependencies-0-brightgreen?color=blue\"){kind=icon}
\r\n \r\n ![](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
\r\n \r\nTry it online now: Demo Page and Interactive Playground!
\r\n\r\n> Example: Add a post entry under users.tom and save it to the database.\r\n\r\n```js\r\ndb.get(\"users\")\r\n .get(\"tom\")\r\n .push({ title: \"Post 1\" })\r\n .save();\r\n```\r\n\r\n## Features\r\n\r\n- đī¸ Blazingly Fast Speeds - Fast read and write speeds, even when handling large data.\r\n- đĻ [Tiny Size](https://bundlephobia.com/result?p=stormdb) - Tiny source code size allows for blazingly fast loading when speed matters.\r\n- âĄī¸ Versatile - Can be used with NodeJS, in the browser or in Electron.\r\n\r\n## Usage\r\n\r\nInstall StormDB through NPM:\r\n\r\n```\r\n$ npm i stormdb\r\n```\r\n\r\nBasic usage with NodeJS:\r\n\r\n```js\r\nconst StormDB = require(\"stormdb\");\r\n\r\n// start db with \"./db.stormdb\" storage location\r\nconst engine = new StormDB.localFileEngine(\"./db.stormdb\");\r\nconst db = new StormDB(engine);\r\n\r\n// set default db value if db is empty\r\ndb.default({ users: [] });\r\n\r\n// add new users entry\r\ndb.get(\"users\").push({ name: \"tom\" });\r\n\r\n// update username of first user\r\ndb.get(\"users\")\r\n .get(0)\r\n .get(\"name\")\r\n .set(\"jeff\");\r\n\r\n// save changes to db\r\ndb.save();\r\n```\r\n\r\nThe `db.stormdb` database file is updated to:\r\n\r\n```js\r\n{\r\n \"users\": [\r\n {\"name\":\"jeff\"}\r\n ]\r\n}\r\n```\r\n\r\nTypescript Usage:\r\n\r\n```ts\r\nimport StormDB from \"stormdb\";\r\n\r\n// start db with \"./db.stormdb\" storage location\r\nconst engine = new StormDB.localFileEngine(\"./db.stormdb\");\r\nconst db = new StormDB(engine);\r\n```\r\n\r\nStormDB is designed to be flexible, and can be used in NodeJS, the browser or even Electron with very small adaptations to the code. Examples usages can be seen below:\r\n\r\n- [Browser Usage](./examples/browser.md)\r\n- [NodeJS Server](./examples/node.md)\r\n- [Online Demo and Playground](https://tomprograms.github.io/stormdb)\r\n\r\n## Engine API\r\n\r\nFor expanding functionality, each database initialized can be expanded with the following options, in the format `new Engine(path, options);`.\r\n\r\n- `serialize` - function to serialize data before writing it to the database.\r\n- `deserialize` - function to deserialize data from the database.\r\n\r\n## Database Operations Examples\r\n\r\nChange Value of Key in Database:\r\n\r\n```js\r\ndb.get(\"old\").set(\"newData\");\r\n// before: {\"old\": \"oldData\"}\r\n// after: {\"old\": \"newData\"}\r\n```\r\n\r\nReturn the Raw Value of a Selected Property:\r\n\r\n```js\r\n// before {\"list\": [1, 2, 3]}\r\ndb.get(\"list\").value(); // returns [1, 2, 3]\r\n```\r\n\r\nSet Key-Value Pair on Dictionary Property:\r\n\r\n```js\r\ndb.set(\"key\", \"value\").save();\r\n// before: {}\r\n// after: {\"key\": \"value\"}\r\n```\r\n\r\nDelete Value:\r\n\r\n```js\r\ndb.get(\"key\").delete();\r\n// before: {'key': 'value', 'key2': 'value2'}\r\n// after: {'key2': 'value2'}\r\n```\r\n\r\nIf you delete a value from a list, it will leave a null value in the place of the deleted data:\r\n\r\n```js\r\ndb.get(\"key\")\r\n .get(1)\r\n .delete();\r\n// before: {'key': [1, 2, 3]}\r\n// after: {'key2': [1, null, 3]}\r\n```\r\n\r\nIf you don't want this behaviour, you can pass in `true` to the `.delete()` function to not leave a null value in place of the deleted data:\r\n\r\n```js\r\ndb.get(\"key\")\r\n .get(1)\r\n .delete(true);\r\n// before: {'key': [1, 2, 3]}\r\n// after: {'key2': [1, 3]}\r\n```\r\n\r\nSet Key-Value Pair on dictionary with dot notation shorthand:\r\n\r\n```js\r\ndb.set(\"key.key2\", \"value\").save();\r\n// before: {}\r\n// after: {\"key\": {\"key2\": \"value\"}}\r\n```\r\n\r\nNote, that the `set` and `get` functions allow for dot notation for the keys, if you don't want this behaviour, as you may have a key with a dot in it, you can disable it by providing an extra parameter:\r\n\r\n```js\r\ndb.get(\"one.two\", false).set(\"three.four\", \"test\", false);\r\n// before: {\"one.two\": {}}\r\n// after: {\"one.two\": {\"three.four\": \"test\"}}\r\n```\r\n\r\nSet Default Data for Empty Database:\r\n\r\n```js\r\ndb.default({ name: \"tom\" });\r\n\r\n// actual db: {}\r\nconsole.log(db.get(\"name\")); // prints \"tom\"\r\n```\r\n\r\nPush Item to Array Property:\r\n\r\n```js\r\ndb.get(\"list\")\r\n .push(1)\r\n .save();\r\n\r\n// before: {'list': []}\r\n// after: {'list': [1]}\r\n```\r\n\r\nFilter Out All Elements under 5:\r\n\r\n```js\r\n// before = {'list': [1,2,6,1]}\r\n// output = {'list': [6]}\r\n\r\ndb.get(\"list\").filter(i => i >= 5);\r\n\r\n// save db\r\ndb.save();\r\n```\r\n\r\nChange Element with Highest Value:\r\n\r\n```js\r\n// before = {'users': [{value: 10}, {value: 5}, {value: 6}]}\r\n// after = {'users': [{value: \"changed\"}, {value: 6}, {value: 5}]}\r\n\r\ndb.get(\"users\").sort((a, b) => b.value - a.value);\r\n\r\n// change value of highest element\r\ndb.get(\"users\")\r\n .get(0)\r\n .get(\"value\")\r\n .set(\"changed\");\r\n\r\n// save db\r\ndb.save();\r\n```\r\n\r\nMap List, Squaring Each Number in List:\r\n\r\n```js\r\n// before = {'data': [1,2,3,4,5]}\r\n// after = {'data': [1,4,9,16,25]}\r\n\r\n// square each number in the list\r\ndb.get(\"data\").map(x => x ** 2);\r\n\r\n// save db\r\ndb.save();\r\n```\r\n\r\nReduce List, Finding Value of All Values in List Summed:\r\n\r\n```js\r\n// before = {'data': [1,2,3,4,5]}\r\n// after = {'data': 15}\r\n\r\n// find value of all numbers in list summed together\r\ndb.get(\"data\").reduce(\r\n (accumulator, currentValue) => accumulator + currentValue\r\n);\r\n\r\n// save db\r\ndb.save();\r\n```\r\n\r\nLeverage Serialize and Deserialize functions to encrypt and decrypt data:\r\n\r\n```js\r\nconst engine = new StormDB.localFileEngine(\"./db.stormdb\", {\r\n serialize: data => {\r\n // encrypt and serialize data\r\n return encrypt(JSON.stringify(data));\r\n },\r\n deserialize: data => {\r\n // decrypt and deserialize data\r\n return JSON.parse(decrypt(data));\r\n }\r\n});\r\nconst db = new StormDB(engine);\r\n```\r\n\r\n## Credit\r\n\r\nAuthor: [Tom](https://github.com/TomPrograms)\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n","readmeFilename":"Readme.md","keywords":["database","JSON","file","embed","embeddable","localStorage","node","browser","electron"]}