README.md
1## depot.js
2
3[](http://travis-ci.org/mkuklis/depot.js)
4
5
6
7
8## Description
9
10**depot.js** is a namespaced [localStorage](http://diveintohtml5.info/storage.html) wrapper with a simple API.
11There are [other](http://brian.io/lawnchair/) [tools](https://github.com/marcuswestin/store.js/) out there but none
12of them had what I was looking for.
13
14
15## Setup
16
17depot.js should work well with CommonJS and AMD loaders.
18If loaders are not present depot.js will attach itself to the current context (window) when loaded via `<script src="depot.min.js"></script>`.
19
20depot.js is also a [bower](https://github.com/twitter/bower) [component](http://sindresorhus.com/bower-components/) so you should be able to install it by running:
21
22`bower install depot`
23
24or if you already have a bower based project you can add depot.js to your dependency list in `component.json`
25
26```js
27 "dependencies": {
28 ...
29 "depot": "0.x.x"
30 ...
31 }
32```
33
34
35## Dependencies
36
37depot.js does not depend on any other libraries however if you plan to support older browsers you will need to include [ES5-shim](https://github.com/kriskowal/es5-shim).
38
39If you plan to run it on browsers that don't support [localStorage](http://diveintohtml5.info/storage.html) you may try to include [storage polyfill](https://gist.github.com/remy/350433).
40
41## API
42
43+ save(record)
44
45+ updateAll(hash)
46
47+ update(hash)
48
49+ find(hash | function)
50
51+ all()
52
53+ destroy(id | record)
54
55+ destroyAll(none | hash | function)
56
57+ get(id)
58
59+ size()
60
61##Usage
62
63####Define new store
64
65```js
66var todoStore = depot('todos');
67```
68
69####Add new records
70
71`_id` property will be generated and attached to each new record:
72
73```js
74todoStore.save({ title: "todo1" });
75todoStore.save({ title: "todo2", completed: true });
76todoStore.save({ title: "todo3", completed: true });
77```
78
79####Update all records
80
81```js
82todoStore.updateAll({ completed: false });
83```
84
85####Return all records
86
87```js
88todoStore.all(); // [{ id: 1, title "todo1" }, {id: 2, title: todo2 }]
89```
90
91####Find records
92
93* find based on given criteria
94
95```js
96todoStore.find({ completed: true }); // [{ id: 2, title: "todo2" }, { id: 3, title: "todo3" }]
97```
98
99* find based on given function
100
101```js
102todoStore.find(function (record) {
103 return record.completed && record.title == "todo3";
104}); // [{ id: 3, title: "todo3" }]
105```
106
107
108####Return single record by id
109
110```js
111todoStore.get(1); // { id: 1, title: "todo1" }
112```
113
114####Destroy single record
115
116* by record id
117
118```js
119todoStore.destroy(1);
120```
121
122* by record object
123
124```js
125todoStore.destroy(todo);
126```
127
128####Destroy all records
129
130* destroy all
131
132```js
133todoStore.destroyAll();
134```
135
136* destroy by given criteria
137
138```js
139todoStore.destroyAll({ completed: true });
140```
141
142* destroy by given function
143
144```js
145todoStore.destroyAll(function (record) {
146 return record.completed && record.title == "todo3";
147});
148```
149
150##Options
151
152You can pass a second parameter to depot.js with additional options.
153
154```js
155var todoStore = depot("todos", options);
156```
157
158### Available options:
159
160+ idAttribute - used to override record id property (default: `_id`)
161
162```js
163var todoStore = depot("todos", { idAttribute: 'id' });
164```
165
166+ storageAdaptor - used to override storage type (default: `localStorage`)
167
168```js
169var todoStore = depot('todos', { storageAdaptor: sessionStorage });
170```
171
172
173##Contributors:
174
175* [@mkuklis](http://github.com/mkuklis)
176* [@scttnlsn](http://github.com/scttnlsn)
177* [@chrispitt](http://github.com/chrispitt)
178* [@simonsmith](http://github.com/simonsmith)
179* [@mdlawson](http://github.com/mdlawson)
180* [@jdbartlett](http://github.com/jdbartlett)
181
182##License:
183<pre>
184The MIT License
185</pre>
186
){kind=link}
){kind=link}