{"id":22859957,"url":"https://github.com/reelyactive/esmapdb","last_synced_at":"2025-03-31T08:22:46.432Z","repository":{"id":57230425,"uuid":"453101936","full_name":"reelyactive/esmapdb","owner":"reelyactive","description":"ESMapDB is an embedded database for Node.js with an ECMAScript Map interface.  We believe in an open Internet of Things.","archived":false,"fork":false,"pushed_at":"2022-12-05T22:31:10.000Z","size":28,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T23:27:01.521Z","etag":null,"topics":["database","embedded-database","javascript-map","leveldb","node-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/reelyactive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2022-01-28T14:40:20.000Z","updated_at":"2023-06-06T09:12:08.000Z","dependencies_parsed_at":"2023-01-24T07:01:35.450Z","dependency_job_id":null,"html_url":"https://github.com/reelyactive/esmapdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fesmapdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fesmapdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fesmapdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fesmapdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reelyactive","download_url":"https://codeload.github.com/reelyactive/esmapdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246436890,"owners_count":20777115,"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-database","javascript-map","leveldb","node-js"],"created_at":"2024-12-13T09:08:31.877Z","updated_at":"2025-03-31T08:22:46.410Z","avatar_url":"https://github.com/reelyactive.png","language":"JavaScript","readme":"ESMapDB\n=======\n\nESMapDB is an embedded database for Node.js with an ECMAScript Map interface.  For lightweight operations with key-value pairs, ESMapDB combines the convenient interface of a Map with a simple, persistent data store.\n\n\nMotivation\n----------\n\n_Yet another database???_  At [reelyActive](https://www.reelyactive.com), we used [NeDB](https://github.com/louischatriot/nedb), \"The JavaScript Database\", successfully for many years.  But alas, NeDB is no longer maintained.  After an extensive search for a simple, well-maintained successor with minimal dependencies, [LevelDB](https://github.com/google/leveldb) (wrapped up in the Node.js-friendly [level package](https://github.com/Level/level)) was identified as the best candidate.\n\n_So why not just LevelDB???_  Well, LevelDB is very nearly functionally equivalent with the [Map](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map) object introduced in ES6, so we decided to wrap LevelDB with a Map interface, which arguably results in more familiar, readable and developer-friendly code.  In short, we've attempted to make managing a reasonable number of key-value pairs—with persistence—as simple as using Map.get(), Map.set() and the usual iterators.\n\n\nHow ESMapDB works\n-----------------\n\nESMapDB can be instantiated with any combination of __in-memory__ _and/or_ __persistent__ operation.\n\nWhen in-memory operation is enabled, simply interact with ESMapDB like a Map, using .get(), .set(), .delete() and the iterators which function exactly like a Map.\n\nWhen persistent operation is enabled, simply add a callback function as an argument to the same .get(), .set(), .delete(), ... functions, which will execute once the asynchronous filesystem operation of LevelDB completes.\n\nWhen _both_ in-memory and persistent operation are enabled, enjoy the simple non-blocking function calls of the Map interface while the filesystem operations are taken care of in the background.\n\n\nInstallation\n------------\n\n    npm install esmapdb\n\n\nHello ESMapDB!\n--------------\n\n```javascript\nconst ESMapDB = require('esmapdb');\n\nconst options = { createInMemory: true,\n                  createPersistent: true };\n\nlet database = new ESMapDB(options);\n\ndatabase.set('key', 'value');     // Write to both memory and the filesystem\nconsole.log(database.get('key')); // Prints 'value'\n```\n\n\nAPI Reference\n-------------\n\nNote that in all methods with an _optional_ callback below, the callback function observes the form __callback(err, result)__ where the two parameters are defined as follows:\n- __err:__ Error returned by the persistent database operation, `undefined` otherwise.\n- __result:__ The same result that the function call itself returns, but taken from the persistent store, when persistent operation is enabled.  If persistent operation is disabled, the result is taken from the in-memory store.\n\nIn other words, when both in-memory _and_ persistent operation are enabled, the function call returns the result from the in-memory store while the asynchronous callback result is derived from the persistent store.\n\n### ESMapDB(options[, callback])\n\nConstructor.  Create a new ESMapDB instance with the given options:\n\n| Option                  | Default    | Description                           |\n|:------------------------|:-----------|:--------------------------------------|\n| createInMemory          | false      | Maintain an in-memory copy of the database |\n| createPersistent        | false      | Maintain a copy of the database on the filesystem |\n| persistentLocation      | 'database' | Store data in a folder called 'database' |\n| persistentKeyEncoding   | 'utf-8'    | See LevelDB for supported encodings   |\n| persistentValueEncoding | 'utf-8'    | See LevelDB for supported encodings   |\n\nIf an _optional_ callback is provided, and the `createPersistent` option is selected, the callback will execute after the persistent store is loaded or an error is encountered.\n\nAs of __esmapdb__ v0.3.0, errors encountered when loading a persistent store are no longer thrown, but may be observed in the _optional_ callback, and operation will continue as per the `createInMemory` setting.\n\n### .size\n\nReturns the number of key/value pairs in the database.  If in-memory option is enabled, the number of key/value pairs in the Map() is returned.  Else, an _estimate_ of the number of key/value pairs in persistent storage is returned.\n\n### .clear([callback])\n\nRemoves all key/value pairs from the database.  Returns `undefined`.\n\nIf an _optional_ callback is provided, and persistent operation is enabled, the callback will execute after the persistent store is cleared.  In the absence of a persistent store, the callback will execute immediately.\n\n### .delete(key[, callback])\n\nRemoves the pair with the given key from the database.  Returns `true` if the pair in the database existed and has been removed, or `false` if the element does not exist.\n\nIf an _optional_ callback is provided, and persistent operation is enabled, the callback will execute after deletion from the persistent store completes.  In the absence of a persistent store, the callback will execute immediately.\n\n### .get(key[, callback])\n\nRetrieve the value associated with the given key.  Returns the value associated to the key, or `undefined` if there is none.\n\nIf an _optional_ callback is provided, and persistent operation is enabled, the callback will execute after retrieval from the persistent store completes.  In the absence of a persistent store, the callback will execute immediately.\n\n### .has(key[, callback])\n\nDetermine whether a pair with the given key exists in the database.  Returns a boolean asserting whether a value has been associated to the key in the database or not.\n\nIf an _optional_ callback is provided, and persistent operation is enabled, the callback will execute after determination from the persistent store completes.  In the absence of a persistent store, the callback will execute immediately.\n\n### .set(key, value[, callback])\n\nCreate or update a key/value pair in the database.  Sets the value for the key in the database and returns the updated database as a Map object.  If in-memory operation is disabled, the return value will be an empty Map object.\n\nIf an _optional_ callback is provided, and persistent operation is enabled, the callback will execute after the update of the persistent store completes.  In the absence of a persistent store, the callback will execute immediately.\n\n### .keys()\n\nReturns a new Iterator object that contains the keys for each element in the in-memory database.  If in-memory operation is disabled, there will be zero keys over which to iterate.\n\n### .values()\n\nReturns a new Iterator object that contains the values for each element in the in-memory database.  If in-memory operation is disabled, there will be zero values over which to iterate.\n\n### .entries()\n\nReturns a new Iterator object that contains an array of [key, value] for each element in the in-memory database.  If in-memory operation is disabled, there will be zero pairs over which to iterate.\n\n### .forEach(callback)\n\nExecutes the callback once for each key-value pair present in the in-memory database.  If in-memory operation is disabled, there will be zero execution of the callback function.\n\n\nContributing\n------------\n\nDiscover [how to contribute](CONTRIBUTING.md) to this open source project which upholds a standard [code of conduct](CODE_OF_CONDUCT.md).\n\n\nSecurity\n--------\n\nConsult our [security policy](SECURITY.md) for best practices using this open source software and to report vulnerabilities.\n\n[![Known Vulnerabilities](https://snyk.io/test/github/reelyactive/esmapdb/badge.svg)](https://snyk.io/test/github/reelyactive/esmapdb)\n\n\nLicense\n-------\n\nMIT License\n\nCopyright (c) 2022 reelyActive\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR \nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, \nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE \nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER \nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, \nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN \nTHE SOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fesmapdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freelyactive%2Fesmapdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fesmapdb/lists"}