One of the challenges of writing software used by a huge range of developers is maintaining API’s which are stable and cross-compatible. Sometimes this need for compatibility can back us into a corner which restricts our ability to implement exciting new features. In light of that, I am very excited to announce the release of Alpha versions of our upcoming Node.js 3.0 SDK. This major version bump enables us to focus again on building powerful APIs which strongly leverage new features available in ECMAScript 6 and more intuitively integrate Couchbase’s extensive feature set into Node.js. We also had the opportunity to take lessons learned over the past 4 years of SDK 2.0 and build more future-proof APIs which will allow us to evolve with the language and server features throughout the life of this next generation SDK. Now that you know what our goals were, let’s talk a bit about the resulting changes!
Introduction of Promises and Async/Await
The 3.0 version of the Node.js SDK introduces built-in support for Promises throughout the APIs, this lends itself well to writing non-blocking serially written code using the new Async/Await features introduced in ECMAScript 6. All methods now support both Promises and the callback pattern native to older Javascript code. In addition to this, all event emitters have been enhanced with promises support. In the case of the various query interfaces within the SDK, this enables you to choose on a case by case basis whether to process data on the fly, or simply await on it and process the entire result set at once.
Initializing the Cluster and Buckets in SDK 3.0
Just like SDK 2.0, Cluster and Bucket objects are back in SDK 3.0 each representing their server equivalences. Connecting to a Cluster is done in a similar manner to SDK 2.0, though the parameters and pattern for authenticating have gotten some improvements:
|
1 2 3 4 5 6 7 8 |
const couchbase = require('couchbase'); var cluster = new couchbase.Cluster('couchbase://localhost', { username: 'Administrator', password: 'password', }); var bucket = cluster.bucket('default'); |
Similar to SDK 2.0, your Cluster objects are long lived resource management objects whose life generally spans from application starts-up until the application shuts-down. As of this next generation of SDKs, the rest of your objects can be short lived, or kept around without having any performance penalties. The SDK will internally cache bucket objects, collection objects, etc on your behalf.
The New KV APIs for Couchbase Server 6.5
All Key/Value operations now exist on the Collections level, which will always be a member of exactly one scope. In the case of a Server version which does not support collections, you have access to the default collection which will work exactly like our buckets did in the past. Here is an example of accessing the default Collection and then writing and reading some data with it.
|
1 2 3 4 5 |
var coll = bucket.defaultCollection(); var res = await coll.upsert('test', { x: 14 }); var res = await coll.get(‘test’); |
Scope and Collections with Developer Preview mode
As part of the upcoming Server 6.5 release, we have introduced the ability to enable a developer preview mode which exposes some upcoming features which are still in development. Turning on the Collections feature enables you to access a feature which represents the future of data access with Couchbase Server 6.5. Collections enable you to slice a Bucket into multiple logical Scopes and Collections. This replaces the requirement in early versions of Couchbase server to add a special “type” field which designated a sort of grouping of documents by name which could then be queried independently within a Bucket. I think you’ll find it’s a much more intuitive programming model and will allow you to keep your data better organized. Here is an example:
|
1 2 3 4 |
var scope = bucket.scope('app1'); var coll = scope.collection('users'); var res = await coll.upsert('test', { x: 14 }); |
The New Querying APIs
N1QL, like Analytics and FTS, are considered “global” scope in that a query can reference multiple Buckets. Initially in SDK 2.0, N1QL queries were scoped to the Bucket and later added to Cluster. In SDK 3.0 you can currently only query from the Cluster object.
|
1 |
var res = await cluster.query('SELECT * FROM default WHERE x=14'); |
Overall, all of the services (Query, FTS, and Analytics) have a public API very similar to SDK 2.0, however, for consistency all required fields have been added as a parameter on the left-hand side and the optional parameters are now consolidated into an “options” block or structure on the right hand side. You will notice that this continues across the entire SDK and greatly improves the consistency of our APIs.
|
1 2 3 4 |
var res = await cluster.query('SELECT * FROM default', { adhoc: false, readonly: true, }); |
Getting the Release
Installing the alpha release of the Node.js 3.0 SDK, you can simply use npm like you normally would, while specifying the specific version when performing the install.
|
1 |
> npm install couchbase@3.0.0-alpha.1 |
Thank Nice Brett for this post. We are looking for Promises and Async/Await support in NodeJS. Is there any plan when this feature available for production?