Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 377 lines (284 sloc) 9.709 kB
6da94e4 basic README & LICENSE
cloudhead authored
1 cradle
2 ======
3
9a4db61 fixed README a little, and added full API method list
cloudhead authored
4 A high-level, caching, CouchDB client for Node.js
f3847bd README init
cloudhead authored
5
6 introduction
7 ------------
8
9 Cradle is an asynchronous javascript client for [CouchDB](http://couchdb.apache.org).
10 It is somewhat higher-level than most other CouchDB clients, requiring a little less knowledge of CouchDB's REST API.
6c504bf clarification to the README
cloudhead authored
11 Cradle also has built-in write-through caching, giving you an extra level of speed, and making document _updates_ and _deletion_ easier.
22d14b2 ws
cloudhead authored
12 Cradle was built from the love of CouchDB and Node.js, and tries to make the most out of this wonderful marriage of technologies.
f3847bd README init
cloudhead authored
13
14 philosophy
15 ----------
16
17 The key concept here is the common ground shared by CouchDB and Node.js, that is, _javascript_. The other important aspect of this marriage is the asynchronous behaviors of both these technologies. Cradle tries to make use of these symmetries, whenever it can.
542be0b (doc) update documentation to reflect API changes
cloudhead authored
18 Cradle's API, although closely knit with CouchDB's, isn't overly so. Whenever the API can be abstracted in a friendlier, simpler way, that's the route it takes. So even though a large part of the `Cradle <--> CouchDB` mappings are one to one, some Cradle functions, such as `save()`, can perform more than one operation, depending on how they are used.
f3847bd README init
cloudhead authored
19
20 synopsis
21 --------
22
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
23 ``` js
24 var cradle = require('cradle');
25 var db = new(cradle.Connection)().database('starwars');
26
27 db.get('vader', function (err, doc) {
28 doc.name; // 'Darth Vader'
29 assert.equal(doc.force, 'dark');
30 });
31
32 db.save('skywalker', {
33 force: 'light',
34 name: 'Luke Skywalker'
35 }, function (err, res) {
36 if (err) {
37 // Handle error
38 } else {
39 // Handle success
40 }
41 });
42 ```
22d14b2 ws
cloudhead authored
43
0aefe28 (dist) npm
cloudhead authored
44 installation
45 ------------
46
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
47 ``` bash
48 $ npm install cradle
49 ```
0aefe28 (dist) npm
cloudhead authored
50
f3847bd README init
cloudhead authored
51 API
52 ---
53
4a8478d ws
cloudhead authored
54 Cradle's API builds right on top of Node's asynch API. Every asynch method takes a callback as its last argument. The return value is an `event.EventEmitter`, so listeners can also be optionally added.
f3847bd README init
cloudhead authored
55
56 ### Opening a connection ###
57
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
58 ``` js
59 new(cradle.Connection)('http://living-room.couch', 5984, {
60 cache: true,
61 raw: false
62 });
63 ```
f3847bd README init
cloudhead authored
64
9a4db61 fixed README a little, and added full API method list
cloudhead authored
65 _Defaults to `127.0.0.1:5984`_
f3847bd README init
cloudhead authored
66
9a4db61 fixed README a little, and added full API method list
cloudhead authored
67 Note that you can also use `cradle.setup` to set a global configuration:
f3847bd README init
cloudhead authored
68
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
69 ``` js
70 cradle.setup({
71 host: 'living-room.couch',
72 cache: true,
73 raw: false
74 });
75
76 var c = new(cradle.Connection),
77 cc = new(cradle.Connection)('173.45.66.92');
78 ```
f3847bd README init
cloudhead authored
79
80 ### creating a database ###
81
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
82 ``` js
83 var db = c.database('starwars');
84 db.create();
85 ```
f3847bd README init
cloudhead authored
86
927fc7c @pdeschen add sub section about database existence in README
pdeschen authored
87 #### checking for database existence ####
88
89 You can check if a database exists with the `exists()` method.
90
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
91 ``` js
92 db.exists(function (err, exists) {
93 if (err) {
94 console.log('error', err);
95 } else if (exists) {
96 console.log('the force is with you.');
97 } else {
98 console.log('database does not exists.');
99 db.create();
100 /* populate design documents */
101 }
102 });
103 ```
f3847bd README init
cloudhead authored
104
765dadd @dominictarr mention destroy method in README
dominictarr authored
105 ### destroy a database ###
106
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
107 ``` js
108 db.destroy(cb);
109 ```
765dadd @dominictarr mention destroy method in README
dominictarr authored
110
9a4db61 fixed README a little, and added full API method list
cloudhead authored
111 ### fetching a document _(GET)_ ###
f3847bd README init
cloudhead authored
112
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
113 ``` js
114 db.get('vader', function (err, doc) {
23291a8 @indexzero [minor] Remove old references to `sys`
indexzero authored
115 console.log(doc);
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
116 });
117 ```
f3847bd README init
cloudhead authored
118
ee3c03d (doc) update bulk GET and fixes
cloudhead authored
119 > If you want to get a specific revision for that document, you can pass it as the 2nd parameter to `get()`.
120
121 Cradle is also able to fetch multiple documents if you have a list of ids, just pass an array to `get`:
122
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
123 ``` js
124 db.get(['luke', 'vader'], function (err, doc) { ... });
125 ```
f3847bd README init
cloudhead authored
126
127 ### Querying a view ###
128
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
129 ``` js
130 db.view('characters/all', function (err, res) {
131 res.forEach(function (row) {
23291a8 @indexzero [minor] Remove old references to `sys`
indexzero authored
132 console.log("%s is on the %s side of the force.", row.name, row.force);
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
133 });
134 });
135 ```
f3847bd README init
cloudhead authored
136
2fcb86a @indexzero [doc] Added docs for querying a view by key. Fixes #12
indexzero authored
137 #### Querying a row with a specific key ####
138 Lets suppose that you have a design document that you've created:
139
140 ``` js
141 db.save('_design/user', {
142 views: {
143 byUsername: {
144 map: 'function (doc) { if (doc.resource === 'User') { emit(doc.username, doc) } }'
145 }
146 }
147 });
148 ```
149
150 In CouchDB you could query this view directly by making an HTTP request to:
151
152 ```
153 /_design/User/_view/byUsername/?key="luke"
154 ```
155
156 In `cradle` you can make this same query by using the `.view()` database function:
157
158 ``` js
159 db.view('user/byUsername', { key: 'luke' }, function (err, doc) {
160 console.dir(doc);
161 });
162 ```
163
f3847bd README init
cloudhead authored
164 ### creating/updating documents ###
165
542be0b (doc) update documentation to reflect API changes
cloudhead authored
166 In general, document creation is done with the `save()` method, while updating is done with `merge()`.
f3847bd README init
cloudhead authored
167
e1c2385 updated README for new API
cloudhead authored
168 #### creating with an id _(PUT)_ ####
f3847bd README init
cloudhead authored
169
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
170 ``` js
171 db.save('vader', {
172 name: 'darth', force: 'dark'
173 }, function (err, res) {
174 // Handle response
175 });
176 ```
f3847bd README init
cloudhead authored
177
e1c2385 updated README for new API
cloudhead authored
178 #### creating without an id _(POST)_ ####
f3847bd README init
cloudhead authored
179
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
180 ``` js
181 db.save({
182 force: 'dark', name: 'Darth'
183 }, function (err, res) {
184 // Handle response
185 });
186 ```
f3847bd README init
cloudhead authored
187
188 #### updating an existing document with the revision ####
189
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
190 ``` js
191 db.save('luke', '1-94B6F82', {
192 force: 'dark', name: 'Luke'
193 }, function (err, res) {
194 // Handle response
195 });
196 ```
f3847bd README init
cloudhead authored
197
542be0b (doc) update documentation to reflect API changes
cloudhead authored
198 Note that when saving a document this way, CouchDB overwrites the existing document with the new one. If you want to update only certain fields of the document, you have to fetch it first (with `get`), make your changes, then resave the modified document with the above method.
f3847bd README init
cloudhead authored
199
d0ffc9d @DTrejo README.md: code formatting fix
DTrejo authored
200 If you only want to update one or more attributes, and leave the others untouched, you can use the `merge()` method:
f3847bd README init
cloudhead authored
201
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
202 ``` js
203 db.merge('luke', {jedi: true}, function (err, res) {
204 // Luke is now a jedi,
205 // but remains on the dark side of the force.
206 });
207 ```
f3847bd README init
cloudhead authored
208
542be0b (doc) update documentation to reflect API changes
cloudhead authored
209 Note that we didn't pass a `_rev`, this only works because we previously saved a full version of 'luke', and the `cache` option is enabled.
f3847bd README init
cloudhead authored
210
211 #### bulk insertion ####
212
542be0b (doc) update documentation to reflect API changes
cloudhead authored
213 If you want to insert more than one document at a time, for performance reasons, you can pass an array to `save()`:
f3847bd README init
cloudhead authored
214
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
215 ``` js
216 db.save([
217 { name: 'Yoda' },
218 { name: 'Han Solo' },
219 { name: 'Leia' }
220 ], function (err, res) {
221 // Handle response
222 });
223 ```
f3847bd README init
cloudhead authored
224
225 #### creating views ####
226
227 Here we create a design document named 'characters', with two views: 'all' and 'darkside'.
228
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
229 ``` js
230 db.save('_design/characters', {
231 all: {
232 map: function (doc) {
233 if (doc.name) emit(doc.name, doc);
234 }
235 },
236 darkside: {
237 map: function (doc) {
238 if (doc.name && doc.force == 'dark') {
239 emit(null, doc);
240 }
241 }
242 }
243 });
244 ```
f3847bd README init
cloudhead authored
245
246 These views can later be queried with `db.view('characters/all')`, for example.
247
d0ffc9d @DTrejo README.md: code formatting fix
DTrejo authored
248 Here we create a temporary view. WARNING: do not use this in production as it is
249 extremely slow (use it to test views).
250
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
251 ``` js
252 db.temporaryView({
b8eaefa @indexzero [fix minor] Emit errors in `.changes()`. Anonymous functions should b…
indexzero authored
253 map: function (doc) {
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
254 if (doc.color) emit(doc._id, doc);
255 }
256 }, function (err, res) {
257 if (err) console.log(err);
258 console.log(res);
259 });
260 ```
b864fa0 @DTrejo add support for temporary views
DTrejo authored
261
1d6ac47 @dominictarr doc for creating validation functions.
dominictarr authored
262 ### creating validation ###
263
264 when saving a design document, cradle guesses you want to create a view, mention views explicitly to work around this.
265
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
266 ``` js
267 db.save('_design/laws', {
268 views: {},
269 validate_doc_update:
b8eaefa @indexzero [fix minor] Emit errors in `.changes()`. Anonymous functions should b…
indexzero authored
270 function (newDoc, oldDoc, usrCtx) {
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
271 if(! /^(light|dark|neutral)$/(newDoc.force))
b8eaefa @indexzero [fix minor] Emit errors in `.changes()`. Anonymous functions should b…
indexzero authored
272 throw { error: "invalid value", reason:"force must be dark, light, or neutral" }
1d6ac47 @dominictarr doc for creating validation functions.
dominictarr authored
273 }
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
274 }
275 });
276 ```
1d6ac47 @dominictarr doc for creating validation functions.
dominictarr authored
277
9a4db61 fixed README a little, and added full API method list
cloudhead authored
278 ### removing documents _(DELETE)_ ###
f3847bd README init
cloudhead authored
279
280 To remove a document, you call the `remove()` method, passing the latest document revision.
281
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
282 ``` js
283 db.remove('luke', '1-94B6F82', function (err, res) {
284 // Handle response
285 });
286 ```
f3847bd README init
cloudhead authored
287
288
289 If `remove` is called without a revision, and the document was recently fetched from the database, it will attempt to use the cached document's revision, providing caching is enabled.
290
a7baf2b @cloudhead (doc) auth & SSL
cloudhead authored
291 Connecting with authentication and SSL
292 --------------------------------------
293
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
294 ``` js
295 var connection = new(cradle.Connection)('https://couch.io', 443, {
296 auth: { username: 'john', password: 'fha82l' }
297 });
298 ```
a7baf2b @cloudhead (doc) auth & SSL
cloudhead authored
299
300 or
301
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
302 ``` js
303 var connection = new(cradle.Connection)('couch.io', 443, {
304 secure: true,
305 auth: { username: 'john', password: 'fha82l' }
306 });
307 ```
a7baf2b @cloudhead (doc) auth & SSL
cloudhead authored
308
01ac23d (new) _changes API
cloudhead authored
309 Changes API
310 -----------
311
312 For a one-time `_changes` query, simply call `db.changes` with a callback:
313
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
314 ``` js
315 db.changes(function (list) {
316 list.forEach(function (change) { console.log(change) });
317 });
318 ```
01ac23d (new) _changes API
cloudhead authored
319
320 Or if you want to see changes since a specific sequence number:
321
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
322 ``` js
323 db.changes({ since: 42 }, function (list) {
324 ...
325 });
326 ```
01ac23d (new) _changes API
cloudhead authored
327
328 The callback will receive the list of changes as an *Array*. If you want to include
329 the affected documents, simply pass `include_docs: true` in the options.
330
331 ### Streaming #
332
1f11f28 @indexzero [doc] Update README.md with references to `follow`
indexzero authored
333 You can also *stream* changes, by calling `db.changes` without the callback. This API uses the **excellent** [follow][0] library from [IrisCouch][1]:
01ac23d (new) _changes API
cloudhead authored
334
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
335 ``` js
1f11f28 @indexzero [doc] Update README.md with references to `follow`
indexzero authored
336 var feed = db.changes({ since: 42 });
337
338 feed.on('change', function (change) {
339 console.log(change);
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
340 });
341 ```
01ac23d (new) _changes API
cloudhead authored
342
1f11f28 @indexzero [doc] Update README.md with references to `follow`
indexzero authored
343 In this case, it returns an instance of `follow.Feed`, which behaves very similarly to node's `EventEmitter` API. For full documentation on the options available to you when monitoring CouchDB with `.changes()` see the [follow documentation][0].
01ac23d (new) _changes API
cloudhead authored
344
345
9a4db61 fixed README a little, and added full API method list
cloudhead authored
346 Other API methods
347 -----------------
f3847bd README init
cloudhead authored
348
9a4db61 fixed README a little, and added full API method list
cloudhead authored
349 ### CouchDB Server level ###
f3847bd README init
cloudhead authored
350
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
351 ``` js
352 new(cradle.Connection)().*
353 ```
9a4db61 fixed README a little, and added full API method list
cloudhead authored
354
355 - `databases()`: Get list of databases
356 - `config()`: Get server config
357 - `info()`: Get server information
358 - `stats()`: Statistics overview
359 - `activeTasks()`: Get list of currently active tasks
360 - `uuids(count)`: Get _count_ list of UUIDs
4c3f308 @cloudhead use 'secure' and 'username'/'password' options
cloudhead authored
361 - `replicate(options)`: Replicate a database.
9a4db61 fixed README a little, and added full API method list
cloudhead authored
362
363 ### database level ###
364
f360e05 @indexzero [doc] Update code samples to use Github flavored Markdown in README.md
indexzero authored
365 ``` js
366 new(cradle.Connection)().database('starwars').*
367 ```
9a4db61 fixed README a little, and added full API method list
cloudhead authored
368
369 - `info()`: Database information
370 - `all()`: Get all documents
371 - `compact()`: Compact database
372 - `viewCleanup()`: Cleanup old view data
4c3f308 @cloudhead use 'secure' and 'username'/'password' options
cloudhead authored
373 - `replicate(target, options)`: Replicate this database to `target`.
f3847bd README init
cloudhead authored
374
1f11f28 @indexzero [doc] Update README.md with references to `follow`
indexzero authored
375 [0]: https://github.com/iriscouch/follow
376 [1]: http://iriscouch.com
Something went wrong with that request. Please try again.