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

node-cosmos is a client for Azure CosmosDB 's SQL API. Which is an opinionated library aimed at ease of creating REST API for CRUD and find.

Support cosmosdb / mongodb / postgres as backend databases.


Background

* Microsoft's official nodejs CosmosDB client is verbose to use, especially when creating REST api to query/filter items.

Disclaimer

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

Quickstart

$3

``typescript
import { Cosmos } from "node-cosmos"

const db = await new CosmosBuilder()
.withConnectionString("YOUR_CONNECTION_STRING")
.withDatabaseType("cosmosdb") // or mongodb / postgres
.build()
.getDatabase("my-awesome-db");

await db.upsert("my-awesome-coll", { id:"id011", firstName: "Anony", lastName: "Nobody"}, "Users");

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

Examples

$3

`typescript
// 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");

`




$3

`typescript
//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");

`

$3

`typescript

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");

`

$3

The count() is similar to find(), but the count will ignore offset and limit.

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

const total = await db.count("Collection1", {
filter: {
lastName : "Nobody"
},
offset: 0,
limit: 100 // total is able to greater than limit
}, "Users");
`

$3

`typescript

// 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.

`




$3

`typescript

const cond = {
filter: {
id: "id010", // id equal to 'id010'
"lastName LIKE": "%Ban%", // last name CONTAINS "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
"tagIds ARRAY_CONTAINS_ANY": ["T001", "T002"], // field tagIds which is an array, contains any of ["T001", "T002"]. see cosmosdb EXISTS for details.
"tags ARRAY_CONTAINS_ALL name": ["Java", "React"], //field tags which is an array of Tag, who's name contains all of ["Java", "React"]. see cosmosdb EXISTS for details.
},
sort: ["lastName", "ASC"], //optional sort order
offset: 0, //optional offset
limit: 100 //optional limit
}

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

`

$3

`typescript
// cross partition queries are only supported for cosmosdb.

const cond = {
filter: {
"id LIKE": "ID00%", // id starts with "ID00"
},
};

// if you do not specify the partition, this will be a cross-partition query
const result = await db.find("Collection1", cond, undefined);

// or just
const result = await db.find("Collection1", cond);

`

$3

`typescript
const items = await db.findBySQL(
"Collection1",
"SELECT c.address.country, COUNT(1) AS count FROM c GROUP BY c.address.country",
"Users",
);
``

$3

node-cosmos uses unified terminology across different backends.
The table below shows how those terms correspond in each database.

| Concept | Azure Cosmos DB (SQL API) | MongoDB | PostgreSQL |
| ---------- | ------------------------- | ---------- | ---------- |
| collection | container | collection | schema |
| partition | logical partition (key) | partition | table |
| document | item | document | row/record |