{"id":20974700,"url":"https://github.com/artus9033/tsdiskdb","last_synced_at":"2025-06-27T10:07:08.863Z","repository":{"id":42567838,"uuid":"282157092","full_name":"artus9033/tsdiskdb","owner":"artus9033","description":"A lightweight disk-based JSON database with a MongoDB-like API for Node, written in TypeScript. Port of the original diskdb, with types.","archived":false,"fork":false,"pushed_at":"2024-08-15T17:38:22.000Z","size":699,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T06:48:40.247Z","etag":null,"topics":["db","json","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artus9033.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2020-07-24T07:48:43.000Z","updated_at":"2025-03-21T22:58:34.000Z","dependencies_parsed_at":"2024-08-17T07:16:40.057Z","dependency_job_id":null,"html_url":"https://github.com/artus9033/tsdiskdb","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/artus9033/tsdiskdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artus9033%2Ftsdiskdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artus9033%2Ftsdiskdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artus9033%2Ftsdiskdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artus9033%2Ftsdiskdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artus9033","download_url":"https://codeload.github.com/artus9033/tsdiskdb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artus9033%2Ftsdiskdb/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259960323,"owners_count":22938041,"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":["db","json","nodejs","typescript"],"created_at":"2024-11-19T04:32:24.693Z","updated_at":"2025-06-27T10:07:08.832Z","avatar_url":"https://github.com/artus9033.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tsDiskDB\n\nA Lightweight Disk based JSON Database with a MongoDB like API for Node, written in TypeScript. Port of the original [`diskdb`](https://github.com/arvindr21/diskDB), with types.\n\n## Contents\n\n-   [tsDiskDB](#tsdiskdb)\n    -   [Contents](#contents)\n    -   [Getting Started](#getting-started)\n        -   [Load collections](#load-collections)\n            -   [Load multiple collections](#load-multiple-collections)\n        -   [Save models in a collection](#save-models-in-a-collection)\n        -   [Search a collection](#search-a-collection)\n        -   [Find many models in a collection](#find-many-models-in-a-collection)\n            -   [Find one model in a collection](#find-one-model-in-a-collection)\n        -   [Update a collection](#update-a-collection)\n        -   [Remove a collection](#remove-a-collection)\n        -   [Count models in a collection](#count-models-in-a-collection)\n-   [Appendix](#appendix)\n\n## Getting Started\n\nInstall the module:\n\n```bash\n$ npm install tsdiskdb\n```\n\nImport \u0026 intitialize it with:\n\n```ts\nvar db = require(\"tsdiskdb\");\n// or with the import syntax, if supported:\nimport db from \"tsdiskdb\";\n```\n\nThen, connect to a `.json` 'DB' with:\n\n```ts\ndb.connect(pathToFolder, [\"filename\"]);\n```\n\nWhere `filename` is the name of the `.json` file. You can omit the extension. This method also returns the instance itself so it can be used for chaining calls as well.\n\nThis will check for a directory at given path, if it does not exits, tsDiskDB will throw an error and exit.\n\nIf the directory exists but the file does not exist, tsDiskDB will create it for you.\n\n**Note** : If you have manually created a JSON file, please make sure it contains a valid JSON array, otherwise tsDiskDB\nwill return an empty array (`[]`).\n\n---\n\n### Load collections\n\nAlternatively you can also load collections with the following syntaxes:\n\n```ts\nvar db = require(\"tsdiskdb\");\n\n// variant 1\ndb = db.connect(\"/path/to/folder\");\ndb.loadCollections([\"articles\"]);\n\n// variant 2\ndb.connect(\"/path/to/folder\");\ndb.loadCollections([\"articles\"]);\n\n// variant 3\ndb.connect(\"/path/to/folder\").loadCollections([\"articles\"]);\n//or\ndb.connect(\"/path/to/folder\", [\"articles\"]);\n```\n\n#### Load multiple collections\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\", \"users\"]);\n```\n\n---\n\n### Save models in a collection\n\n```ts\ndb.collectionName.save(object);\n```\n\nOnce you have loaded a collection, you can access the collection's methods the following way:\n\n```ts\ndb.collectionName.methodName;\n```\n\nTo save a modified instance of a collection, use:\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"db\", [\"articles\"]);\n\nvar article = {\n\ttitle: \"Article 1\",\n\tpublished: \"today\",\n\trating: \"10/10\",\n};\n\ndb.articles.save(article);\n```\n\nThe saved data will be\n\n```ts\n[\n\t{\n\t\ttitle: \"Article 1\",\n\t\tpublished: \"today\",\n\t\trating: \"10/10\",\n\t\t_id: \"d6f39a8dc7494d19a3eb60a008e71cd9\",\n\t},\n];\n```\n\nYou can also save multiple objects at once:\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"db\", [\"articles\"]);\nvar article1 = {\n\ttitle: \"Article 1\",\n\tpublished: \"today\",\n\trating: \"10/10\",\n};\n\nvar article2 = {\n\ttitle: \"Article 2\",\n\tpublished: \"yesterday\",\n\trating: \"7/10\",\n};\n\ndb.articles.save([article1, article2]);\n```\n\nAnd this will return the inserted objects\n\n```ts\n[\n\t{\n\t\ttitle: \"Article 1\",\n\t\tpublished: \"today\",\n\t\trating: \"10/10\",\n\t\t_id: \"628574cc74384f8eb07236ef99140773\",\n\t},\n\t{\n\t\ttitle: \"Article 2\",\n\t\tpublished: \"yesterday\",\n\t\trating: \"7/10\",\n\t\t_id: \"fd976e7ba0c64eb8acc2855701c32dfb\",\n\t},\n];\n```\n\n---\n\n### Search a collection\n\nTo search a collection, use:\n\n-   `db.collectionName.find({ query })` to find many models matching the specified criteria\n-   `db.collectionName.findOne({ query })` to find just one model matching the specified criteria\n\n### Find many models in a collection\n\nUse the following code to find all models in a collection:\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.find();\n```\n\nThis will return all the records\n\n```ts\n[\n\t{\n\t\ttitle: \"tsdiskDB rocks\",\n\t\tpublished: \"today\",\n\t\trating: \"5 stars\",\n\t\t_id: \"0f6047c6c69149f0be0c8f5943be91be\",\n\t},\n];\n```\n\nYou can also query with a criteria that is a partial object of the original one stored.\n\nFor example:\n\n```ts\ndb.articles.find({ rating: \"7/10\", published: \"yesterday\" });\n```\n\nWith the data inside the collection fed by the aforementioned snippets, this would return:\n\n```json\n[\n\t{\n\t\t\"title\": \"Article 2\",\n\t\t\"published\": \"yesterday\",\n\t\t\"rating\": \"7/10\",\n\t\t\"_id\": \"fd976e7ba0c64eb8acc2855701c32dfb\"\n\t}\n]\n```\n\nSince tsDiskDB is mostly for lightweight data storage, avoid nested structures and huge datasets.\n\n#### Find one model in a collection\n\n```ts\ndb.articles.findOne();\n```\n\nIf you do not pass a query, tsDiskDB will return the first article in the collection. If you pass a query, it will return first article in the filtered data.\n\n```ts\ndb.articles.findOne({ _id: \"0f6047c6c69149f0be0c8f5943be91be\" });\n```\n\nNote that models can also be queried by their `_id` field, like above.\n\n---\n\n### Update a collection\n\n```ts\ndb.collectionName.update(query, data, options);\n```\n\nYou can also update one or many objects in the collection\n\n```ts\noptions = {\n\tmulti: false, // update multiple - default false\n\tupsert: false, // if object is not found, add it (update-insert) - default false\n};\n```\n\nSample usage:\n\n```ts\nvar query = {\n\ttitle: \"tsdiskDB rocks\",\n};\n\nvar dataToBeUpdated = {\n\ttitle: \"tsdiskDB rocks again!\",\n};\n\nvar options = {\n\tmulti: false,\n\tupsert: false,\n};\n\nvar updated = db.articles.update(query, dataToBeUpdated, options);\nconsole.log(updated); // { updated: 1, inserted: 0 }\n```\n\n---\n\n### Remove a collection\n\n```ts\ndb.collectionName.remove(query, multi);\n```\n\nYou can remove the entire collection (including the file) or you can remove the matched objects by passing in a query. When you pass a query, you can either delete all the matched objects or only the first one by passing `multi` as `false`. The default value of `multi` is `true`.\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.remove({ rating: \"5 stars\" });\n```\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.remove({ rating: \"5 stars\" }, true); // remove all matched. Default - multi = true\n```\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.remove({ rating: \"5 stars\" }, false); // remove only the first match\n```\n\nUsing remove without any params will delete the file and will remove the db instance.\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.remove();\n```\n\nAfter the above operation `db.articles` is `undefined`.\n\n---\n\n### Count models in a collection\n\n```ts\ndb.collectionName.count();\n```\n\nWill return the count of objects in the Collection\n\n```ts\nvar db = require(\"tsdiskdb\");\ndb.connect(\"/path/to/folder\", [\"articles\"]);\ndb.articles.count(); // will give the count\n```\n\n# Appendix\n\nThe project was originally based off [`diskdb`](https://github.com/arvindr21/diskDB) and is now a more advanced, improved version of the project, ported to TypeScript.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartus9033%2Ftsdiskdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartus9033%2Ftsdiskdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartus9033%2Ftsdiskdb/lists"}