View Source

h1. Design goals

h2. Error handling

Asynchronous operations, where the user provides a callback function, should always reserve the first argument for errors (Error object). The implication is that in these cases, we do not throw exceptions. However, if the user omitted a callback function, (synchronous) errors can only be caught by throwing an exception.

This is common practice in many Node.js libraries, including a lot of APIs internal to Node.js itself.

h1. Architecture proposal

h2. Primary components

h3. libcouchbase (C binding)

The lowest level API, written in C, exposes libcouchbase API virtually 1-to-1.
The only difference is type handling. Buffer lengths don't have to be given to the API, as this is part of the buffer object.
Callbacks are exposed through the EventEmitter. If this proves difficult, we'll just expose the C-logic (set_storage_callback, etc).
No special error handling logic.

h3. api (JavaScript)

The api module can wrap around the binding, providing friendly access to the binding. Its responsibilities:

* turn error codes into Error or CouchbaseError objects.
* synchronous (exceptions) and asynchronous (callback argument) error emission.
* type conversion for special data types.
* callback wrapping, based on a cookie (see: CookieJar) it creates, follows and destroys.
* registering and unregistering event listeners on the libcouchbase binding.

_uses: libcouchbase, CookieJar, errors_

h3. couchbase (JavaScript)

This is what we really want to expose to the user. This module is in charge of:

* creating instance objects (see: CouchbaseInstance).
* emitting errors that are not related to any instances.
* any global configuration that may exist.

_uses: api, CouchbaseInstance, errors_

h3. CouchbaseInstance class (JavaScript)

A friendly API that exposes a single instance and hides any complexities in the underlying APIs. Its responsibilities:

* hiding API that is unrelated to the user.
* value serialization.
* flags management.
* emitting instance related errors.
* self destruction.

_uses: couchbase, api, errors_

h2. Secondary components

h3. CookieJar (JavaScript)

A module that provides cookie generation, access and destruction.

h3. errors (JavaScript)

The errors module contains the CouchbaseError error class that can automatically transform error codes (strerror api) into error strings. Whenever possible, this class is prefered over the generic Error class.

_uses: api_