Node-dynamodb-utils NPM

dynamoDBUtils

A lightweight, TypeScript-based utility package for simplifying DynamoDB operations using AWS SDK v3. This package provides essential DynamoDB functionalities, including caching, query building, and transactional operations, with input validation powered by Zod.

Features

CRUD Operations: Simplified functions for getItem, insertItem, updateItem, and more.
Table Management: Easily manage tables with listTables, createTable, describeTable, and deleteTable.
Caching: Built-in ephemeral caching with TTL support to optimize performance.
Advanced Querying: Query and scan operations with reusable query builders.
Input Validation: Integrated with Zod for strong input validation.
TypeScript Support: Fully typed for better developer experience and safety.

Installation

Install the package via npm:

npm install dynamoDBUtils

Usage

Setup

Before using the package, ensure you have AWS credentials configured in your environment or ~/.aws/credentials.

import { getItem, updateItem, scanTable } from "dynamoDBUtils";

Basic Examples

Get an Item

import { getItem } from "dynamoDBUtils";

const result = await getItem("UsersTable", { userId: "123" });
console.log(result);

Get an Item with Cache

import { getItemWithCache } from "dynamoDBUtils";

const result = await getItemWithCache(
  "UsersTable",
  { userId: "123" },
  ["name", "email"],
  10
); // Cache for 10 minutes
console.log(result);

Update an Item

import { updateItem } from "dynamoDBUtils";

const result = await updateItem(
  "UsersTable",
  { userId: "123" },
  { name: "John Doe" }
);
console.log(result);

Scan a Table

import { scanTable } from "dynamoDBUtils";

const result = await scanTable("UsersTable", { isActive: true });
console.log(result);

Batch Get Items

import { batchGet } from "dynamoDBUtils";

const result = await batchGet("UsersTable", [
  { userId: "123" },
  { userId: "456" },
]);
console.log(result);

Advanced Operations

Transactional Write

import { transactWrite } from "dynamoDBUtils";

const result = await transactWrite({
  TransactItems: [
    {
      Put: {
        TableName: "UsersTable",
        Item: { userId: "789", name: "Alice" },
      },
    },
    {
      Update: {
        TableName: "UsersTable",
        Key: { userId: "123" },
        UpdateExpression: "SET #name = :name",
        ExpressionAttributeNames: { "#name": "name" },
        ExpressionAttributeValues: { ":name": "John Updated" },
      },
    },
  ],
});
console.log(result);

Query Table

import { queryTable } from "dynamoDBUtils";

const result = await queryTable({
  TableName: "UsersTable",
  KeyConditionExpression: "userId = :userId",
  ExpressionAttributeValues: { ":userId": "123" },
});
console.log(result);

Table Management

List Tables

import { listTables } from "dynamoDBUtils";

const tables = await listTables();
console.log(tables);

Create a Table

import { createTable } from "dynamoDBUtils";

const result = await createTable({
  TableName: "NewTable",
  KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
  AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
  ProvisionedThroughput: {
    ReadCapacityUnits: 5,
    WriteCapacityUnits: 5,
  },
});
console.log(result);

Query Builder

Create reusable query objects dynamically with the QueryBuilder utility.

import { QueryBuilder } from "dynamoDBUtils";

const query = new QueryBuilder("UsersTable")
  .addKeyCondition("userId", "=", "123")
  .addFilter("isActive", "=", true)
  .addProjection("name", "email")
  .setLimit(10)
  .build();

console.log(query);