{"id":29022031,"url":"https://github.com/jsweb/jsdb","last_synced_at":"2026-04-29T21:06:53.592Z","repository":{"id":42221982,"uuid":"165898308","full_name":"jsweb/jsdb","owner":"jsweb","description":"Simple NoSQL like embedded JSON database for modern Node.js applications.","archived":false,"fork":false,"pushed_at":"2022-12-29T18:52:13.000Z","size":203,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-03-02T05:31:21.447Z","etag":null,"topics":["database","embedded","javascript","js","json","nosql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/jsweb.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":"2019-01-15T17:59:19.000Z","updated_at":"2022-12-29T18:07:50.000Z","dependencies_parsed_at":"2023-01-31T09:30:39.748Z","dependency_job_id":null,"html_url":"https://github.com/jsweb/jsdb","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/jsweb/jsdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsweb%2Fjsdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsweb%2Fjsdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsweb%2Fjsdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsweb%2Fjsdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsweb","download_url":"https://codeload.github.com/jsweb/jsdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsweb%2Fjsdb/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261987995,"owners_count":23240946,"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","embedded","javascript","js","json","nosql"],"created_at":"2025-06-26T02:37:32.980Z","updated_at":"2026-04-29T21:06:48.573Z","avatar_url":"https://github.com/jsweb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @jsweb/jsdb\n\nSimple NoSQL like embedded JSON database for modern Node.js applications.\n\n- Vanilla JSON data store\n- Vanilla Javascript API\n- Multiple JSON files (one for each store)\n- Asynchronous\n- Fast enought\n\nNot tested with large applications in production, but recommended for small to medium applications (almost all).\n\n***\n\n- [@jsweb/jsdb](#jswebjsdb)\n  - [Install](#install)\n  - [Usage](#usage)\n  - [JSON files](#json-files)\n  - [Auto ID](#auto-id)\n  - [Auto optimization](#auto-optimization)\n  - [Database intance](#database-intance)\n    - [Auto timestamps](#auto-timestamps)\n    - [Methods](#methods)\n      - [drop (name: string)](#drop-name-string)\n      - [store(name: string)](#storename-string)\n  - [Store instance](#store-instance)\n    - [Methods](#methods-1)\n      - [parse()](#parse)\n      - [truncate()](#truncate)\n      - [push(...args: any[])](#pushargs-any)\n      - [find(find: function)](#findfind-function)\n      - [filter(filter: function)](#filterfilter-function)\n      - [update(value: any, find?: function)](#updatevalue-any-find-function)\n      - [replace(value: any, find?: function)](#replacevalue-any-find-function)\n      - [delete(id: string, find?: function)](#deleteid-string-find-function)\n      - [filterUpdate(value: any, filter: function)](#filterupdatevalue-any-filter-function)\n      - [filterReplace(value: any, filter: function)](#filterreplacevalue-any-filter-function)\n      - [filterDelete(filter: function)](#filterdeletefilter-function)\n  - [TODO](#todo)\n\n## Install\n\n```\nnpm i -S @jsweb/jsdb\n\n# or\n\nyarn add @jsweb/jsdb\n```\n\n## Usage\n\n```javascript\nimport { Database } from '@jsweb/jsdb'\n\nconst db = new Database('base', 'path', 'dir') // or just base/path/dir\n\nconst posts = db.store('posts') // a JSON store into db\n```\n\nYou don't need to create paths or files, **@jsweb/jsdb** will do the trick for you.\n\nThe base path directory is relative to de process root directory. It will be automatically detected using `process.cwd()`.\n\n## JSON files\n\nAll your data will be stored in JSON files. The root object in the JSON is an Array and expects to store Objects. Like this:\n\n```javascript\n[\n  { id: '...', name: 'John Doug', age: 28 },\n  { id: '...', name: 'Jane Doug', age: 26 },\n  { id: '...', name: 'Lorem Ipsum', age: 75 }\n]\n```\n\nThese objects are NoSQL like documents. So, no fixed model is required, they can be completely diferent.\n\nIt is just it, simple and vanilla JSON.\n\nAnd if do you already have a JSON file full of data, just drop it into de database directory. It just works.\n\n## Auto ID\n\n`id` fields will be auto generated for each entry.\n\nHere we have an immutable rule: `id` is only generated by **@jsweb/jsdb** and it is not possible to overwrite it, even if you provide one.\n\nThe only way you can edit `id` is editting the JSON file directly.\n\nIf you need to look at your data by indexing the value provided by yourself, just include a key/value into the Object.\n\n**@jsweb/jsdb** have simple methods to `find` and `filter` your data by any field or rule.\n\n## Auto optimization\n\n**@jsweb/jsdb** checks `NODE_ENV` enviroment variable to optimize JSON files into db.\n\nIf you are running in `production` mode, then JSON will be minimized. Else it will be indented to develop, test or debug.\n\n## Database intance\n\nJust import and instance a database into a base path.\n\nDatabase instance have a public `get` for the base dir absolute path, and public `get/set` for auto timestamps.\n\n```javascript\nimport { Database } from '@jsweb/jsdb'\n\nconst db = new Database('base', 'path', 'dir')\n\ndb.path // get (only) full OS path to database dir\n\ndb.timestamps // it is false by default\n\ndb.timestamps = true // now it is true\n```\n\n### Auto timestamps\n\nUse it to set auto timestamps on/off (default off).\n\nTurning on auto timestamps will include `createdAt` and `updatedAt` automatic fields on all entries. Values will be datetime strings, resulting from `new Date()` native object serialized to JSON.\n\n### Methods\n\n#### drop (name: string)\n\nUse it to drop a store from database. JSON file will be deleted.\n\n```javascript\nimport { Database } from '@jsweb/jsdb'\n\nconst db = new Database('base', 'path', 'dir')\n\ndb.drop('posts')\n```\n\n#### store(name: string)\n\nUse it to instance a JSON store from database. JSON file will be created, if it not exists.\n\n```javascript\nimport { Database } from '@jsweb/jsdb'\n\nconst db = new Database('base', 'path', 'dir')\n\nconst posts = db.store('posts')\n```\n\nThis method returns a Store instance, with methods to operate data in JSON files.\n\n## Store instance\n\nThis istance is the object to interact with JSON data.\n\nLike database instance, store have a public `get` for the JSON file absolute path.\n\n### Methods\n\nAll methods from store instance are `async`, so it is necessary to use them in Promise like syntax or with `async/await` functions.\n\nExemple:\n\n```javascript\nimport { Database } from '@jsweb/jsdb'\n\nconst db = new Database('base', 'path', 'dir')\n\nconst posts = db.store('posts')\n\nconst allPosts = await posts.parse()\n// or\nposts.parse().then(allPosts =\u003e {\n  // ...\n})\n```\n\n#### parse()\n\nParses data from JSON file and returns it to use in code.\n\n#### truncate()\n\nIt is to clean the store data and make it empty.\n\n#### push(...args: any[])\n\nIt is just native `Array.push` (but async), adding new entries to data store.\n\n#### find(find: function)\n\nIt is just native `Array.find` (but async), picking an entry from data store which match the `find` function return. If none match, returns `undefined`.\n\n#### filter(filter: function)\n\nIt is just native `Array.filter` (but async), picking entries from data store which match the `filter` function return. If none match, returns `[]`.\n\n#### update(value: any, find?: function)\n\nUpdates an entry in data store by assign `value` to target entry, merging data. Same effect as `Object.assign(entry, value)`.\n\n`value` must be a literal object with `keys/values` for update.\n\nIf `id` is present in `value`, the entry for update will be picked by `id`.\n\nOptionally, `find` function can be used like `Array.find(function)` to pick into data store the exact entry for update.\n\nOnly entry `id` will be automatically preserved by store because it is immutable, cannot be reassigned.\n\n#### replace(value: any, find?: function)\n\nWorks the same way as `update` method, but updates an entry in data store by replacing it. Same effect as `entry = value`.\n\n#### delete(id: string, find?: function)\n\nDeletes an entry from data store.\n\nIf `id` is provided, picks the entry by `id` for delete.\n\nOptionally, it is possible to pass `null` for `id` and `find` function can be used like `Array.find(function)` to pick into data store the exact entry for delete.\n\n#### filterUpdate(value: any, filter: function)\n\nAs the name suggests, this is a convenient method combining `filter` + `update` methods for batch updates.\n\n`value` must be a literal object with `keys/values` for update.\n\nIf `id` is present in `value`, `update` method will be invoked instead and only one entry will be updated by `id`.\n\nElse, `filter` function will be used the way like `Array.filter(function)` to match all entries for update.\n\n#### filterReplace(value: any, filter: function)\n\nWorks the same way as `filterUpdate`, but combines `filter` + `replace` methods.\n\n#### filterDelete(filter: function)\n\nCombines `filter` + `delete` methods for batch deletes.\n\n***\n\n## TODO\n\n- [ ] Paginate list results\n- [ ] Browser version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsweb%2Fjsdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsweb%2Fjsdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsweb%2Fjsdb/lists"}