documentdb-typescript

Azure DocumentDB TypeScript API

This Node.js module provides the 'missing' TypeScript 2 API for Microsoft's awesome SQL-queried schema-free NoSQL database in the Azure cloud, DocumentDB.

Refer to the DocumentDB documentation here: https://docs.microsoft.com/en-us/azure/documentdb/

No TypeScript required — you can use this module with plain JavaScript too (ES3, ES5, or ES6 aka ES2015 and whatever comes after), and enjoy enhanced Intellisense in an editor that supports TypeScript 2 definition files, such as VS Code.

NOTE: The author of this module is not affiliated with Microsoft, Azure, or Document DB.

Goals

This module was written with the following goals in mind:

• Streamline common DocumentDB use cases;
• Enable a better developer experience with accurate Intellisense;
• Reduce clutter by grouping methods into classes and combining some of their functionality;
• Use idiomatic TypeScript 2 (es6 for Node JS) internally and externally;
• Enable asynchronous programming with async/await and/or Promises (native Node JS).

Change Log

v1.0.0:

• Important: This version now requires TypeScript 2.1+.
• New: Added an existsAsync method to Collection that uses a select count(1) from c where... query to determine more efficiently if any documents exist that match given ID or properties.
• New: Added path properties to Database and Collection, which can be used with the underlying Node.js API (through Client.documentClient) if needed.
• New: Most methods now accept an options parameter to forward feed and/or request options to the underlying Node.js API (e.g. for enableCrossPartitionQuery).
• Improved: Where possible, document IDs are now used to locate document resources instead of mandatory _self links. This allows for a new overload of the deleteDocumentAsync method that just takes an ID, and removes the need for a query in findDocumentAsync if an ID is passed in (either as a property or as a single parameter). Also, storeDocumentAsync with StoreMode.UpdateOnly no longer requires a _self property, an id property will do.
• Improved: More accurate types for objects passed to and/or returned from Collection methods. E.g. query results generated by queryDocuments no longer automatically include document properties such as id and _self, because queries may not actually return full documents anyway (or a document at all, e.g. for select value... queries). This is a breaking change since the TypeScript compiler may no longer find these properties on result objects, even for select * queries. The findDocumentAsync and queryDocuments methods now accept a type parameter to specify a result type explicitly.
• Changed: Getting Client.documentClient now throws an exception if the client connection has not been opened yet, or has been closed. Use isOpen() to check if the connection is currently open.
• Fixed: Operations are now queued properly in DocumentStream, e.g. calling .read() twice in succession (synchronously) actually returns promises for two different results.
• Fixed: Added strictNullChecks and noImplicitAny to the TypeScript configuration for compatibility with projects that have these options enabled.
• Fixed: Added TypeScript as a development dependency to package.json.

Note:

At this point parts of the DocumentDB feature set are still missing. If your app needs stored procedures, or users and permissions, for example, then please add to this code (preferably as new classes). Pull requests are greatly appreciated!

Tests are sorely needed as well. Perhaps some of the tests can be ported over from DocumentDB itself.

Installation

Use npm to install this module:

npm install documentdb-typescript

Then import this module into your JavaScript or TypeScript code:

const DB = require("documentdb-typescript");
const client = new DB.Client(/*...*/);

// OR: ...
import * as DB from "documentdb-typescript";
const client = new DB.Client(/*...*/);

// OR: ...
import { Client /*,...*/} from "documentdb-typescript";
const client = new Client(/*...*/);

Usage

This module exports only the following symbols:

• Client class: contains methods for dealing with the connection to DocumentDB account.
• Database class: represents a database.
• Collection class: represents a collection, and contains methods for dealing with documents.
• DocumentStream class: contains methods for reading query results (used as a return type only).
• StoreMode enum: lists different modes of storing documents in a collection.

Where is Document? — There is no 'Document' class because documents are really just plain JavaScript objects (of type any), which may or may not have some extra properties (such as _self) depending on where they come from, and are very hard to pin down as such. Also, the results of a query may or may not be full documents, which makes it impossible to predict exact return types. Adding another abstraction layer (à la the .NET API with its set- / getPropertyValue methods) doesn't seem like the right thing to do in JavaScript code.

Client

Start here if you need to work with multiple databases, or set advanced connection options.

// Example: open a connection and find all databases
async function main(url, masterKey) {
    var client = new Client(url, masterKey);

    // enable logging of all operations to the console
    client.enableConsoleLog = true;

    // dump the account information
    console.log(await client.getAccountInfoAsync());

    // open the connection and print a list of IDs
    await client.openAsync();
    var dbs = await client.listDatabasesAsync();
    console.log(dbs.map(db => db.id));

    // unnecessary unless you expect new clients
    // to reopen the connection:
    client.close();
}

The original DocumentClient from the documentdb module is kept in the documentClient property, after the openAsync method is called:

A static property Client.concurrencyLimit (number) controls how many requests may be outstanding globally at any time; this defaults to 25. Further requests are held internally (without timing out) until a pending request completes. You may want to increase this number if you are performing a high volume of low-cost operations such as deletions.

Database

Start here if you need to list all collections in a database, or delete it from the account. Nothing else here.

