# couchbase-lite-node **Repository Path**: mirrors_couchbaselabs/couchbase-lite-node ## Basic Information - **Project Name**: couchbase-lite-node - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-10-30 - **Last Updated**: 2026-04-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Couchbase Lite Bindings for Node.js This repo contains bindings for using Couchbase Lite inside of a node.js application. This is not a supported product that is distributed, but can serve as a baseline for how to accomplish fairly widespread use of Couchbase Lite in a Javascript (non-browser) ecosystem. The primary goal of this repo is to get enough of the API into Javascript / Typescript so that a proper Visual Studio Code plugin for libcblite can be developed. Other goals are not considered here, but pull requests including other goals will be considered as long as they do not conflict with the primary goal. ## How to Build This repo is *not* self-contained, and required some setup steps in order to work properly. The first step may be fairly obvious but: - Download the Couchbase Lite C distributable for the platform you are building on. You can find instructions for how to do this in the Couchbase [official documentation](https://docs.couchbase.com/couchbase-lite/3.0/c/gs-install.html). You should download the archive rather than following any of the package manager install steps. It should be extracted into the **deps/** folder, with the topmost directory removed (in other words, the final folder stucture should have deps/include, deps/lib etc). - Retrieve the C++ headers and merge them into the include directory from above This step will eventually be made obsolete, but for now the library ships only with C headers whereas this project needs C++. You will need all the headers from the [include/cbl++](https://github.com/couchbase/couchbase-lite-C/tree/master/include/cbl%2B%2B) directory of the C repo, which will go into **deps/include/cbl++**, and all the *.hh files from [Fleece](https://github.com/couchbaselabs/fleece/tree/master/API/fleece), which will go into **deps/include/fleece**. With the above finished, the product can now be built. You will need to have `npm` installed, as it is the primary tool that is used to build this product. `npm install` will perform both downloading the prerequisite Javascript packages, as well as building the final native node module. At this point you will have a file called **build/Release/cblite-js.node** as your final product. This is merely a native shared library with a custom extension, and can be examined as such. It will be linked with libcblite as a runtime dependency. ## Architecture The details that follow are not necessary to know, and are for informational purposes detailing how this runs in the context of node. Javascript is merely a script that is interpreted and executed by a given runtime designed to interpret and execute it. There are a handful of different runtimes out there, but node.js uses the [v8](https://v8.dev/) runtime. That means that this final product will only function in either a node.js context, or perhaps (wild guess) another context that uses v8 as an underlying runtime. node.js develops a library called [Node-API](https://nodejs.org/api/n-api.html) (napi for short). The single purpose of this library is to abstract away the constantly changing details of the underlying Javascript runtime and present a unified interface in which to interact with it. This is immensely helpful, and unlikely to fade away like some other projects have since it is developed by the same team that develops node.js itself. One of the oddities of binding between Javascript and C++ is the stark difference in fundamental approach each language takes. Javascript is a very dynamic language that plays loose and fast with types, so much so that the concept of a Javascript type is almost nonexistent. This is in stark contrast to a language like C++ which is strongly and statically typed. With Javascript, objects are more like collections of key value pairs that can be changed in any way and at any time, not unlike a C++ `map` object. Furthermore, functions are not strongly defined either so any function can be called with any number of arguments and it all is valid and needs to be accounted for. The way that this is abstracted in NAPI is through the use of a context class called `CallbackInfo`. Every constructor, and every method except for limited exceptions has this object and only this object as a parameter. This object is used to query what was passed in: How many arguments, and what type. Furthermore, the return value is universally either `void` or `Value`. The latter is a class provided by NAPI to represent a top level object from which everything else inherits (similar to `object` in languages like Java or C#). There is no way to tell by looking at a definition of a binding method what arguments it takes and what it returns, so the only resort is that it be documented. So every binding method needs to adhere to the rules of the previous paragraph, and furthermore any objects passed into binding methods cannot be expected to live past the end of the current function. Everything needs to be copied in and copied out to avoid accessing invalid memory locations. So in general the binding methods of this project follow a given pattern of execution: - Assert the number of arguments is valid - Assert the type of the arguments is valid - try / catch the C++ logic, setting the current JS error on the way out if applicable - Create a return value based on the C++ return value