node-cosmos - A light weight Azure CosmosDB Client for nodejs

node-cosmos is a client for Azure CosmosDB 's SQL API (also called documentdb formerly). Which is an opinionated library aimed at ease of use for CRUD and find (aka. query).

Background

• Microsoft's official nodejs CosmosDB client is verbose to use

Disclaimer

• This is an alpha version, and features are focused to CRUD and find at present.

Quickstart

Start programming

import { Cosmos } from "node-cosmos"

const db = await new Cosmos("YOUR_CONNECTION_STRING").getDatabase("my-awesome-db");

await db.upsert("my-awesome-coll", { id:"id011", firstName: "Anony", lastName: "Nobody"} );
  
const users = await db.find("Collection1", {
    filter: {
        id : "id010", // id equals "id010"
        "lastName%" : "Nobo" // lastName starts with Nobo
    },
    sort: ["firstName", "ASC"],
    offset: 0,
    limit: 100
});

Examples

Work with partitions

// Save user into Coll:Collection1, partition:Users.
// If you do not specify the partition. It will default to coll name.

const db = await new Cosmos("YOUR_CONNECTION_STRING").getDatabase("Database1");

await db.upsert("Collection1", {id: "id011", firstName: "Tom", lastName: "Banks"}, "Users");

// The default partition key is "_partition", so we'll get a json like this:
// {
//    "id": "id011",
//    "firstName": "Tom",
//    "lastName": "Banks",
//    "_partition": "Users"
// }

const users = await db.find("Collection1", {
    filter: {
        id : ["id010", "id011"] // id equals "id010" or "id011"
        lastName : "Nobody" 
    },
    sort: ["firstName", "ASC"],
    offset: 0,
    limit: 100
}, "Users");

Create database and collection from zero

//get db(create if not exist)
const db = await new Cosmos(process.env.COSMOSDB_CONNECTION_STRING).getDatabase("Database1");

//create a collection(if not exist)
await db.createCollection("Collection1");

CRUD

const db = await new Cosmos(process.env.COSMOSDB_CONNECTION_STRING).getDatabase("Database1");

// Read
const user1 = await db.read("Collection1", "id001", "Users");

// Update
user1.lastName = "Updated";
await db.update("Collection1", user1, "Users");

// Upsert
await db.upsert("Collection1", user1, "Users");

// Delete
await db.delete("Collection1", user1.id, "Users");

Partial Update

// update the lastName field only
await db.update("Collection", {id: "id001", lastName:"LastNameUpdated"}, , "Users");

// if you want to override the item without partial update feature, you can use `upsert` instead, which does not perform partial updating.

Complex queries

const cond = {
  filter: {
    id: "id010", // id equal to 'id010'
    "lastName%": "Ban", // last name STARTSWITH "Ban"
    "firstName !=": "Andy", // not equal
    location:  ["New York", "Paris"], // location is 'New York' or 'Paris'. see cosmosdb IN 
    "age >=": 20, // see cosmosdb compare operators
    "desciption CONTAINS": "Project manager",// see cosmosdb CONTAINS
    "skill ARRAY_CONTAINS": "Java", // see cosmosdb ARRAY_CONTAINS
  },
  sort: ["lastName", "ASC"], //optional sort order
  offset: 0, //optional offset
  limit: 100 //optional limit
}

const users = await db.find("Collection1", cond, "Users");