{"id":15509545,"url":"https://github.com/huan/flash-store","last_synced_at":"2025-04-23T02:26:50.250Z","repository":{"id":33544568,"uuid":"104588803","full_name":"huan/flash-store","owner":"huan","description":"FlashStore is a high-performance Key-Value Persistent Local Database using ES6 Map's API (Async \u0026 Sync), Powered by LevelDB/RocksDB/SQLite and TypeScript.","archived":false,"fork":false,"pushed_at":"2022-03-05T05:53:08.000Z","size":349,"stargazers_count":20,"open_issues_count":7,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T04:40:29.311Z","etag":null,"topics":["database","nosql"],"latest_commit_sha":null,"homepage":"https://paka.dev/npm/flash-store","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-23T18:12:16.000Z","updated_at":"2024-09-10T06:06:56.000Z","dependencies_parsed_at":"2022-08-07T22:00:49.565Z","dependency_job_id":null,"html_url":"https://github.com/huan/flash-store","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huan%2Fflash-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huan%2Fflash-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huan%2Fflash-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huan%2Fflash-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huan","download_url":"https://codeload.github.com/huan/flash-store/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250356546,"owners_count":21417106,"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","nosql"],"created_at":"2024-10-02T09:43:11.146Z","updated_at":"2025-04-23T02:26:50.220Z","avatar_url":"https://github.com/huan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flash-store\n\n\u003c!-- markdownlint-disable MD013 --\u003e\n\n[![Powered by SQLite](https://img.shields.io/badge/Powered%20By-SQLite-green.svg)](https://https://www.sqlite.org/)\n[![Powered by LevelDB](https://img.shields.io/badge/Powered%20By-LevelDB-green.svg)](https://leveldb.org/)\n[![Powered by RocksDB](https://img.shields.io/badge/Powered%20By-RocksDB-green.svg)](https://rocksdb.org/)\n[![Powered by TypeScript](https://img.shields.io/badge/Powered%20By-TypeScript-blue.svg)](https://www.typescriptlang.org/)\n[![ES Modules](https://img.shields.io/badge/ES-Modules-brightgreen)](https://github.com/Chatie/tsconfig/issues/16)\n\n[![NPM Version](https://img.shields.io/npm/v/flash-store?color=brightgreen)](https://www.npmjs.com/package/flash-store)\n[![npm (next)](https://img.shields.io/npm/v/flash-store/next.svg)](https://www.npmjs.com/package/flash-store?activeTab=versions)\n[![GitHub Action](https://github.com/huan/flash-store/workflows/NPM/badge.svg)](https://github.com/huan/flash-store/actions?query=workflow%3ANPM)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)\n[![Downloads](http://img.shields.io/npm/dm/flash-store.svg?style=flat-square)](https://npmjs.org/package/flash-store)\n[![node](https://img.shields.io/node/v/flash-store.svg?maxAge=604800)](https://nodejs.org/)\n\nFlashStore is Key-Value persistent storage with easy to use ES6 Map-like API(both Async and Sync support), powered by LevelDB and TypeScript.\n\n![flash store](https://huan.github.io/flash-store/images/flash-store.png)\n\n## Requirements\n\n1. Node.js v10 or above\n\n## Examples\n\nTry the following command\n\n```shell\nnpm install\nnpm run demo\n```\n\nThe basic function as follows:\n\n```ts\nimport { FlashStore } from 'flash-store'\n\nconst flashStore = new FlashStore('flashstore.workdir')\n\nawait flashStore.set(1, 'a')\nconsole.log(`key: 1, value: ${await flashStore.get(1)}`)\n// Output: 'a'\n\nawait flashStore.del(1)\nconsole.log(`key: 1, value: ${await flashStore.get(1)}`)\n// Output: undefined\n```\n\n## Supported Backend\n\n| Backend | Flash Store | Install NPM Command |\n| :--- | :--- | :--- |\n| LevelDB |v1.0 | `npm install flash-store@1` |\n| SQLite | v0.20 | `npm install flash-store@0.20` |\n| Medea | v0.18 | ~~npm install flash-store@0.18~~ (deprecated) |\n| SnapDB | v0.16 | ~~npm install flash-store@0.16~~ (deprecated) |\n| RocksDB | v0.14 | `npm install flash-store@0.14` |\n| LevelDB |v0.12 | `npm install flash-store@0.12` |\n\n\u003e SnapDB \u0026 Medea were all deprecated because of lots of unknown bugs.\n\n## API Reference\n\n### `FlashStore`\n\nFlashStore implements the Standard ES6 Map API with Async modification, powered by [async-map-like](https://github.com/huan/async-map-like)\n\n```ts\n/**\n * ES6 Map API with Async\n */\nexport interface AsyncMap\u003cK = any, V = any\u003e {\n  [Symbol.asyncIterator]() : AsyncIterableIterator\u003c[K, V]\u003e\n  size                     : Promise\u003cnumber\u003e\n\n  clear   ()                 : Promise\u003cvoid\u003e\n  delete  (key: K)           : Promise\u003cvoid\u003e\n  entries()                  : AsyncIterableIterator\u003c[K, V]\u003e\n  get     (key: K)           : Promise\u003cV | undefined\u003e\n  has     (key: K)           : Promise\u003cboolean\u003e\n  keys    ()                 : AsyncIterableIterator\u003cK\u003e\n  set     (key: K, value: V) : Promise\u003cvoid\u003e\n  values  ()                 : AsyncIterableIterator\u003cV\u003e\n}\n\nclass FlashStore\u003cK, V\u003e implements AsyncMap\u003cK, V\u003e {}\n```\n\n### `FlashStoreSync`\n\nFlashStoreSync implements the Standard ES6 Map API:\n\n```ts\nclass FlashStoreSync\u003cK, V\u003e implements Map\u003cK, V\u003e {}\n```\n\n1. You get a sync API at the cost of all your data have to be kept in memory.\n1. The data will be async writing back to disk for persistent storage in background.\n1. The performance of `FlashStoreSync` can be expected high because it's all in memory.\n\n## Document\n\nSee [auto generated docs](https://huan.github.io/flash-store)\n\n* [ECMAScript 6: Maps - 2ality – JavaScript and more](http://2ality.com/2015/01/es6-maps-sets.html)\n\n## See Also\n\n1. [Node.js databases: an embedded database using LevelDB](https://blog.yld.io/2016/10/24/node-js-databases-an-embedded-database-using-leveldb)\n2. [How to Cook a Graph Database in a Night - LevelGraph](http://nodejsconfit.levelgraph.io/)\n3. [Graph database JS style for Node.js and the Browser. Built upon LevelUp and LevelDB.](https://github.com/levelgraph/levelgraph)\n4. [浅析 BigTable 和 LevelDB 的实现](http://draveness.me/bigtable-leveldb.html)\n\n## Known Issues\n\n1. The `gte` and `lte` in `options` do not work property. ([#4](https://github.com/huan/flash-store/issues/4))\n\n## Version History\n\n### master v1.3 (Sep 12, 2021)\n\n1. ES Modules support ([#93](https://github.com/huan/flash-store/pull/93))\n1. Remove default `workdir` in `FlashStore` constructor.\n\n### v1.0 (Aug 16, 2021) LevelDB v7.0\n\n[![Powered by LevelDB](https://img.shields.io/badge/Powered%20By-LevelDB-green.svg)](https://www.npmjs.com/package/level)\n\nLevelDB v7.0.0 support.\n\n### v0.20 Apr 2020 SQLite as Backend\n\n1. We hardcoded the key type to be `string` only in this version.\n1. We decide to try [better-sqlite3](https://www.npmjs.com/package/better-sqlite3) as it claim is very fast.\n1. The other alternates (would love to try in the future if necessary):\n    1. TypeScript: [sqlite](https://www.npmjs.com/package/sqlite)\n    1. WebAssembly: [sql.js](https://www.npmjs.com/package/sql.js)\n\n### ~~v0.18 Feb 2019 - Medea as Backend~~\n\n[![Powered by Medea](https://img.shields.io/badge/Powered%20By-Medea-green.svg)](https://www.npmjs.com/package/medeadown)\n\nDEPRECATED: Due to [#79](https://github.com/huan/flash-store/issues/79) [#74](https://github.com/huan/flash-store/issues/74) and also it is very unstable in production as my experiences. (e.g. memory leak \u0026 block event loop)\n\n1. Switch from SnapDB to [MedeaDown](https://github.com/medea/medeadown)\n\n[Medea](https://github.com/medea/medea) is a persistent key-value storage library that runs everywhere Node runs.\n\n\u003e \"It is a pure JS implementation of leveldown and it's almost as fast.\"\n\u003e \u0026mdash; @Raynos [link](https://github.com/medea/medeadown/issues/2#issue-38431966)  \n\u003e  \n\u003e \"The LevelDOWN-compatible wrapper for Medea really opens up the possibility to reuse the modules that have already been created around the LevelUP ecosystem.\"\n\u003e \u0026mdash; @kevinswiber [link](https://github.com/medea/medeadown/issues/2#issuecomment-49785861)\n\nKnown Issues: [FlashStore 会写满磁盘的问题 #155](https://github.com/wechaty/wechaty-puppet-padplus/issues/155)\n\n```ts\nasync function compact (store: FlashStore): Promise\u003cvoid\u003e {\n  await store.size\n  const db = (store as any).levelDb.db.db.db\n  await new Promise((resolve, reject) =\u003e {\n    db.compact((err: any) =\u003e {\n      if (err) {\n        return reject(err)\n      }\n      resolve()\n    })\n  })\n}\n```\n\n### v0.16 May 2019 - SnapDB as Backend\n\n[![Powered by SnapDB](https://img.shields.io/badge/Powered%20By-SnapDB-green.svg)](https://www.npmjs.com/package/snap-db)\n\n1. Switch from RocksDB to [SnapDB](https://github.com/ClickSimply/snap-db) [#45](https://github.com/huan/flash-store/issues/45)\n1. [#50](https://github.com/huan/flash-store/issues/50) has been fixed. ~~WARN: Do not use this version because it has known issues~~\n\n### v0.14 May 2019 - RocksDB as Backend\n\n1. Switch from LevelDB to [RocksDB](https://www.npmjs.com/package/rocksdb) [#34](https://github.com/huan/flash-store/issues/34)\n\n### v0.12 Jan 2019 - LevelDB as Backend\n\n1. Use [LevelDB](https://github.com/level/leveldown) as backend to skip the compiling when install.\n1. Using leveldb official typings from `@types/`\n\n### v0.7 Aug 2018 - Nosql-LevelDB as Backend\n\n1. Use [nosql-leveldb](https://github.com/snowyu/node-nosql-leveldb) as backend to prevent segfault.\n\n### v0.6 Jul 2018\n\n1. Upgrade to TypeScript 3.0\n\n### v0.4 Jun 2018\n\n#### 1. Refactor API to implement ES6 `Map` interface\n\n1. Update the API to ES6 `Map`-like, the difference is that FlashStore is all **async**.\n\n#### 2. Add `FlashStoreSync` as a in-memory **Write-back Cache** for Flash-Store\n\nAdd a new class `FlashStoreSync` which is a in-memory full loaded **Write-back Cache** for Flash-Store:\n\n1. Writes directly to `cache`, lazy writes to `store`.\n1. Reads from cache, never read-miss because cache have the full data of the store which will never expire.\n1. API of `FlashStoreSync` is the same as the ES6 `Map`\n\n### v0.2 Sep 2017\n\nInit version, API is LevelDB-like.\n\n## FAQ\n\n### Q: What's the difference between the `flash-store` and `memory-card`\n\nShort answer:\n\n1. `flash-store` is for save data to local filesystem.\n1. `memory-card` is for save data to a distributed network storage, it can be serialized/deserialized safely with the minimum payload transfered by design.\n\nLong answer:\n\n`flash-store` and `memory-card` are all built by @huan, and they are all follow the ES6 Map API.\n\n`flash-store` is using a no-sql local file database to maximum the performance, it can be used as a local database, or a local cache for whatever you want to cache from other API.\n\n`memory-card` is using a local file to store data in JSON format by default, however, it supports more distributed methods and it can be serialized/deserialized safely with the minimum payload for transfer the data between networks (for example, it can serialize itself to only include the `redis` config and then deserialize it to restore a MemoryCard instance with the same data backend). Learn more from it's repository at [here](https://github.com/huan/memory-card)\n\n## Author\n\n[Huan LI](https://github.com/huan) ([李卓桓](http://linkedin.com/in/zixia)) zixia@zixia.net\n\n[![Profile of Huan LI (李卓桓) on StackOverflow](https://stackexchange.com/users/flair/265499.png)](https://stackexchange.com/users/265499)\n\n## Copyright \u0026 License\n\n* Code \u0026 Docs © 2017-now Huan (李卓桓) \\\u003czixia@zixia.net\\\u003e\n* Code released under the Apache-2.0 License\n* Docs released under Creative Commons\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuan%2Fflash-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuan%2Fflash-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuan%2Fflash-store/lists"}