Design goals

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.

Architecture proposal

Primary components

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.

api (JavaScript)

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