{"id":32119740,"url":"https://github.com/jswildcards/filedb","last_synced_at":"2026-02-21T03:02:02.328Z","repository":{"id":44364760,"uuid":"304201597","full_name":"jswildcards/filedb","owner":"jswildcards","description":":zap: A lightweight local JSON database for Deno.","archived":false,"fork":false,"pushed_at":"2021-01-18T08:18:16.000Z","size":50,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-20T18:32:52.426Z","etag":null,"topics":["database","deno","json"],"latest_commit_sha":null,"homepage":"","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/jswildcards.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2020-10-15T03:39:23.000Z","updated_at":"2024-07-31T20:29:41.000Z","dependencies_parsed_at":"2022-09-26T18:11:55.654Z","dependency_job_id":null,"html_url":"https://github.com/jswildcards/filedb","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jswildcards/filedb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jswildcards%2Ffiledb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jswildcards%2Ffiledb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jswildcards%2Ffiledb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jswildcards%2Ffiledb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jswildcards","download_url":"https://codeload.github.com/jswildcards/filedb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jswildcards%2Ffiledb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29672256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"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","deno","json"],"created_at":"2025-10-20T18:22:57.105Z","updated_at":"2026-02-21T03:02:02.322Z","avatar_url":"https://github.com/jswildcards.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FileDB\n\n![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/jswildcards/filedb/Deno/develop)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/jswildcards/filedb)\n![GitHub Release Date](https://img.shields.io/github/release-date/jswildcards/filedb)\n![LGTM Grade](https://img.shields.io/lgtm/grade/javascript/github/jswildcards/filedb)\n![deno-code-coverage](https://img.shields.io/badge/code%20coverage-93.97%25-brightgreen.svg)\n![GitHub Repo stars](https://img.shields.io/github/stars/jswildcards/filedb?style=social)\n![GitHub](https://img.shields.io/github/license/jswildcards/filedb)\n[![nest badge](https://nest.land/badge.svg)](https://nest.land/package/filedb)\n\n:zap: A lightweight local JSON database for Deno.\n\n## Why Use FileDB?\n\n- Simplicity: the module is semantic and easy to use.\n- Flexibility: the module have multiple implementations for different situations.\n- Suit with RESTful API: the module API is suited with RESTful API, you may refer to [this](https://github.com/jswildcards/filedb/blob/main/example/with_oak.ts) example.\n\n## Quick Start\n\n```bash\n$ git clone https://github.com/jswildcards/filedb.git\n$ cd ./filedb/example\n$ deno run --allow-read --allow-write hello_world.ts\n```\n\n## Getting Started\n\n### Setup\n\nLet's start with importing the FileDB module and creating a database.\n\n```ts\n// main.ts\nimport { FileDB, Document } from \"https://deno.land/x/filedb/mod.ts\";\nconst db = new FileDB({ rootDir: \"./data\", isAutosave: true }); // create database with autosave\n```\n\nThen, create a `User` collection. The `User` collection has three attributes: `firstName`, `lastName` and `favourites` - a list of fruits the user loves!\n\nTo achieve this step, we need to define a `User` interface with attributes, and get (and implicitly create!) the `User` collection from the database.\n\n```ts\n// main.ts\ninterface User extends Document {\n  firstName?: string;\n  lastName?: string;\n  favourites?: string[];\n}\nconst users = await db.getCollection\u003cUser\u003e(\"users\"); // implicitly create and get User collection\n```\n\n### Insert Records\n\nWe now have a `User` collection which can be inserted some records. Let's add one `User` first who is `fancy foo` and loves `🍎 Apple` and `🍐 Pear`.\n\n```ts\n// main.ts\nawait users.insertOne({\n  firstName: \"fancy\",\n  lastName: \"foo\",\n  favourites: [\"🍎 Apple\", \"🍐 Pear\"],\n});\n```\n\nGreat! We have our first records inserted into the collection. Now let's try inserting more `User` by using `insertMany` method.\n\n```ts\n// main.ts\nawait users.insertMany([\n  {\n    firstName: \"betty\",\n    lastName: \"bar\",\n    favourites: [\"🍌 Banana\"],\n  },\n  {\n    firstName: \"benson\",\n    lastName: \"baz\",\n    favourites: [\"🍌 Banana\"],\n  },\n]);\n```\n\n### Retrieve Records\n\nNow we have totally 3 `User` in our collection. We now want to know the information about `fancy foo`. We can use `findOne` method and pass a *filtered object* to do that.\n\n```ts\n// main.ts\nconsole.log(users.findOne({ firstName: \"fancy\", lastName: \"foo\" }));\n```\n\nGreat! But how about we now want to get *all* `User` who loves `🍌 Banana`? We can use `findMany` method and pass a `filter method` to do that. Remember to call `.value()` after calling the `findMany` method.\n\n```ts\n// main.ts\nconsole.log(users.findMany((el) =\u003e el.favourites?.includes(\"🍌 Banana\")).value());\n```\n\n### Update Records\n\nAs time goes by, some `User` may change their favourites. We now want to update **only the first** `User` who only loves `🍌 Banana` before, loves `🍎 Apple` and `🍐 Pear` only in this moment.\n\nIn this case, the database will update the `User betty bar` as obviously she was inserted into the database earlier than `User benson baz`. \n\n```ts\n// main.ts\nawait users.updateOne(\n  (el) =\u003e el.favourites?.[0] === \"🍌 Banana\",\n  { favourites: [\"🍎 Apple\", \"🍐 Pear\"] },\n);\n```\n\nNow we want to update **all** `User` whose `lastName` contains \"ba\". As besides love whatever they loved before, they all love \"🍉 Watermelon\" now.\n\n```ts\n// main.ts\nawait users.updateMany(\n  (el) =\u003e el.lastName?.includes(\"ba\"),\n  (el) =\u003e {\n    el.favourites = [\"🍉 Watermelon\", ...(el.favourites || [])];\n    return el;\n  },\n);\n```\n\n### Delete Records\n\nNow we want to delete some records in our database. First we delete **only one** `User` whose `firstName` is `fancy`.\n\n```ts\n// main.ts\nawait users.deleteOne({ firstName: \"fancy\" });\n```\n\nNow we want to delete **all** `User` whose has at least one favourites.\n\n```ts\n// main.ts\nawait users.deleteMany((el) =\u003e (el.favourites?.length ?? []) \u003e= 1);\n```\n\n### Drop Database\n\n```ts\n// main.ts\nawait db.drop();\n```\n\nThe whole example can be found [here](https://github.com/jswildcards/filedb/tree/main/example/hello_world.ts).\n\nThis module can do stuffs more than that! More examples can be found [here](https://github.com/jswildcards/filedb/tree/main/example).\n\n## Permission Required\n\nThis module requires `--allow-read` and `--allow-write` flags.\n\n## API\n\nPlease see the [documentation](https://doc.deno.land/https/deno.land/x/filedb/mod.ts).\n\n## Contribution\n\nWelcome to Contribute to this module. Read this [guideline](https://github.com/jswildcards/filedb/blob/main/CONTRIBUTING.md) to get started.\n\n## Disclaimer\n\nThis module is still unstable. So the module API may have breaking changes.\n\nThis module is only suitable for small-scaled projects. As when the database is large enough, it will be slow down with this file-based database structure and unoptimised searching algorithms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjswildcards%2Ffiledb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjswildcards%2Ffiledb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjswildcards%2Ffiledb/lists"}