{"id":17033491,"url":"https://github.com/morgul/dustbin","last_synced_at":"2025-04-12T12:51:36.627Z","repository":{"id":8011338,"uuid":"9419622","full_name":"Morgul/dustbin","owner":"Morgul","description":"A slim wrapper around localStorage and sessionStorage that allows for NoSQL style access. It's basically a JSON-backed object database for your web browser.","archived":false,"fork":false,"pushed_at":"2013-04-17T02:59:25.000Z","size":284,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-26T07:36:28.634Z","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/Morgul.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":"2013-04-13T20:25:26.000Z","updated_at":"2016-03-31T03:13:13.000Z","dependencies_parsed_at":"2022-08-06T04:15:34.047Z","dependency_job_id":null,"html_url":"https://github.com/Morgul/dustbin","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/Morgul%2Fdustbin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Fdustbin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Fdustbin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morgul%2Fdustbin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Morgul","download_url":"https://codeload.github.com/Morgul/dustbin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571400,"owners_count":21126517,"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-10-14T08:34:59.691Z","updated_at":"2025-04-12T12:51:36.609Z","avatar_url":"https://github.com/Morgul.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dustbin JS\n\n[![Build Status](https://travis-ci.org/Morgul/dustbin.png?branch=master)](https://travis-ci.org/Morgul/dustbin)\n\nA JSON-backed object database for your web browser. It's a light wrapper around local/session storage, designed to\nbehave much like a standard NoSQL database. (In fact, it's design is heavily influenced by [Riak](http://basho.com/riak/),\nmy personal favoriate NoSQL.)\n\n## Overview\n\nDustbin has the concepts of 'bins', which are loosely analogous to tables in SQL, or collections/buckets in NoSQL.\nBasically, they are collections of objects able to be referenced by a name. (In fact, Dustbin simply uses an anonymous\nobject for each bin).\n\nInside each bin, objects are stored by key. Keys are _always_ strings, but they can be any key you can set on a\njavascript object. The objects that are stored _must_ be able to be turned into a JSON string. That is the only\nrestriction. (Really, it's the cost of doing business with localStorage; it doesn't support storage of objects,\nonly strings and integers.)\n\n### Metadata support\n\nDustbin does modify the stored objects _slightly_. In each object, it adds a key called `$metadata`, which stores useful\ninformation about the object, such as the key, and the bucket it was saved in, or the creation time. This object is for\nboth internal use, as well as providing possibly useful data to the user. You may store whatever additional data you\nwould like in the object; just be aware that whenever the object is stored, Dustbin will always override `key`,\n`bucket`, and `updated`.\n\nCurrently, here is an example `$metadata` object:\n\n```javascript\n{\n    key: \"someKey\",\n    bin: \"someBin\",\n    created: \"Tue Apr 15 2013 23:05:42 GMT-0500 (CDT)\",\n    updated: \"Tue Apr 16 2013 09:01:38 GMT-0500 (CDT)\"\n}\n```\n\nIt should be noted that `created` and `updated` are _always_ strings. You can turn them into `Date` objects trivially:\n\n```javascript\n    var createdDate = new Date(obj.$metadata.created);\n```\n\n## Usage\n\nUsing Dustbin is incredibly easy. When you include dustbin, it creates a new object on window, called `dustbin`. Here's\nan example of basic usage:\n\n```javascript\nvar obj = {'foo': \"bar\"};\n\n// Store the object.\ndustbin.store(\"testBin\", \"testObj\", obj);\n\n// Store an object if it already contains metadata.\ndustbin.store(obj);\n\n// Retrieve it by key.\nobj = dustbin.get(\"testBin\", \"testObj\");\n\n// Alternative syntax.\nobj = dustbin.get(\"testBin\")[\"testObj\"];\n```\n\nThat's all there is to it!\n\n### RequireJS support\n\nRecently, I've added support for RequireJS. While it's optional (and will remain so), the support seems to work very\nwell. You can simply use it like any other RequireJS module:\n\n```javascript\nrequire(['dustbin'], function(dustbin)\n{\n    var key = dustbin.store(\"testBin\", obj);\n});\n```\n\nThough the support has been tested (and is part of the unit tests), I still consider the RequireJS support experimental.\nIf you encounter any issues, please file a ticket. (Make sure to include a test case!)\n\n### Auto-generated Keys\n\nYou're not required to have a key to store your object under. Dustbin will automatically generate a key for you if you\ndon't pass one in:\n\n```javascript\nvar obj = {'foo': \"bar\"};\n\n// Store the object.\nvar key = dustbin.store(\"testBin\", obj);\n\n// Key will be something like: \"LTMwMzk5OTQ2MA==\"\nconsole.log(\"Key:\", key);\n\n// Retrieve it by key.\nobj = dustbin.get(\"testBin\", key);\n```\n\n### Retrieve entire bin object\n\nYou can also retrieve the entire bin object:\n\n```javascript\nbin = dustbin.get(\"testBin\");\n```\n\nThis allows for the alternative (and in my opinion, cleaner) syntax:\n\n```javascript\nobj = dustbin.get(\"testBin\")[\"testObj\"];\n```\n\n### Remove an object\n\nYou can remove an object by key:\n\n```javascript\ndustbin.remove(\"testBin\", \"testObj\");\n```\n\n### Remove all objects in a bin\n\nYou can even remove all objects from a bin:\n\n```javascript\ndustbin.removeAllKeys(\"testBin\");\n```\n\n### Basic Query support\n\nCurrently, only basic query support has been added. You will need to construct an object containing `key` and `value`\nwhere you want back a list of object that have `key` equal to `value`. Here's an example:\n\n```javascript\nvar alex = {animal:\"cat\", name: \"alex\", age: 4};\nvar izzy = {animal:\"cat\", name: \"izzy\", age: 4};\nvar baal = {animal:\"snake\", name: \"baal\", age: 2};\n\ndustbin.store(\"pets\", alex);\ndustbin.store(\"pets\", izzy);\ndustbin.store(\"pets\", baal);\n\n// `cats` will be equal to `[alex, izzy]`\nvar cats = dustbin.query(\"pets\", {animal: \"cat\"});\n\n// `pets` will be equal to `[alex, izzy, baal]`\nvar pets = dustbin.query(\"pets\", {});\n```\n\nRight now the only thing supported is pure _equality_, **not** _equivalence_. Also, this is basically two nested `forEach`\ncalls, so performance isn't as good as it could be. I'll be looking at improving this in the future, but for now it\nshould meet most needs.\n\n### Session store support\n\nAll operations can also be done on the session store. By default, the `dustbin` object's functions are simply wrappers\nfor `dustbin.local`. As such, you can also access the session store by using: `dustbin.session`. Here's some examples:\n\n```javascript\nvar obj = {'foo': \"bar\"};\n\n// Store the object.\ndustbin.session.store(\"testBin\", \"testObj\", obj);\n\n// Retrieve it by key.\nobj = dustbin.session.get(\"testBin\", \"testObj\");\n\n// Alternative syntax.\nobj = dustbin.session.get(\"testBin\")[\"testObj\"];\n```\n\nAs you can see, it supports all the same operations as the local storage functions. There is absolutely no difference,\nexcept the inherent difference of session storage (all objects only last for the duration of the browser session.)\n\n## Status\n\nCurrently, all unit tests pass, and the basic functionality is there. You can get, remove and store objects by key.\nThere is also basic query support, which I estimate will work for 70% of most use cases. As near as I can tell, this\ncode is simple enough it can be used in a production site.\n\nThat being said, I would very much like to add support for [map/reduce](http://docs.basho.com/riak/latest/tutorials/querying/MapReduce/)\nand a [django-like query api](https://docs.djangoproject.com/en/dev/ref/models/querysets/#id4). I will work on that as\nI have time. If you would like to implement these features, I am more than willing to accept pull requests.\n\n## Contribution\n\nAs mentioned, I'm more than willing to accept pull requests. I will require you to follow\n[my code format](https://github.com/Morgul/dustbin/wiki/Code-Style). I also reserve the rights to reject any features\nthat rely heavily on experimental features, or lock users into one way system for using Dustbin. (There's a readon why\nthe RequireJS support is optional.)\n\n### Reporting issues\n\nI'm more than happy to have issues reported! All that I ask is a clear description of the problem, along with a test\ncase. I don't have the time or inclination to wade through your application to try and discover the causes for a bug. So,\nwhenever possible, please try and give me a small test case (Or, preferably, a pull-request with new unit tests that\nshow the failure!)\n\nThat all being said, don't wait to file a bug until you have a use case. I'd rather know there's a potential issue asap;\nyou can feel free to file an issue, and attach the test case to it later. Just make it clear you're working on it. If\nyou're having trouble isolating it, I'm more than willing to lend a hand, provided I have the time. Feel free to ask.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorgul%2Fdustbin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorgul%2Fdustbin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorgul%2Fdustbin/lists"}