# couch-client

**Repository Path**: mirrors_creationix/couch-client

## Basic Information

- **Project Name**: couch-client
- **Description**: A minimal CouchDB client that easy and powerful
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Couch Client

Couch Client is a simple wrapper around CouchDB's http interface.

> "CouchDB is a document-oriented, Non-Relational Database Management Server (NRDBMS)."

This wrapper/driver implements some nice things like request batching and automatic revision and key generation. Usage should be simple and straight-forward. For anything advanced, a simple http client is exposed that already connected to the couch server.

## `CouchClient(url)` - A client factory

This module exports a single factory function called `CouchClient`.  Usage is simple, it takes a single url for the connection to the database.

    var CouchClient = require('couch-client');
    var Users = CouchClient("http://username:password@yourhost:5984/users");

Since this assumes many defaults, for local testing on a stock CouchDB build, you can connect with simply `CouchCLient("/users")`.

This object will internally keep track of revisions it's seen before and batches http requests that happen in the same "tick" to go out at the same time using CouchDB's batch processing APIs.

The resulting object has the following four functions (`save`, `get`, `remove`, `request`);

The default port is 5984.

### `CouchClient.save(doc, callback)` - Save a document

Pass in a document and it will save it to the database.  If the document happens to have a `_id` property that that will be used as the key.  Also if the document has a `_rev` property, that will be passed to the server.  If they are missing, CouchClient will provide an automatic UUID using CouchDB's services and look up the latest revision.  Revisions are remembered.

    Users.save({_id: "creationix", name: "Tim Caswell", age: 28}, function ( err, doc) {
      // You know know if there was an error and have an updated version
      // of the document (with `_id` and `_rev`).
    });

### `CouchClient.get(key, callback)` - Load a document

Once you put data in the database, it's nice to be able to load it back out.  The `.get()` function takes a key as a string and returns the document in a callback.

    Users.get("creationix", function (err, doc) {
      // Now you have the document or error if there was trouble
    });

### `CouchClient.view(path, obj, callback)` - Call a view

`view` takes a path to a view, an object containing GET parameters, and a callback

    Users.view('/users/_design/design_name/_view/usernames', {key: "creationix"}, function(err, doc) {
        // Now you have the document(s) or error if there was trouble
    });

If `obj` is missing then it returns all the items in the view.

### `CouchClient.remove(key/doc, callback)` - Remove a document

Sometimes you want to remove documents from the database.  This function takes either a key as a string or a document with an `_id` property.  It will tell couch to delete it and give you back the modified document with the `_deleted` property.

    Users.remove("creationix", function (err, doc) {
      // If there was no error, it's gone
    });

### `CouchClient.request(method, path, body, callback)` - Arbitrary HTTP request.

This is the helper used internally to execute HTTP requests against the CouchDB database.  It's exposed here because CouchDB provides a very rich interface, and it can't all be easily wrapped.  The `body` parameter is optional and should be passed in as a raw JavaScript object.

    Users.request("GET", "/some_database/_design/company/_view/all", function (err, result) {
      // result is a javascript object of CouchDB's response JSON
    });

    // Manually insert a single document
    Users.request("PUT", "/foo/bar", {Foo:"Bar"}, function (err, result) {
      // result is a javascript object of CouchDB's response JSON
    });

Also if you omit the callback an `EventEmitter` object that emits `"data"`, `"end"`, and `"error"` events.  Note that the data events are not parsed.  They are raw `utf8` strings.

### `CouchClient.changes(since, callback)` - Watch for changes to the database.

CouchDB provides a neat feature known as the `_changes` feed.  This allows you do watch a database and be notified when it's changed.  The `changes()` function is a wrapper.  You give it the `since` parameter and a callback.  The callback is called once per JSON document in the response stream.


## Testing

The basicTests file currently tests a;
* local couchdb instance, with no authorization setup. 
* couchone instance with authorization at https://couch-client.couchone.com/_utils couch-client:testingonly


### Adding Tests

Add tests to the basicTests.js file. Test function names need to start with 'test'.
    
	testSomething:function() {
		// testing something
	},


## Contributing

* please include tests with your pull requests.


## Changes from 0.0.3 -> 0.0.4

* view improvements / fixes
* basic auth support


### Contributors

flashingpumpkin
dready92
devioustree
hij1nx
steelThread
candland