Personal, hyper-specific collection of CosmosDB abstractions
npm install dry-utils-cosmosdbTrusted Root Certification Authorities > Certificates
localhost, Friendly Name: DocumentDbEmulatorCertificate
All Tasks > Export...
bash
npm install dry-utils-cosmosdb
`
Features
- Container Management: Simplified container creation and initialization
- Query Builder: Helper class for building SQL queries with best practices
- CRUD Operations: Streamlined item operations (create, read, update, delete)
- Logging: Emits events for database operations via node:diagnostics_channel, including RU consumption tracking.
Usage
$3
Connect to your database and initialize containers:
`typescript
import { dbConnect } from "dry-utils-cosmosdb";
const db = await dbConnect({
endpoint: "https://your-cosmos-instance.documents.azure.com:443/",
key: "your-cosmos-db-key",
name: "your-database-name",
containers: [
{
name: "users",
partitionKey: "userId",
indexExclusions: ["paths", "to", "exclude"],
},
{
name: "products",
partitionKey: "category",
indexExclusions: "none", // default
},
],
});
// Access the containers
const usersContainer = db.users;
const productsContainer = db.products;
`
$3
Build SQL queries with best practices for performance:
`typescript
import { Query } from "dry-utils-cosmosdb";
// Create a query to find active premium users
const query = new Query()
.whereCondition("status", "=", "active")
.whereCondition("userType", "=", "premium")
.whereCondition("createdDate", ">", "2023-01-01");
// Execute the query
const results = await container.query(query.build(100));
`
$3
Perform common database operations:
`typescript
// Get an item by ID
const user = await container.getItem("user123", "partition1");
// Create or update an item
await container.upsertItem({
id: "user123",
userId: "partition1",
name: "John Doe",
email: "john@example.com",
});
// Delete an item
await container.deleteItem("user123", "partition1");
// Query items
const activeUsers = await container.query(
"SELECT * FROM c WHERE c.status = @status",
{ parameters: [{ name: "@status", value: "active" }] }
);
`
$3
This package uses node:diagnostics_channel to publish log, error, and aggregatable events. A helper function subscribeCosmosDBLogging is provided to simplify subscribing to these events.
The subscribeCosmosDBLogging function accepts an object with optional log, error, and aggregate callbacks.
- log: A function that receives log messages: { tag: string, val: unknown }.
- error: A function that receives error messages: { tag: string, val: unknown }.
- aggregate: A function that receives performance and metric data: { tag: string, blob: Record.
Here is an example of how to subscribe to these events.
`typescript
import { subscribeCosmosDBLogging } from "dry-utils-cosmosdb";
// Subscribe to log, error, and aggregate events
subscribeCosmosDBLogging({
log: ({ tag, val }) => {
console.log([DB LOG] ${tag}:, val);
},
error: ({ tag, val }) => {
console.error([DB ERROR] ${tag}:, val);
},
aggregate: ({ tag, metrics }) => {
console.log([DB PERF] ${tag}:, metrics);
// Example: [DB PERF] UPSERT: { ru: 1.29, ms: 12.3, bytes: 123, count: 1 }
},
});
``