{"id":16048264,"url":"https://github.com/elijah-trillionz/native-json-db","last_synced_at":"2025-11-03T16:03:06.627Z","repository":{"id":50284769,"uuid":"514868091","full_name":"Elijah-trillionz/native-json-db","owner":"Elijah-trillionz","description":"native-json-db offers a JSONDB class with methods for structuring, adding, removing, and updating data in the json file","archived":false,"fork":false,"pushed_at":"2023-03-13T08:44:55.000Z","size":112,"stargazers_count":12,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T17:03:42.635Z","etag":null,"topics":["community","database","hacktoberfest","json","mongodb","nodejs","open-source","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/native-json-db","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/Elijah-trillionz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-07-17T14:35:30.000Z","updated_at":"2024-04-03T14:54:22.000Z","dependencies_parsed_at":"2023-09-28T10:22:23.125Z","dependency_job_id":null,"html_url":"https://github.com/Elijah-trillionz/native-json-db","commit_stats":{"total_commits":42,"total_committers":2,"mean_commits":21.0,"dds":0.09523809523809523,"last_synced_commit":"2c0591f3ea80a3d5a54a7d8e024ca8097470b7d9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijah-trillionz%2Fnative-json-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijah-trillionz%2Fnative-json-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijah-trillionz%2Fnative-json-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijah-trillionz%2Fnative-json-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Elijah-trillionz","download_url":"https://codeload.github.com/Elijah-trillionz/native-json-db/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244156534,"owners_count":20407526,"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":["community","database","hacktoberfest","json","mongodb","nodejs","open-source","typescript","typescript-library"],"created_at":"2024-10-09T00:05:41.645Z","updated_at":"2025-11-03T16:03:06.569Z","avatar_url":"https://github.com/Elijah-trillionz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Native-JSON-DB or JSONDb is a NoSQL database system on your local server. With it, you can store data as JSON objects in a file in your server. native-json-db comes with TypeScript support, in fact using TypeScript is encouraged.\n\n**NOTE:** This library isn't yet efficient for large-scale applications with large ammount of users writing to the database. Use for personal applications or for your portfolio only.\n\n## Installation\n```shell\nnpm install native-json-db\n```\n\n\u003e __Note__: native-json-db supports importing with both ES modules and commonjs.\n\n## Introduction\n\nnative-json-db offers a `JSONDB` class with methods for structuring, adding, removing, and updating data in the json file. Each instance of this class you create can be considered as a collection. For example, let's create a collection of users, and add a few data:\n\n```js\nimport { JSONDB } from \"native-json-db\";\n\nconst users = new JSONDB('users'); // creates a \"users\" collection\n\nconst schema = {\n  type: 'object',\n  properties: {\n    username: { type: 'string' },\n    age: { type: 'number' }\n  }\n} \n\n(async () =\u003e {\n  await users.connect(schema, { writeSync: true, indentSpace: 2 });\n})();\n\nfunction addNewUser() {\n  users.create({ username: 'john_doe', age: 24 }) // creates a user's document\n}\naddNewUser();\n```\n\nThe example above represents a collection of users which in turn automatically creates a json file called __users__.\n\n## Schema\nnative-json-db uses [JSON Schema](https://json-schema.org/) for validating your JSON data.\n\nEach collection you create can have a different schema, but a schema made for a collection must be followed otherwise an error occurs (`614`).\n\nPass in your schema object as the first argument of the `connect` method.\n\n```js\nimport { JSONDB } from \"native-json-db\";\n\nconst users = new JSONDB('users');\n\nconst schema = {\n  type: 'object',\n  properties: {\n    name: { type: 'string' },\n    age: { type: 'number' }\n  }\n}\n\nusers.connect(schema);\n```\n\n## Methods\nAll methods are promises\n\u003cdetails\u003e\n\u003csummary\u003e\nAn example that utilises all methods\n\u003c/summary\u003e\n\n```js\nimport { JSONDB } from \"native-json-db\";\n\nconst users = new JSONDB(\"users\");\nconst schema = {\n  type: 'object',\n  required: ['name', 'age', 'id'],\n  properties: {\n    username: { type: 'string' },\n    age: { type: 'number' },\n    id: { anyOf: [{ type: \"number\" }, { type: \"string\" }] } // id can be of type number or string\n  }\n}\n\n(async () =\u003e {\n  await users.connect(schema, { writeSync: false, indentSpace: 3 });\n})();\n\n// backend programmer\nasync function addNewUser() {\n  try {\n    await users.create({\n      username: \"john_doe\",\n      id: 1,\n      age: 21,\n    });\n  } catch (err) {\n    console.log(err);\n  }\n}\n\nasync function getAllUsers() {\n  const res = await users.allData;\n  console.log(res); // [{ username: \"john_doe\", age: 21, id: 1 }]\n}\n\nasync function findUser() {\n  try {\n    const res = await users.findOne({ username: \"john_doe\" });\n    console.log(res); // { username: \"john_doe\", age: 21, id: 1 } \n  } catch (err) {\n    console.log(err);\n  }\n}\n\nasync function findUsers() {\n  try {\n    const res = await users.findMany({ username: \"john_doe\" });\n    console.log(res); // [{ username: \"john_doe\", age: 21, id: 1 }] \n  } catch (err) {\n    console.log(err);\n  }\n}\n\nasync function updateUser() {\n  try {\n    const res = await users.findOneAndUpdate(\n      { username: \"john_doe\" },\n      { age: \"25\" }\n    );\n    console.log(res);\n  } catch (err) {\n    console.log(err, \"error\"); // throws a schema 614 error, \"age\" is of type number\n  }\n}\n\nasync function updateMany() {\n  try {\n    const res = await users.updateMany(\n      { username: \"john_doe\" },\n      {\n        $inc: { age: 1 }, // increments \"age\" by 1\n      }\n    );\n    console.log(res); // [{ username: \"john_doe\", age: 22, id: 1 }]\n  } catch (e) {\n    console.log(e);\n  }\n}\n\nasync function findOneAndDelete() {\n  try {\n    const res = await users.findOneAndDelete({ username: \"unknown_user\" });\n    console.log(res);\n  } catch (e) {\n    console.log(e); // throws a 612 not found error\n  }\n}\n\nasync function deleteMany() {\n  try {\n    const res = await users.deleteMany(\n      { name: \"john_doe\" }\n    );\n    console.log(res); // [{ username: \"john_doe\", age: 22, id: 1 }]\n  } catch (e) {\n    console.log(e);\n  }\n}\n```\n\u003c/details\u003e\n\n### Connect\nThe `connect` method connects your collection to the database. Connecting is done only once for each collection and without connecting you can't use the other methods.\n\n```js\nconst schema = {\n  type: 'object',\n  properties: {\n    name: { type: 'string' },\n    age: { type: 'number' }\n  }\n}\n\nasync function connectToDb() {\n  await users.connect(schema, { writeSync: true, indentSpace: 3 });\n}\n```\n\nA 613 connection error is thrown if you try to connect more than once for each collection you create.\n\n#### Parameter(s)\n| parameter placeholder name | type     | description                                     |\n|----------------------------|----------|-------------------------------------------------|\n| schema                     | `string` | the schema object of the collection             |\n| options                    | `object` | an object of options, see below for description |\n\n##### Options Object\n| key           | type      | description                                                                                | default |\n|---------------|-----------|--------------------------------------------------------------------------------------------|---------|\n| `writeSync`   | `boolean` | indicates if writing to the json file (collection) is done synchronously or asynchronously | `false` |\n| `indentSpace` | `number`  | the indentation space for the JSON object                                                  | `2`     |\n\n#### Response\nThe `connect` method returns a `string` (\"connected\") as response.\n\n### Create\nThe `create` method creates a new document and attach the data to the collection.\n\n```js\nasync function addNewuser() {\n  const newUser = { username: 'john_doe', age: 21 }\n  const res = await users.create(newUser);\n  console.log(res); // done\n}\n```\n\n#### Parameter(s)\n| parameter placeholder name  | type     | description           |\n|-----------------------------|----------|-----------------------|\n| data                        | `object` | data for the document |\n\n#### Response\nThe `create` method returns a `string` (\"done\") as response.\n\n### findOne\nThe `findOne` method finds a document with a piece of data given as filter and returns the first occurrence found.\n\n```js\nasync function findUser() {\n  const res = await users.findOne({ username: 'john_doe' })\n  console.log(res)\n}\n```\n\n#### Parameter(s)\n| parameter placeholder name | type     | description                                  |\n|----------------------------|----------|----------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection |\n\n#### Response\n- When a result is found, the `findOne` method returns an object. This object being the first occurrence of the filter `object` found.\n\n- When no result is found, the `findOne` method resolves to `null`.\n\n### findMany\nThe `findMany` method finds a document with a piece of data given as filter and returns all occurrences found.\n\n```js\nasync function findUser() {\n  const res = await users.findOne({ username: 'john_doe' })\n  console.log(res)\n}\n```\n\n#### Parameter(s)\n| parameter placeholder name | type     | description                                    |\n|----------------------------|----------|------------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection   |\n\n\n#### Response\n- When a result is found, the `findMany` method returns an array of objects. This array being all occurrences of the filter `object` found.\n\n- When no result is found, the `findMany` method resolves with an empty array `[]`.\n\n### findOneAndUpdate\nThe `findOneAndUpdate` method finds a document with a piece of data given as filter and updates the document with a given data.\n\n```js\nasync function updateUser() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21 }] }\n  const res = await users.findOneAndUpdate({ username: 'john_doe' }, { username: 'john_doe4real' });\n  console.log(res) // { username: 'john_doe4real', age: 21 }\n}\n```\n\n#### Parameters\n| parameter placeholder name | type     | description                                  |\n|----------------------------|----------|----------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection |\n| newData                    | `object` | the new data to update document with         |\n\nWhile the `findOneAndUpdate` method can be used for updating existing data in a document, it can also be used to add data to a document as long as the data is valid with your schema.\n\n```js\nasync function updateUser() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe4real\", \"age\": 21 }] }\n  const res = await users.findOneAndUpdate({ username: 'john_doe4real' }, { followers: 30 });\n  console.log(res) // { username: 'john_doe4real', age: 21, followers: 30 }\n}\n```\n\nThere are special properties that can be used with the `newData` object to ease up updates like adding or removing from an array, incrementing and decrementing a number.\n\n#### Special properties\n| key     | type     | description                                         | example                                                                  |\n|---------|----------|-----------------------------------------------------|--------------------------------------------------------------------------|\n| `$inc`  | `object` | increments a number based on a given object         | `{ $inc: { age: 1 } }` - adds 1 to the age value                         |\n| `$dec`  | `object` | decrements a number based on a given object         | `{ $inc: { age: 1 } }` - removes 1 from the age value                    |\n| `$push` | `object` | pushes a value to the end of an array               | `{ $push: { cars: 'bmw' } }` - pushes \"bmw\" to the list of `cars`        |\n| `$pop`  | `object` | removes the first (0) or last (-1) item of an array | `{ $pop: { cars: -1 } }` - removes the last item from the list of `cars` |\n\n```js\nasync function updateUser() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe4real\", \"age\": 21, \"followers\": 30 }] }\n  const res = await users.findOneAndUpdate({ username: 'john_doe4real' }, { $inc: { followers: 5, age: 1 } });\n  console.log(res) // { username: 'john_doe4real', age: 22, followers: 35 }\n}\n```\n\n#### Response\n- When a result is found, the `findOneAndUpdate` method returns the updated object.\n\n- When no result is found, a `612 - Not Found` error is thrown.\n\n### updateMany\nThe `updateMany` method finds a group of documents with a piece of data given as filter and updates the documents with a given data.\n\n```js\nasync function updateUsers() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21, \"student\": true }, {\"username\": \"jane_doe\", \"age\": 24, \"student\": true }] }\n  const res = await users.updateMany({ student: true }, { promoted: true });\n  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: true }, {username: 'jane_doe', age: 24, student: true, promoted: true }]\n}\n```\n\n#### Parameters\n| parameter placeholder name | type     | description                                                  |\n|----------------------------|----------|--------------------------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection                 |\n| newData                    | `object` | the new data to update document with                         |\n| options                    | `object` | an object of options for specifying how the update should be |\n\n#### Options Object\n| key         | type      | description                                | default |\n|-------------|-----------|--------------------------------------------|---------|\n| `updateAll` | `boolean` | for updating all documents in a collection | `false` |\n\nThe `updateAll` property when set to `true` updates all documents in a collection with the new data:\n\n```js\nasync function updateAllUsers() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21, \"student\": true, \"promoted\": true }, {\"username\": \"jane_doe\", \"age\": 24, \"student\": true, \"promoted\": true }] }\n  const res = await users.updateMany({}, { promoted: false }, { updateAll: true });\n  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: false }, {username: 'jane_doe', age: 24, student: false }]\n}\n```\n\nThe special properties available on the [`findOneAndUpdate` method](https://linkspecialchars.com) is also available on the `updateMany` method.\n\n#### Response\n- When a result is found, the `updateMany` method returns an array of all the updated object.\n\n- When no result is found, a `612 - Not Found` error is thrown.\n\n### findOneAndDelete\nThe `findOneAndDelete` method finds a document with a piece of data given as filter and deletes the document found.\n\n```js\nasync function deleteUser() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21 }] }\n  const res = await users.findOneAndDelete({ username: 'john_doe' });\n  console.log(res) // { username: 'john_doe4real', age: 21 }\n  \n  // data/users.json = { \"users\": [] }\n}\n```\n\n#### Parameters\n| parameter placeholder name | type     | description                                  |\n|----------------------------|----------|----------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection |\n\n#### Response\n- When a result is found, the `findOneAndDelete` method returns the deleted object even though it does no longer exist in the collection\n\n- When no result is found, the promise is resolved with an empty object `{}`.\n- \n### deleteMany\nThe `deleteMany` method finds a group of documents with a piece of data given as filter and deletes the documents.\n\n```js\nasync function deleteUsers() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21 }, {\"username\": \"jane_doe\", \"age\": 24 }] }\n  const res = await users.deleteMany({ student: true });\n  console.log(res) // [{ username: 'john_doe', age: 21 }, {username: 'jane_doe', age: 24 }]\n  \n  // data/users.json = { \"users\": [] }\n}\n```\n\n#### Parameters\n| parameter placeholder name | type     | description                                                  |\n|----------------------------|----------|--------------------------------------------------------------|\n| filter                     | `object` | filter through the documents in a collection                 |\n| options                    | `object` | an object of options for specifying how the update should be |\n\n#### Options Object\n| key         | type      | description                                | default |\n|-------------|-----------|--------------------------------------------|---------|\n| `deleteAll` | `boolean` | for deleting all documents in a collection | `false` |\n\nThe `deleteAll` property when set to `true` deletes all documents in a collection:\n\n```js\nasync function deleteAllUsers() {\n  // data/users.json = { \"users\": [{ \"username\": \"john_doe\", \"age\": 21, \"student\": true, \"promoted\": true }, {\"username\": \"jane_doe\", \"age\": 24, \"student\": true, \"promoted\": true }] }\n  const res = await users.deleteMany({}, { deleteAll: true });\n  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: false }, {username: 'jane_doe', age: 24, student: false, promoted: true }]\n  \n  // data/users.json = { \"users\": [] }\n}\n```\n\n#### Response\n- When a result is found, the `deleteMany` method returns an array of the deleted objects.\n\n- When no result is found, the promise resolves with an empty array `[]`.\n\n## Error Codes\n| code no | title                             | description                                                                                                                                                                                  |\n|---------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `611`   | INVALID_DATA_TYPE                 | error when submitting a new data that isn't an object in JavaScript                                                                                                                          |\n| `612`   | NOT_FOUND                         | error when the filter data in any method does not find any occurrence                                                                                                                        |\n| `613`   | CONNECTION_ERROR                  | because the schema cannot be compiled more than once, the server must be connected only once in every collection, so this error is thrown if multiple connection is attempted per collection |\n| `614`   | INVALID_SCHEMA_RES:[SCHEMA_ERROR] | all schema data type errors                                                                                                                                                                  |\n| `615`   | BAD_REQUEST                       | error when the filter object does not contain key or/and value, exception of the `updateMany` and `deleteMany` methods when used to update and/or delete all documents respectively          |\n\n## Contributing\n\nDocs on contributing coming soon.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijah-trillionz%2Fnative-json-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felijah-trillionz%2Fnative-json-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijah-trillionz%2Fnative-json-db/lists"}