// Example: get a list of collections
async function main(url, masterKey) {
    var client = new Client(url, masterKey);
    var db = new Database("sample", client);

    // ... or this, which creates a new client
    // but reuses the connection:
    var db2 = new Database("sample", url, masterKey);

    // create the database if necessary
    await db.openOrCreateAsync();

    // ... or not at all (fails if not found)
    await db.openAsync();

    // print a list of collection IDs
    var colls = await db.listCollectionsAsync();
    console.log(colls.map(c => c.id));

    // delete the database
    await db.deleteAsync();
}

Collection

This is where most of the functionality lives. Finding and/or creating a collection, optionally along with the database is easy:

// Example: create and delete a collection
async function main(url, masterKey) {
    var client = new Client(url, masterKey);
    var db = new Database("sample", client);

    // these are all the same:
    var coll = new Collection("test", db);
    var coll2 = new Collection("test", "sample", client);
    var coll3 = new Collection("test", "sample", url, masterKey);
    
    // create everything if necessary
    await coll.openOrCreateDatabaseAsync();

    // ... or just the collection
    await coll.openOrCreateAsync();

    // ... or nothing (fails if not found)
    await coll.openAsync();

    // delete the collection
    await coll.deleteAsync();
}

The Collection instance has methods for setting and getting provisioned throughput levels:

// Example: set and get throughput information 
async function main(url, masterKey) {
    var client = new Client(url, masterKey);
    var coll = new Collection("test", "sample", client);
    await coll.openOrCreateDatabaseAsync();

    // set the offer throughput
    await coll.setOfferInfoAsync(500);
    
    // dump the new offer information
    console.log(await coll.getOfferInfoAsync());
}

Storing documents

This module abstracts away most of the work involved in creating, updating, and upserting documents in a collection.

// Example: store and delete a document
async function main(url, masterKey) {
    var client = new Client(url, masterKey);
    client.enableConsoleLog = true;
    var coll = new Collection("test", "sample", client);
    await coll.openOrCreateDatabaseAsync();

    // create a document (fails if ID exists),
    // returns document with meta properties
    var doc = { id: "abc", foo: "bar" };
    doc = await coll.storeDocumentAsync(doc, StoreMode.CreateOnly);

    // update a document (fails if not found)
    doc.foo = "baz";
    doc = await coll.storeDocumentAsync(doc, StoreMode.UpdateOnly);

    // update a document if not changed in DB,
    // using _etag property (which must exist)
    doc.foo = "bla";
    doc = await coll.storeDocumentAsync(doc, StoreMode.UpdateOnlyIfNoChange);
    
    // upsert a document (in parallel, without errors)
    var doc2 = { id: "abc", foo: "bar" };
    var doc3 = { id: "abc", foo: "baz" };
    await Promise.all([
        coll.storeDocumentAsync(doc, StoreMode.Upsert),
        coll.storeDocumentAsync(doc)  // same
    ]);

    // delete the document (fails if not found)
    await coll.deleteDocumentAsync(doc);

    // ... or delete by ID (fails if not found)
    await coll.deleteDocumentAsync("abc");
}

Finding documents

There are a number of ways to find a document or a set of documents in a collection.

// Example: find document(s)
async function main(url, masterKey) {
    var coll = await new Collection("test", "sample", url, masterKey)
        .openOrCreateDatabaseAsync();

    // check if a document with given ID exists
    // (uses "count(1)" aggregate in a query)
    var exists = coll.existsAsync("abc");

    // check if a document with given properties exists
    // (exact match, also uses "count(1)" aggregate)
    var customerExists = coll.existsAsync({
        isCustomer: true,
        customerID: "1234"
    })

    // retrieve a document by ID (fails if not found)
    var doc = await coll.findDocumentAsync("abc");

    // retrieve a document with given properties
    // (exact match, fails if not found, takes
    // newest if multiple documents match)
    try {
        var user = await coll.findDocumentAsync({
            isAccount: true,
            isInactive: false,
            email: "[e-mail]"
        });
        console.log(`Found ${user.email}: ${user.id}`);
    }
    catch (err) {
        console.log("User not found");
    }

    // find a set of documents (see below)
    var stream = coll.queryDocuments();  // <= all
    var stream2 = coll.queryDocuments("select * from c");  // same
    var stream3 = coll.queryDocuments({
        query: "select * from c where c.foo = @foo",
        parameters: [
            { name: "@foo", value: "bar" }
        ]
    });
}

Iterating over query results

The queryDocuments method on the Collection class is one of the few methods that does not return a Promise. Instead, it returns a DocumentStream instance which can be used to iterate over the results or load them all in one go.

// Example: iterate over query results
async function main(url, masterKey) {
    var coll = await new Collection("test", "sample", url, masterKey)
        .openOrCreateDatabaseAsync();

    // load all documents into an array
    var allDocs = await coll.queryDocuments().toArray();

    // read all results in a loop (with type hint)
    type FooResult = { foo: string };
    var stream = coll.queryDocuments<FooResult>("select c.foo from c");
    while (true) {
        var it = await stream.next();
        if (it.done === true) break;
        console.log(it.value.foo);
    }

    // ... or use the forEach method
    // (can be awaited, too)
    await stream.reset().forEach(doc => {
        console.log(doc.foo);
    });

    // ... or map all results to another array
    var ids = await stream.mapAsync(doc => doc.id);
    console.log(ids);
    
    // get only the newest time stamp
    var newest = await coll.queryDocuments(
        "select top 1 c._ts from c order by c._ts desc")
        .read();
    if (!newest)
        console.log("No documents");
    else
        console.log("Last change " +
            (Date.now() / 1000 - newest._ts) +
            "s ago");
}