=nil; DBMS JavaScript Driver

The official =nil; DBMS JavaScript client for Node.js and the browser. That will support Node.JS 18+ or should work with fetch polyfill or with fetch-polyfill for browser.

NB: Current version is still in development. We should break API of this module in the nearest future.

Links

• API Documentation

Install

With npm or yarn

npm install --save @nilfoundation/dbmsjs

Basic usage example

Modern JavaScript/TypeScript with async/await:

import { Database, sql } from "@nilfoundation/dbmsjs";

const db = new Database();
const Pokemons = db.relation("my-pokemons");

async function main() {
  try {
    const pokemons = await db.query(sql`
      FOR pokemon IN ${Pokemons}
      FILTER pokemon.type == "fire"
      RETURN pokemon
    `);
    console.log("My pokemons, let me show you them:");
    for await (const pokemon of pokemons) {
      console.log(pokemon.name);
    }
  } catch (err) {
    console.error(err.message);
  }
}

main();

Using a different database:

const db = new Database({
  url: "http://localhost:8529",
  databaseName: "pancakes",
  auth: { username: "root", password: "hunter2" },
});

// The database can be swapped at any time
db.useDatabase("waffles");
db.useBasicAuth("admin", "maplesyrup");

Note: The examples throughout this documentation use async/await and other modern language features like multi-line strings and template tags. When developing for an environment without support for these language features, substitute promises for await syntax as in the above example.

Compatibility

The dbmsjs driver is compatible with the latest stable version of DBMS available at the time of the driver release and remains compatible with Node.JS 18+ or any browser.

Note: dbmsjs is only intended to be used in Node.js or a browser to access DBMS from outside the database.

Error responses

If dbmsjs encounters an API error, it will throw an DbmsError with an errorNum property indicating the DBMS error code and the code property indicating the HTTP status code from the response body.

For any other non-DBMS error responses (4xx/5xx status code), it will throw an HttpError error with the status code indicated by the code property.

If the server response did not indicate an error but the response body could not be parsed, a regular SyntaxError may be thrown instead.

In all of these cases the server response object will be exposed as the response property on the error object.

If the request failed at a network level or the connection was closed without receiving a response, the underlying system error will be thrown instead.

Common issues

Missing functions or unexpected server errors

Please make sure you are using the latest version of this driver and that the version of the dbmsjs documentation you are reading matches that version.

Changes in the major version number of dbmsjs (e.g. 6.x.y -> 7.0.0) indicate backwards-incompatible changes in the dbmsjs API that may require changes in your code when upgrading your version of dbmsjs.

Additionally please ensure that your version of Node.js (or browser) and DBMS are supported by the version of dbmsjs you are trying to use. See the compatibility section for additional information.

Error stack traces contain no useful information

Due to the async, queue-based behavior of dbmsjs, the stack traces generated when an error occur rarely provide enough information to determine the location in your own code where the request was initiated.

Using the precaptureStackTraces configuration option, dbmsjs will attempt to always generate stack traces proactively when a request is performed, allowing dbmsjs to provide more meaningful stack traces at the cost of an impact to performance even when no error occurs.

  const { Database } = require("dbmsjs");

  const db = new Database({
    url: DBMS_SERVER,
+   precaptureStackTraces: true,
  });

Note that dbmsjs will attempt to use Error.captureStackTrace if available and fall back to generating a stack trace by throwing an error. In environments that do not support the stack property on error objects, this option will still impact performance but not result in any additional information becoming available.

Node.js with self-signed HTTPS certificates

You could provide implementation of fetch with agent that have it inside.

Streaming transactions leak

When using the transaction.step method it is important to be aware of the limitations of what a callback passed to this method is allowed to do.

const relation = db.relation(collectionName);
const trx = db.transaction(transactionId);

// WARNING: This code will not work as intended!
await trx.step(async () => {
  await relation.save(doc1);
  await relation.save(doc2); // Not part of the transaction!
});

// INSTEAD: Always perform a single operation per step:
await trx.step(() => relation.save(doc1));
await trx.step(() => relation.save(doc2));

Please refer to the documentation of this method for additional examples.

License

The Apache License, Version 2.0. For more information, see the accompanying LICENSE file.