node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Known Vulnerabilities

A general-purpose Communibase client for node.js projects. It is primarily a Singleton connector doing REST-calls on the Communibase API using a queuing system. It returns A+ promises for Communibase responses. Behaviour is reflected by a PHP-version that can be found at Github.


npm install --save communibase-connector-js


Make sure environment variable exists with your API-key called COMMUNIBASE_KEY

const { Connector } = require('communibase-connector-js');
const cbc = new Connector(process.env.COMMUNIBASE_KEY);'Person', { firstName: 'Tim' }).then((peopleCalledTim) => {
  // eslint-disable-next-line no-console

Advanced usage

If you need to connect to a specific version of the endpoint, you may want to set a environment variable COMMUNIBASE_API_URL e.g.


Use via a tunnel requires also adding an extra Host header

COMMUNIBASE_API_URL= node script.js


The following methods exists, all returning a promise for a result.

"selectors" may be provided MongoDb style.

"params" is a key value store for e.g. fields, limit, page and/or sort . See API docs for more details.

The param includeMetadata will set a metadata-property on the promise, when available.

cbc.getById(entityType, id, params): Promise for Entity;
cbc.getByIds(entityType, id[], params): Promise for Entity[];
cbc.getAll(entityType, params): Promise for Entity[];
cbc.getId(entityType, selector): Promise for id[];
cbc.getIds(entityType, selector, params): Promise for id[];, selector, params): Promise for Entity[];
cbc.update(entityType, document): Promise for Entity;
cbc.destroy(entityType, id): Promise for null;
cbc.undelete(entityType, id): Promise for null;


An entity is an plain JavaScript object: a key/value store of data in Communibase, also called "document".


    "firstName": "Tim",
    "addresses": [
            "street": "Breestraat"

Error handling

The update-Promise may be rejected if an entity is not considered valid. The Error has one or more of the following properties:

    "message": <a simplified error-string>
    "code": <http response code of API>
    "errors": {
            "field": "<string>",
            "message": "<string>"
        ], ...

File handling

upload a new file or update an existing one:

 * @param {Stream|Buffer|String} resource a stream, buffer or a content-string
 * @param {String} name The binary name (i.e. a filename)
 * @param {String} destinationPath The "directory location"
 * @param {String} id The `File` id to replace the contents of (optional; if not set then creates a new File)
cbc.updateBinary = function updateBinary(resource, name, destinationPath, id) {

create a readable stream:

cbc.createReadStream(fileId) : Stream;

Work with document history

First, find the _id of both the document and the version you are looking for. To find all available versions of a specific document, use

cbc.getHistory(entityType, id) : Promise for  VersionInformation[];

Alternatively, you can search the entire history of documents to look for specific properties. e.g.

//Lookup all versions of any person (even deleted documents) ever with first name Tim.
cbc.historySearch('Person', { firstName: 'Tim' }): Promise for VersionInformation[]

VersionInformation has the following structure

  • _id - The _id of the version.
  • refId - The _id of the original document. You can use this at the regular CRUD endpoint
  • updatedAt - The date this version was created
  • updatedBy - A human readable description describing who created it

With an _id and a refId, we can lookup that specific version via the API

cbc.getById(entityType, id, params, versionId) : Promise for version of document;

Aggregate document data via Mongodb pipeline. For more information, see

cbc.aggregate(entityType, aggregationPipeline);
var participantCounters = cbc.aggregate('Event', [
    { "$match": { "_id": {"$ObjectId": "52f8fb85fae15e6d0806e7c7"} } },
    { "$unwind": "$participants" },
    { "$group": { "_id": "$_id", "participantCount": { "$sum": 1 } } }

Work with "DocumentReferences"

A DocumentReference is a unified specification to point to some other (sub-)doucment within the administration. A DocumentReference looks like:

    rootDocumentId: '524aca8947bd91000600000c',
    rootDocumentEntityType: 'Person',
    path: [
            field: 'addresses',
            objectId: '53440792463cda7161000003'
        }, ...

The contents will be parsed and the requested data will be retrieved.

EXPERIMENTAL - Work with local in-memory cache for query results

The connector may cache documents locally. To enable in-memory cache for a certain instance of the connector:

cbc.enableCache(communibaseAdministrationId, socketServiceUrl)

Contact Kingsquare for these values in your particular scenario and use with caution: BEWARE of excessive memory usage!