{"id":13992219,"url":"https://github.com/creationix/nstore","last_synced_at":"2025-04-05T05:04:55.106Z","repository":{"id":958877,"uuid":"745357","full_name":"creationix/nstore","owner":"creationix","description":"nStore is a simple, in-process key/value database for node.js","archived":false,"fork":false,"pushed_at":"2017-08-02T13:27:31.000Z","size":237,"stargazers_count":392,"open_issues_count":22,"forks_count":31,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-30T08:18:36.988Z","etag":null,"topics":[],"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/creationix.png","metadata":{"files":{"readme":"README.markdown","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":"2010-06-28T19:24:37.000Z","updated_at":"2024-09-08T22:23:13.000Z","dependencies_parsed_at":"2022-08-16T11:35:24.506Z","dependency_job_id":null,"html_url":"https://github.com/creationix/nstore","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creationix%2Fnstore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creationix%2Fnstore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creationix%2Fnstore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creationix%2Fnstore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/creationix","download_url":"https://codeload.github.com/creationix/nstore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289426,"owners_count":20914464,"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":[],"created_at":"2024-08-09T14:01:53.063Z","updated_at":"2025-04-05T05:04:55.085Z","avatar_url":"https://github.com/creationix.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# nStore\n\nA simple in-process key/value document store for node.js. nStore uses a safe append-only data format for quick inserts, updates, and deletes.  Also a index of all documents and their exact location on the disk is stored in in memory for fast reads of any document.  This append-only file format means that you can do online backups of the datastore using simple tools like rsync.  The file is always in a consistent state.\n\n## Warning\n\nThis library is still under development.  There are bugs.  APIs will change.  Docs may be wrong.\n\nKeep in mind this is something I make in my free time and that's something I've had very little of lately thanks to my many other projects.  I would love for someone with database and javascript smarts to partner with to make nStore super awesome.\n\n## Setup\n\nAll the examples assume this basic setup. Loading the database is async so there is a callback for when it's safe to query the database.\n\nCreating a database is easy, you just call the nStore function to generate a collection object.\n\n    // Load the library\n    var nStore = require('nstore');\n    // Create a store\n    var users = nStore.new('data/users.db', function () {\n      // It's loaded now\n    });\n\n\n## Creating a document\n\nTo insert/update documents, just call the save function on the collection.\n\n    // Insert a new document with key \"creationix\"\n    users.save(\"creationix\", {name: \"Tim Caswell\", age: 29}, function (err) {\n        if (err) { throw err; }\n        // The save is finished and written to disk safely\n    });\n\n    // Or insert with auto key\n    users.save(null, {name: \"Bob\"}, function (err, key) {\n        if (err) { throw err; }\n        // You now have the generated key\n    });\n\n## Loading a document\n\nAssuming the previous code was run, a file will now exist with the persistent data inside it.\n\n    // Load the document with the key \"creationix\"\n    users.get(\"creationix\", function (err, doc, key) {\n        if (err) { throw err; }\n        // You now have the document\n    });\n\n\n## Removing a document\n\nRemove is by key only.\n\n    // Remove our new document\n    users.remove(\"creationix\", function (err) {\n        if (err) { throw err; }\n        // The document at key \"creationix\" was removed\n    });\n\n## Clearing the whole collection\n\nYou can also quickly clear the entire collection\n\n    // Clear\n    users.clear(function (err) {\n      // The database is now empty\n    });\n\nThis clears all the keys and triggers a compaction.  Only after the compact finishes is the data truly deleted from the disk, however any further queries cannot see the old data anymore.\n\n## Querying the database\n\nThere are no indexes, however, nStore provides a simple query interface to get at data quickly and easily.  You can filter using `condition` expressions or plain functions.\n\nTo use queries, you need to include the query addon.\n\n    var nStore = require('nstore');\n    nStore = nStore.extend(require('nstore/query')());\n\n### Query as a single callback\n\nFor convenience you can pass in a callback and get the results as a single object.\n\n    // Using a callback for buffered results\n    users.find({age: 29}, function (err, results) {\n      // results is an object keyed by document key with the document as the value\n    });\n\n\n### Query using streams.\n\nAlso you can stream results.\n\n    var stream = users.find({age: 29});\n    stream.on(\"document\", function (doc, key) {\n      // This is a single document\n    });\n    stream.on(\"end\", function () {\n      // No more data is expected\n    })\n\n### `all` shortcut\n\nIf you want no condition you can use the `all()` shortcut.\n\n    users.all(function (err, results) {\n      // All the users are now in a single object.\n    });\n\n### Structure of `condition` expressions.\n\nA simple condition is pairs of key's and values.  This builds a condition where all columns named by the key must equal the corresponding value.\n\nThis matches rows where `name` is `\"Tim\"` and `age` is `29`:\n\n    {name: \"Tim\", age: 29}\n\nIf a key contains space, then the operator after it is used instead of equal.\n\nThis matches rows where `age` is greater than `18` and `age` is less than `50`:\n\n    {\"age \u003e\": 18, \"age \u003c\": 50}\n\nThe supported operators are:\n\n - `\u003c` - less than\n - `\u003c=` - less than or equal to\n - `\u003e=` - greater than or equal to\n - `\u003e` - greater than\n - `!=` or `\u003c\u003e` - not equal to\n  \nIf an array of hash-objects is passed in, then each array item is grouped and ORed together.\n\nThis matches `name` is `\"Tim\"` or `age` \u003c `8`:\n\n    [{name: \"Tim\"}, {\"age \u003c\": 8}]\n\n\n## Special compaction filter\n\nThere are times that you want to prune stale data from a database, like when using nStore to store session data.  The problem with looping over the index keys and calling `remove()` on them is that it bloats the file. Deletes are actually appends to the file.  Instead nStore exposes a special filter function that, if specified, will filter the data when compacting the data file.\n\n    // Prune any items that have a doc.lastAccess older than 1 hour.\n    var session = nStore.new('data/sessions.db', function () {\n      // It's loaded now\n    });\n    session.filterFn = function (doc, meta) {\n      return doc.lastAccess \u003e Date.now() - 360000;\n    };\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreationix%2Fnstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcreationix%2Fnstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreationix%2Fnstore/lists"}