Framework

- About
- Guides
- Community
- API
- Code
- Download

# Kanso API Documentation

Index | View on single page

## db

Contains functions for querying and storing data in CouchDB.

### encode(str)

Encodes a document id or view, list or show name.

#### Parameters

str | String |

Returns: String

### request(options, callback)

Make a request, with some default settings and proper callback handling. Used behind-the-scenes by most other DB module functions.

#### Parameters

options | Object |
callback | Function |

### getRewrite(path, [q], callback)

Fetches a rewrite from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

path | String |
q | Object | (optional)
callback | Function |

### getDoc(id, [q, options], callback)

Fetches a document from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

id | String |
q | Object | (optional)
options | Object | (optional)
callback | Function |

### saveDoc(doc, [options], callback)

Saves a document to the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

doc | Object |
options | Object | (optional)
callback | Function |

### removeDoc(doc, [options], callback)

Deletes a document from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

doc | Object |
callback | Function |

### getView(view, [q], callback)

Fetches a view from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

view | String |
q | Object | (optional)
callback | Function |

### getList(list, view, [q], callback)

Transforms and fetches a view through a list from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

list | String |
view | String |
q | Object | (optional)
callback | Function |

### getShow(show, docid, [q], callback)

Transforms and fetches a document through a show from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

#### Parameters

show | String |
docid | String |
q | Object | (optional)
callback | Function |

### all([q], callback)

Get all documents (including design docs).

#### Parameters

q | Object | (optional)
callback | Function |

### stringifyQuery(query)

Properly encodes query parameters to CouchDB views etc. Handle complex keys and other non-string parameters by passing through JSON.stringify. Returns a shallow-copied clone of the original query after complex values have been stringified.

#### Parameters

query | Object |

Returns: Object

### newUUID(cacheNum, callback)

Returns a new UUID generated by CouchDB. Its possible to cache multiple UUIDs for later use, to avoid making too many requests.

#### Parameters

cacheNum | Number | (optional, default: 1)
callback | Function |

### createDatabase(name, callback)

Creates a CouchDB database.

If you're running behind a virtual host you'll need to set up appropriate rewrites for a PUT request to '/' and turn off safe rewrites.

#### Parameters

name | String |
callback | Function |

### deleteDatabase(name, callback)

Deletes a CouchDB database.

If you're running behind a virtual host you'll need to set up appropriate rewrites for a DELETE request to '/' and turn off safe rewrites.

#### Parameters

name | String |
callback | Function |

### getReplication(id, callback)

Fetches the most recent revision of the replication document referred to by the id parameter.

If you're running behind a virtual host you'll need to set up appropriate rewrites to /_replicator, which will also mean turning off safe rewrites.

This function only works with CouchDB >= 1.1, since it uses the _replicator database.

#### Parameters

id | String |
callback | Function |

### startReplication(options, callback)

Replicates options.source to options.target. The strings options.source and options.target are each either a CouchDB database name or a CouchDB database URI.

If you're running behind a virtual host you'll need to set up appropriate rewrites to /_replicator, which will also mean turning off safe rewrites.

This function only works with CouchDB >= 1.1, since it uses the _replicator database.

#### Parameters

options | Object |
callback | Function |

### waitReplication(doc, [options, state_function], callback)

Waits for a replication operation to enter a specific state. waitReplication polls the _replication database using the doc provided, and evaluates state_function(doc) at each iteration. This function stops polling and invokes callback when the state_function evaluates to true. If state_function is not provided, waitReplication waits for the doc's _replication_state to change from 'triggered' to 'completed' (or 'error').

If you're running behind a virtual host you'll need to set up appropriate rewrites to /_replicator, which will also mean turning off safe rewrites.

This function only works with CouchDB >= 1.1, since it uses the _replicator database.

#### Parameters

doc | Object |
state_function | Function | (optional)
callback | Function |

### stopReplication(doc, callback, [options])

Stops a replication operation already in progress. The doc parameter can be obtained by calling getReplication.

If you're running behind a virtual host you'll need to set up appropriate rewrites to /_replicator, which will also mean turning off safe rewrites.

This function only works with CouchDB >= 1.1, since it uses the _replicator database.

#### Parameters

id | String |
callback | Function |
options | Function |

### deleteUser(username, callback)

Deletes an existing user document, given its username. You must be logged in as an administrative user for this function to succeed.

#### Parameters

username | String |
callback | Function |

### getDesignDoc(name, callback, no_cache)

Fetch a design document from CouchDB. By default, the results of this function are cached within the javascript engine. To avoid this, pass true for the no_cache argument.

#### Parameters

name |  | The name of (i.e. path to) the design document.
callback |  | The callback to invoke when the request completes.
no_cache |  | optional; true to force a cache miss for this request.