{"id":14007036,"url":"https://github.com/Belphemur/node-json-db","last_synced_at":"2025-07-24T00:32:54.758Z","repository":{"id":18560302,"uuid":"21762296","full_name":"Belphemur/node-json-db","owner":"Belphemur","description":"A simple \"database\" that use JSON file for Node.JS.","archived":false,"fork":false,"pushed_at":"2024-04-18T05:14:53.000Z","size":5306,"stargazers_count":766,"open_issues_count":14,"forks_count":65,"subscribers_count":16,"default_branch":"develop","last_synced_at":"2024-05-01T20:24:58.039Z","etag":null,"topics":["database","datapath","javascript","json","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/Belphemur.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.YML","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},"funding":{"github":"Belphemur","custom":"https://soundswitch.aaflalo.me/#donate"}},"created_at":"2014-07-12T07:47:25.000Z","updated_at":"2024-05-07T06:33:20.056Z","dependencies_parsed_at":"2024-01-15T06:28:38.865Z","dependency_job_id":"40937274-bdc0-4fc1-bd2b-382aa754ae99","html_url":"https://github.com/Belphemur/node-json-db","commit_stats":{"total_commits":735,"total_committers":33,"mean_commits":"22.272727272727273","dds":0.5034013605442177,"last_synced_commit":"9e052a504fe1f73eeaa00000bc4052f23d7a9d9f"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Belphemur%2Fnode-json-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Belphemur%2Fnode-json-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Belphemur%2Fnode-json-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Belphemur%2Fnode-json-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Belphemur","download_url":"https://codeload.github.com/Belphemur/node-json-db/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":214665239,"owners_count":15766623,"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","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":["database","datapath","javascript","json","typescript"],"created_at":"2024-08-10T10:01:46.933Z","updated_at":"2025-07-24T00:32:54.747Z","avatar_url":"https://github.com/Belphemur.png","language":"TypeScript","readme":"[![NodeJs](https://github.com/Belphemur/node-json-db/actions/workflows/nodejs.yml/badge.svg)](https://github.com/Belphemur/node-json-db/actions/workflows/nodejs.yml) [![codecov](https://codecov.io/gh/Belphemur/node-json-db/branch/master/graph/badge.svg?token=J3Ppt4UCbY)](https://codecov.io/gh/Belphemur/node-json-db)\n[![npm version](https://badge.fury.io/js/node-json-db.svg)](https://badge.fury.io/js/node-json-db)\n\u003e A simple \"database\" that uses JSON file for Node.JS.\n\n## Breaking changes since v1.x.x\n### v2.0.0\n\nJsonDB is now using the concept of async/await for all its calls since we read from the database file on demand and\ndepending on how the database is configured, we might write at each push.\n\n* You're now forced to use the `Config` object to setup JsonDB\n* Every method is now asynchronous\n\n## Installation\nAdd `node-json-db` to your existing Node.js project.\n\nYARN:\n```bash\nyarn add node-json-db\n```\nNPM:\n```bash\nnpm i node-json-db\n```\n\n## Documentation\n[Auto Generated](https://belphemur.github.io/node-json-db)\n\n## Known projects\nIf you're looking for testing out the library in a playground [@Servant-Cities](https://github.com/Servant-Cities/) has made a small project to test it out:\n\n[Rest Api Playground](https://github.com/Servant-Cities/rest-api-playground-template)\n\n## Inner Working\n\n### Data\nThe module stores the data using JavaScript Object directly into a JSON file. You can easily traverse the data to directly reach \nthe desired property using the DataPath. The principle of DataPath is the same as XMLPath.\n\n### Example\n```javascript\n{\n    test: {\n        data1 : {\n            array : ['test','array']\n        },\n        data2 : 5\n    }\n}\n```\nIf you want to fetch the value of array, the DataPath is **/test/data1/array**\nTo reach the value of data2 : **/test/data2**\nYou can of course also get the full object **test** : **/test**\nOr even the root : **/**\n## Usage\nSee [test](https://github.com/Belphemur/node-json-db/tree/master/test) for more usage details.\n\n\n```javascript\nimport { JsonDB, Config } from 'node-json-db';\n\n// The first argument is the database filename. If no extension is used, '.json' is assumed and automatically added.\n// The second argument is used to tell the DB to save after each push\n// If you set the second argument to false, you'll have to call the save() method.\n// The third argument is used to ask JsonDB to save the database in a human readable format. (default false)\n// The last argument is the separator. By default it's slash (/)\nvar db = new JsonDB(new Config(\"myDataBase\", true, false, '/'));\n\n// Pushing the data into the database\n// With the wanted DataPath\n// By default the push will override the old value\nawait db.push(\"/test1\",\"super test\");\n\n// When pushing new data for a DataPath that doesn't exist, it automatically creates the hierarchy\nawait db.push(\"/test2/my/test\",5);\n\n// You can also push objects directly\nawait db.push(\"/test3\", {test:\"test\", json: {test:[\"test\"]}});\n\n// If you don't want to override the data but to merge them\n// The merge is recursive and works with Object and Array.\nawait db.push(\"/test3\", {\n    new:\"cool\",\n    json: {\n        important : 5\n    }\n}, false);\n\n/*\nThis give you this results :\n{\n   \"test\":\"test\",\n   \"json\":{\n      \"test\":[\n         \"test\"\n      ],\n      \"important\":5\n   },\n   \"new\":\"cool\"\n}\n*/\n\n// You can't merge primitives.\n// If you do this:\nawait db.push(\"/test2/my/test/\",10,false);\n\n// The data will be overriden\n\n// Get the data from the root\nvar data = await db.getData(\"/\");\n\n// Or from a particular DataPath\nvar data = await db.getData(\"/test1\");\n\n// If you try to get some data from a DataPath that doesn't exist\n// You'll get an Error\ntry {\n    var data = await db.getData(\"/test1/test/dont/work\");\n} catch(error) {\n    // The error will tell you where the DataPath stopped. In this case test1\n    // Since /test1/test does't exist.\n    console.error(error);\n};\n\n// Easier than try catch when the path doesn't lead to data\n// This will return `myDefaultValue` if `/super/path` doesn't have data, otherwise it will return the data\nvar data = await db.getObjectDefault\u003cstring\u003e(\"/super/path\", \"myDefaultValue\");\n\n// Deleting data\nawait db.delete(\"/test1\");\n\n// Save the data (useful if you disable the saveOnPush)\nawait db.save();\n\n// In case you have an exterior change to the databse file and want to reload it\n// use this method\nawait db.reload();\n\n```\n\n### TypeScript Support\n\n#### v0.8.0\nAs of v0.8.0, [TypeScript](https://www.typescriptlang.org) types are\nincluded in this package, so using `@types/node-json-db` is no longer required.\n\n\n#### v1.0.0\n\nJsonDB isn't exported as default any more. You'll need to change how you load the library.\n\nThis change is done to follow the right way to import module.\n```javascript\nimport { JsonDB, Config } from 'node-json-db';\n\nconst db = new JsonDB(new Config(\"myDataBase\", true, false, '/'));\n```\n\n#### Typing\nWith TypeScript, you have access to a new method: getObject\u003cT\u003e that will take care of typing your return object.\n```typescript\nimport { JsonDB, Config } from 'node-json-db';\n\nconst db = new JsonDB(new Config(\"myDataBase\", true, false, '/'));\n\ninterface FooBar {\n    Hello: string\n    World: number\n}\nconst object = {Hello: \"World\", World: 5} as FooBar;\n\nawait db.push(\"/test\", object);\n\n// Will be typed as FooBar in your IDE\nconst result = await db.getObject\u003cFooBar\u003e(\"/test\");\n```\n\n\n### Array Support\nYou can also access the information stored in arrays and manipulate them.\n```typescript\nimport { JsonDB, Config } from 'node-json-db';\n\n// The first argument is the database filename. If no extension is used, '.json' is assumed and automatically added.\n// The second argument is used to tell the DB to save after each push\n// If you set the second argument to false, you'll have to call the save() method.\n// The third argument is used to ask JsonDB to save the database in a human readable format. (default false)\nconst db = new JsonDB(new Config(\"myDataBase\", true, false, '/'));\n\n// This will create an array 'myarray' with the object '{obj:'test'}' at index 0\nawait db.push(\"/arraytest/myarray[0]\", {\n    obj:'test'\n}, true);\n\n// You can retrieve a property of an object included in an array\n// testString = 'test';\nvar testString = await db.getData(\"/arraytest/myarray[0]/obj\");\n\n// Doing this will delete the object stored at the index 0 of the array.\n// Keep in mind this won't delete the array even if it's empty.\nawait db.delete(\"/arraytest/myarray[0]\");\n```\n\n#### Appending in Array\n```javascript\n// You can also easily append a new item to an existing array\n// This sets the next index with {obj: 'test'}\nawait db.push(\"/arraytest/myarray[]\", {\n    obj:'test'\n}, true);\n\n\n// The append feature can be used in conjuction with properties\n// This will set the next index as an object {myTest: 'test'}\nawait db.push(\"/arraytest/myarray[]/myTest\", 'test', true);\n\n```\n\n#### Last Item in Array\n```javascript\n// Add basic array\nawait db.push(\"/arraytest/lastItemArray\", [1, 2, 3], true);\n\n// You can easily get the last item of the array with the index -1\n// This will return 3\nawait db.getData(\"/arraytest/lastItemArray[-1]\");\n\n\n// You can delete the last item of an array with -1\n// This will remove the integer \"3\" from the array\nawait db.delete(\"/arraytest/lastItemArray[-1]\");\n\n// This will return 2 since 3 just got removed\nawait db.getData(\"/arraytest/lastItemArray[-1]\");\n```\n#### Count for Array\n```javascript\n//\nawait db.push(\"/arraytest/list\", [{id: 65464646155, name: \"test\"}], true);\n\n// You can request for the total number of elements, in this case, 1\nlet numberOfElements = await db.count(\"/arraytest/list\");\n```\n\n#### Get Index in Array\n```javascript\n\n// You can have the current index of an object\nawait db.push(\"/arraytest/myarray\", [{id: 65464646155, name: \"test\"}], true);\nawait db.getIndex(\"/arraytest/myarray\", 65464646155);\n// The default property is 'id'\n// You can add another property instead\nawait db.getIndex(\"/arraytest/myarray\", \"test\", \"name\");\n\n// It's useful if you want to delete an object\nawait db.delete(\"/arraytest/myarray[\" + await db.getIndex(\"/arraytest/myarray\", 65464646155) + \"]\");\n```\n    \n#### Nesting in Array\n```javascript\n// You can easily access any nested array and their object\n// You can also append another array to a nested array\nawait db.push(\"/arraytest/myarray\",\n[\n  [\n    {\n      obj: 'test'\n    },\n    {\n      obj: 'hello'\n    }\n  ],\n  [\n    {\n      obj: 'world'\n    }\n  ]\n]\n, true);\n\n// This will return the first object (obj: 'test')\n\nawait db.getData(\"/arraytest/myarray[0][0]\");\n\n```\n\n#### Getting Item path in Array by id or Another key\n\n```javascript\n\nawait db.push(\"/myarray\",\n[\n    {\n      id: '1',\n      obj: 'test'\n    },\n    {\n      id: '2',\n      obj: 'hello'\n    },\n    {\n      id: '3',\n      obj: 'hello',\n      children:[\n        {\n          id: '1',\n          desc: 'a sub item'\n        }\n      ]\n    },\n]\n, true);\n\n// You can easily get the path of any nested array and its child object by a property using the route style syntax, the default is the object's \"id\" property\n\nconst itemPath = db.fromPath(\"/myarray/3/children/1\");\n\n```\n\n### Exception/Error\n#### Type\n\n| Type          |                   Explanation                                    |\n| ------------- |:----------------------------------------------------------------:|\n| DataError     | When the error is linked to the Data Given                       | \n| DatabaseError | Linked to a problem with the loading or saving of the Database.  |\n\n#### Errors\n\n| Error                                                 | Type          |                   Explanation                                                                                                                                             |\n| ------------------------------------------------------|:-------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n|The Data Path can't be empty                           |DataError      |The Database expects to receive at least the root **separator** as part of the DataPath.                                                                                                         |\n|Can't find dataPath: /XXX. Stopped at YYY              |DataError      |When the full hierarchy of the provided DataPath is not present in the Database, it indicates the extent of its validity. This error can occur when using the `getData` and `delete` operations. | \n|Can't merge another type of data with an Array         |DataError      |This occurs if you chose not to override the data when pushing (merging) and the new data is an array, but the current data isn't an array (an Object for example).                      | \n|Can't merge an Array with an Object                    |DataError      |Similar to the previous message, you have an array as the current data and request to merge it with an object.                                                                   | \n|DataPath: /XXX.  YYY is not an array.                  |DataError      |When trying to access an object as an array.                                                                                                                               | \n|DataPath: /XXX. Can't find index INDEX in array YYY    |DataError      |When trying to access a non-existent index in the array.                                                                                                                   | \n|Only numerical values accepted for array index         |DataError      |An array can only use `number` for its indexes. For this use the normal object.                                                                                              |\n|The entry at the path (/XXX) needs to be either an Object or an Array        |DataError      |When using the `find` method, the rootPath needs to point to an object or an array to search within it for the desired value.                              |\n|Can't Load Database:  XXXX                             |DatabaseError  |JsonDB can't load the database for \"err\" reason. You can find the nested error in `error.inner`                                                                          |\n|Can't save the database: XXX                           |DatabaseError  |JsonDB can't save the database for \"err\" reason. You can find the nested error in `error.inner`                                                                          | \n|DataBase not loaded. Can't write                       |DatabaseError  |Since the database hasn't been loaded correctly, the module won't let you save the data to avoid erasing your database.                                                    | \n\n# Limitations\n\n## Object with `separator` in key\n Object pushed with key containing the `separator` character won't be reachable. See [#75](https://github.com/Belphemur/node-json-db/issues/75).\n\n Please consider the `separator` as a reserved character by node-json-await db.\n\n\n# Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://davisjam.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/22822319?v=4?s=100\" width=\"100px;\" alt=\"Jamie Davis\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJamie Davis\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#security-davisjam\" title=\"Security\"\u003e🛡️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/sidblommerswork\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/93680615?v=4?s=100\" width=\"100px;\" alt=\"sidblommerswork\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003esidblommerswork\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=sidblommerswork\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=sidblommerswork\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/drproktor\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/19718418?v=4?s=100\" width=\"100px;\" alt=\"Max Huber\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMax Huber\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=drproktor\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/adamhl8\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1844269?v=4?s=100\" width=\"100px;\" alt=\"Adam\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAdam\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=adamhl8\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=adamhl8\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://divineanum.me\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/44934037?v=4?s=100\" width=\"100px;\" alt=\"Divine Anum\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDivine Anum\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=CHR-onicles\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/michalfedyna\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/84079005?v=4?s=100\" width=\"100px;\" alt=\"Michał Fedyna\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMichał Fedyna\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=michalfedyna\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/alexsad\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/2659613?v=4?s=100\" width=\"100px;\" alt=\"alex.query\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ealex.query\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=alexsad\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://www.antonytrupe.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/182436?v=4?s=100\" width=\"100px;\" alt=\"Tony Trupe\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTony Trupe\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Belphemur/node-json-db/commits?author=antonytrupe\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n    \n## Special Thanks\n\n[James Davis](https://github.com/davisjam) for helping to fix a regular expression vulnerable to [catastrophic backtracking](https://docs.microsoft.com/en-us/dotnet/standard/base-types/backtracking-in-regular-expressions).\n\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FBelphemur%2Fnode-json-await db.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2FBelphemur%2Fnode-json-db?ref=badge_large)\n","funding_links":["https://github.com/sponsors/Belphemur","https://soundswitch.aaflalo.me/#donate"],"categories":["TypeScript","typescript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBelphemur%2Fnode-json-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBelphemur%2Fnode-json-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBelphemur%2Fnode-json-db/lists"}