{"id":49182795,"url":"https://github.com/simple-works/fsdb","last_synced_at":"2026-04-23T02:04:19.261Z","repository":{"id":42838484,"uuid":"264100595","full_name":"simple-works/fsdb","owner":"simple-works","description":"🗃️ Simple NodeJS File System Database.","archived":false,"fork":false,"pushed_at":"2026-03-18T03:49:25.000Z","size":118,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-03-18T11:37:14.577Z","etag":null,"topics":["database","file","file-data-storage","file-database","filesystem","fs-db","fsdb","javascript","nodejs","nodejs-fs","nodejs-library"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simple-works.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-15T05:04:21.000Z","updated_at":"2026-03-18T03:49:23.000Z","dependencies_parsed_at":"2023-01-30T16:01:48.391Z","dependency_job_id":null,"html_url":"https://github.com/simple-works/fsdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simple-works/fsdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple-works%2Ffsdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple-works%2Ffsdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple-works%2Ffsdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple-works%2Ffsdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simple-works","download_url":"https://codeload.github.com/simple-works/fsdb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple-works%2Ffsdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"online","status_checked_at":"2026-04-23T02:00:06.710Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","file","file-data-storage","file-database","filesystem","fs-db","fsdb","javascript","nodejs","nodejs-fs","nodejs-library"],"created_at":"2026-04-23T02:04:02.148Z","updated_at":"2026-04-23T02:04:19.218Z","avatar_url":"https://github.com/simple-works.png","language":"JavaScript","readme":"# fsdb (File System Database)\n\nSimple NodeJS File System Database.\n\n\u003c!-- toc --\u003e\n\n- [Install](#install)\n- [Getting Started](#getting-started)\n- [Initialize](#initialize)\n- [CREATE](#create)\n  - [CREATE Examples](#create-examples)\n  - [CREATE Queries](#create-queries)\n  - [CREATE Options](#create-options)\n- [READ](#read)\n  - [READ Examples](#read-examples)\n  - [READ Queries](#read-queries)\n  - [READ Options](#read-options)\n- [UPDATE](#update)\n  - [UPDATE Examples](#update-examples)\n  - [UPDATE Queries](#update-queries)\n  - [UPDATE Options](#update-options)\n- [DELETE](#delete)\n  - [DELETE Examples](#delete-examples)\n  - [DELETE Queries](#delete-queries)\n  - [DELETE Options](#delete-options)\n- [Other](#other)\n\n\u003c!-- tocstop --\u003e\n\n## Install\n\n```bash\nnpm install amb-fsdb\n```\n\n## Getting Started\n\n```javascript\n// Require library\nconst fsdb = require(\"amb-fsdb\");\n\n// Initialize database\nconst db = await fsdb();\n\n// Create a new item within a collection named \"players\"\n// If the collection doesn't exist it will be created automatically\nawait db(\"players\").create({\n  name: \"ambratolm\",\n  level: 99,\n  inventory: [\"sword\", \"shield\", \"potion\"]\n});\n\n// Read all items in \"players\" collection\nconst players = await db(\"players\").read();\nconsole.log(players);\n```\n\nA database JSON file named `db.json` will be created in the current directory with the following content:\n\n```json\n{\n  \"players\": [\n    {\n      \"name\": \"ambratolm\",\n      \"level\": 99,\n      \"inventory\": [\"sword\", \"shield\", \"potion\"],\n      \"id\": \"c8256c53-44ba-4ef4-bc89-e6e9a400fc0c\",\n      \"createdAt\": \"2020-09-28T02:01:39.064Z\"\n    }\n  ]\n}\n```\n\nThe `Id` and `createdAt` fields are created automatically.\n\n## Initialize\n\n```javascript\n// Initialize with a \"db.json\" file in the current directory\nconst db = await fsdb();\n\n// Initialize with a custom named \".json\" file in current directory\nconst db = await fsdb(\"my-database-file\");\n\n// Initialize with a custom named \".json\" file in the specified directory\nconst db = await fsdb(\"my-database-file\", \"../some/directory\");\n```\n\n## CREATE\n\n```javascript\nawait db(collectionName).create(item, options);\n```\n\nCreates a new item in a collection.\nIf the specified collection doesn't exist it will be created automatically.\nThe created item is returned.\n\n| Parameter      | Type   | Default | Description                             |\n| -------------- | ------ | ------- | --------------------------------------- |\n| collectionName | string |         | Targeted collection                     |\n| item           | object |         | Item to create                          |\n| options        | object | {}      | Additional options                      |\n| **@returns**   | object |         | The created item                        |\n| **@throws**    | Error  |         | If a unique field value is already used |\n| **@throws**    | Error  |         | If a value to encrypt is not a string   |\n\n### CREATE Examples\n\n```javascript\n// Create an item within a collection named \"players\" (automatically created)\n// The created item is returned\nconst createdPlayer = await db(\"players\").create({\n  name: \"ambratolm\",\n  level: 99,\n  inventory: [\"sword\", \"shield\", \"potion\"]\n});\n\n// Create an item within a collection named \"players\" with some options\nconst createdPlayer = await db(\"players\").create(\n  {\n    name: \"ambratolm\",\n    level: 99,\n    inventory: [\"sword\", \"shield\", \"potion\"],\n    password: \"this_is_a_secret\"\n  },\n  {\n    // Options\n    unique: [\"name\"], // Make \"name\" field unique\n    encrypt: [\"password\"], // Encrypt \"password\" field\n    omit: [\"password\", \"level\"], // Omit fields in the returned item object\n    nocase: true // Ignore case when comparing strings\n  }\n);\n```\n\n### CREATE Queries\n\nNo Queries.\n\n### CREATE Options\n\n| Propperty | Type     | Default | Description                     |\n| --------- | -------- | ------- | ------------------------------- |\n| unique    | string[] | []      | Fields to make unique           |\n| encrypt   | string[] | []      | Fields to encrypt               |\n| pick      | string[] | []      | Fields to pick in returned item |\n| omit      | string[] | []      | Fields to omit in returned item |\n| nocase    | boolean  | false   | Ignore case in search           |\n\n## READ\n\n```javascript\nawait db(collectionName).read(query, options);\n```\n\nReads an existing item in a collection.\nIf the specified collection doesn't exist it will be created automatically.\nThe read item is returned.\n\n| Parameter      | Type   | Default | Description                       |\n| -------------- | ------ | ------- | --------------------------------- |\n| collectionName | string |         | Targeted collection               |\n| query          | object |         | Query object or function          |\n| options        | object | {}      | Additional options                |\n| **@returns**   | object |         | The read item                     |\n| **@throws**    | Error  |         | If an encrypted field not matched |\n\n### READ Examples\n\n```javascript\n// Read all items in \"players\" collection\nconst players = await db(\"players\").read();\n\n// Read items matching a query object\nconst somePlayers = await db(\"players\").read({ name: \"ambratolm\" });\n\n// Read items matching a query function\nconst someOtherPlayers = await db(\"players\").read(player =\u003e player.level \u003e= 90);\n\n// Read items matching a query with some options\nconst player = await db(\"players\").read(\n  { name: \"AmBrAtOlM\" },\n  {\n    // Options\n    nocase: true, // Ignore case when comparing strings\n    one: true // return only one result (an object instead of array)\n  }\n);\n```\n\n### READ Queries\n\n...\n\n### READ Options\n\n...\n\n## UPDATE\n\n```javascript\nawait db(collectionName).update(query, changes, options);\n```\n\nUpdates an existing item in a collection.\nIf the specified collection doesn't exist it will be created automatically.\nThe updated item is returned.\n\n| Parameter      | Type   | Default | Description                             |\n| -------------- | ------ | ------- | --------------------------------------- |\n| collectionName | string |         | Targeted collection                     |\n| query          | object |         | Query object or function                |\n| changes        | object |         | Changes to apply                        |\n| options        | object | {}      | Additional options                      |\n| **@returns**   | object |         | The updated item                        |\n| **@throws**    | Error  |         | If Items matching query not found       |\n| **@throws**    | Error  |         | If a unique field value is already used |\n| **@throws**    | Error  |         | If a value to encrypt is not a string   |\n\n### UPDATE Examples\n\n```javascript\n// Update item(s)\n// The updated item is returned\nconst updatedPlayer = await db(\"players\").update(\n  { name: \"ambratolm\" }, // Query can also be a function\n  { name: \"new name\", level: 0 } // Changes to apply\n);\n\n// Update item(s) with some options\nconst updatedPlayer = await db(\"players\").update(\n  { name: \"ambratolm\" }, // Query can also be a function\n  { name: \"new name\", level: 0 }, // Changes to apply\n  {\n    // Options\n  }\n);\n```\n\n### UPDATE Queries\n\n...\n\n### UPDATE Options\n\n...\n\n## DELETE\n\n```javascript\nawait db(collectionName).delete(query, options);\n```\n\nDeletes an existing item in a collection.\nIf the specified collection doesn't exist it will be created automatically.\nThe deleted item is returned.\n\n| Parameter      | Type   | Default | Description                       |\n| -------------- | ------ | ------- | --------------------------------- |\n| collectionName | string |         | Targeted collection               |\n| query          | object |         | Query object or function          |\n| options        | object | {}      | Additional options                |\n| **@returns**   | object |         | The deleted item                  |\n| **@throws**    | Error  |         | If Items matching query not found |\n\n### DELETE Examples\n\n```javascript\n// Delete item(s)\n// The deleted item is returned\nconst deletedPlayer = await db(\"players\").delete(\n  { name: \"ambratolm\" } // Query can also be a function\n);\n\n// Delete item(s) with some options\nconst deletedPlayer = await db(\"players\").delete(\n  { name: \"ambratolm\" }, // Query can also be a function\n  {\n    // Options\n  }\n);\n```\n\n### DELETE Queries\n\n...\n\n### DELETE Options\n\n...\n\n## Other\n\n```javascript\n// Remove all collections\nawait db.drop();\n\n// Remove a collection named \"players\"\nawait db(\"players\").drop();\n\n// Remove all items in a collection named \"players\" and keep it\nawait db(\"players\").clear();\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimple-works%2Ffsdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimple-works%2Ffsdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimple-works%2Ffsdb/lists"}