Better documentation on the Node SDK?

I’ve had a very frustrating time getting started with the NodeJS SDK. It appears that the documentation for the Node API is significantly incomplete. Here are some notes I’ve taken while trying to get some basic tasks done with the Node SDK:


If you get an error saying that “attachments are not supported in couchbase”, then check to make sure you don’t have _design/ at the front of your design doc name when building a query.

It appears that callbacks are called with exceptions when there’s a problem on the Javascript side of the operation, but they are called with an object or code when there’s an error on the C, or database side of the operation and the programmer must correlate that code with an enum in the source to understand what it means?

I just read that on the forum, but I don’t have the link handy. Here’s a related issue, though:
[…link erased because new users can only put two links in a post…]

It looks like an execution callback for a subdocument operation callback is being sent just an error code (a naked int) in the error parameter instead of an exception. This is not documented.

I would think that the documentation for the integer error code would appear here:

http://docs.couchbase.com/sdk-api/couchbase-node-client-2.1.4/MutateInBuilder.html#execute

but all that’s given the programmer is that the value passed to execute should be a callback . There’s no explanation of a deviation from the expected behavior of an exception as the first parameter to the callback, and there’s no indication that the result of the execution is a DocumentFragment .

When dealing with document fragments specifically, the Node API will pass 1 to the callback’s error position if any of the fragments in the DocumentFragment have errors in them. The programmer then has to visit each fragment in the contents section of the DocumentFragment object and access the error field for a description and code. It looks like the description is included in the error, so no need to compare with the source code there.

The contents and error fields are not documented. I’d expect them to appear here: http://docs.couchbase.com/sdk-api/couchbase-node-client-2.1.4/DocumentFragment.html but I don’t see contents in the list of methods or as fields on the class.


This has been a very frustrating experience. Is Node just a second-class citizen SDK? I’m guessing maybe the high-paying customers use the Java SDK mostly. I’m not trying to be cynical or accusatory. I’m hoping that you might either flesh out the documentation (and maybe make the API more consistent?) of the Node API, or if you don’t have time to do that, at least make a blaringly obvious note for users who are just getting started that they’ll probably have to do a lot of experimentation and discovery on their own with the current state of the Node documentation.

Or is there updated documentation somewhere that I’m missing?

Thanks! (Sorry I sound frustrated :\ )

1 Like

Sorry for the trouble you’ve encountered @splodingsocks.

The node SDK is definitely not a second class citizen. One of the projects that has been simmering and is hopefully getting underway soon is improvement in API ref and examples. In particular, the interplay between the documentation on developer.couchbase.com and these other artifacts.

By the way, you appear to be looking at old API ref. The current is at http://docs.couchbase.com/sdk-api/couchbase-node-client-2.4.3/. I’m sure that’s partially our fault from a bad link, which is related to the above. It doesn’t get any better on that page in particular, but may be better on some of the others.

What would be great is if you can let @Richard_Smedley and @brett19 and @tyler.mitchell and I know of anything you run across that’s confusing. Just a post here in the Node.js category would be great. The link you mention above is certainly in that category. We can answer questions here and file issues to fix while we work on bigger infrastructure improvements.

p.s.: are splodingsocks like exploding kittens?

:smiley: :boom: :socks:

Thanks for the reply, @ingenthr! It’s certainly encouraging to know that Node is a priority for y’all. And that link is helpful, too! How would one organically find that? I’ve found the ones I linked here by googling, and by following links from developer.couchbase.com.

The reason I was dealing with those particular oddities last night when I wrote this post is because I’ve been trying to write a couchbase wrapper in https://reasonml.github.io/, which is a strongly typed language that interfaces with, and compiles down to Javascript.

I wonder, might y’all be willing to consider actually writing future versions of the Node.js driver in Reason? It generates relatively sensible JS, and it seems like it could be a great way to improve consistency of the API, completeness of the API documentation, and soundness of the code. And as a bonus, we wouldn’t have to wrap it anymore :D.

And thanks for understanding :slight_smile:

Certainly willing to consider it, though it’s not really in our near term plans. We’re getting ready to have something of a planning summit though. We’ll keep an eye on this one!

1 Like

I would like to add my support to this thread. The node SDK documentation is sparse and unhelpful. In many cases, you get a list of functions with a one-line description and their parameters but little to no information on what the parameters need to be. For example, see every function on this page:
http://docs.couchbase.com/sdk-api/couchbase-node-client-2.4.2/ClusterManager.html

In my case, I wanted to create a new user for authentication. I think the upsertUser call is the way to go, which is listed on this page. Two of the parameters are “domain” and “settings” but there is no information on what these should be. and the example code on this page (which is part of the official documentation) is wrong (I assume that either it has not been tested, or the interface has changed).

I like working with the Node SDK, and don’t like to moan, but I have to agree with the original post that the documentation is sparse, incomplete or wrong, and gives the appearance that the node SDK is not a priority.

Thanks,
Giles


Edit: just to add to my comment above that the example code on that page is wrong, my reason for saying that was because (a) it doesn’t pass the required “domain” parameter to upsertUser and, (b) once I got passed that problem (it should be set to “local”), I couldn’t get any of the roles listed in that page to work - data_reader, data_writer, etc. This was very frustrating and I spent a couple of hours trying and failing to get these roles to work, assuming that the code was wrong. Since writing that, I have just realised that those finer detail roles are not available in the Community Edition. The page on roles here does not mention this important detail and, in fact, states that the one role that is available on the Community Edition (bucket_full_access) is “deprecated” and the other roles should be used!

This is another of my frustrations with the Couchbase documentation generally, not specifically the Node SDK documentation. I often try and fail to get something to work which turns out not to be available on the Community Edition. I am generally fine with the feature not being available - we just won’t use it - but I wish these differences were more obvious in the docs so I don’t waste my time trying to get it working.

1 Like

Thanks for the honest feedback @giles and sorry for the frustration. A group of us got together today to come up with some actions and while there’s a lot of work to do, I feel good that we made some progress.

One thing I would suggest, any time you spot something like that in the docs, hit the “feedback” in the lower right and tell us what can be better. When sorting the backlog of items to do, I know that @amarantha and @tyler.mitchell do give weight to the things that are bothering people/misleading/incorrect.

Thanks @ingenthr, I don’t like to moan about these things as I do think Couchbase is a great product and, as I’m a Community Edition user, it’s free. :slight_smile:
I will use the feedback button when I come across these things in future.

Cheers,
Giles

1 Like