@devsylar/dynamo-table

A lightweight utility library for interacting with AWS DynamoDB tables. Wraps the AWS SDK v3 to provide simple, readable methods for the most common CRUD operations on a single table.

Features

• get — Retrieve a single item by primary key
• query — Query items by key conditions (supports GSI)
• scan — Scan and filter items across the entire table (supports GSI)
• put — Create or replace an item
• update — Update specific attributes of an existing item
• Automatic handling of DynamoDB reserved word escaping via # prefix

Requirements

• Node.js >= 14
• AWS SDK v3 (@aws-sdk/client-dynamodb, @aws-sdk/util-dynamodb) — listed as peer dependencies

Installation

npm install @devsylar/dynamo-table

Install peer dependencies if not already present in your project:

npm install @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Configuration

The client reads credentials and region from environment variables:

| Variable | Description | | ----------------------- | ----------------------------- | | AWS_REGION | AWS region (e.g. us-east-1) | | AWS_ACCESS_KEY_ID | AWS access key ID | | AWS_SECRET_ACCESS_KEY | AWS secret access key |

Usage

const DynamoDBTable = require("@devsylar/dynamo-table");

const usersTable = new DynamoDBTable("Users");

get(where)

Retrieves a single item by primary key. Returns null if not found.

const user = await usersTable.get({ userId: "123" });
// { userId: '123', name: 'Alice', status: 'ACTIVE' } or null

query(where, indexName?)

Queries items using key conditions. Pass an index name to query a GSI.

// Query by partition key
const orders = await ordersTable.query({ customerId: "c-001" });

// Query a GSI — use # prefix for reserved words
const active = await usersTable.query({ "#status": "ACTIVE" }, "status-index");

scan(where, indexName?, limit?)

Scans the table and filters by the given conditions. Prefer query() for large tables.

// Simple scan with filter
const pending = await ordersTable.scan({ "#status": "PENDING" });

// Scan a GSI with a limit
const recent = await ordersTable.scan({ type: "ORDER" }, "type-index", 50);

ConsistentRead is enabled by default on scans.

put(data)

Creates or replaces an item. If an item with the same key already exists, it will be overwritten.

await usersTable.put({
  userId: "456",
  name: "Bob",
  status: "ACTIVE",
  createdAt: new Date().toISOString(),
});

update(where, data)

Updates specific attributes of an existing item. Attributes not listed in data are left unchanged.

await usersTable.update(
  { userId: "456" },
  { "#status": "INACTIVE", updatedAt: new Date().toISOString() },
);

Handling Reserved Words

DynamoDB reserves certain attribute names (status, name, type, etc.). Prefix any reserved word key with # and the library will automatically build the correct ExpressionAttributeNames mapping for you.

// 'status' is a reserved word — use '#status'
await table.query({ "#status": "ACTIVE" }, "status-index");
await table.update({ id: "1" }, { "#status": "INACTIVE", "#name": "Alice" });

Project Structure

dynamo-table/
├── src/
│   └── dynamodbtable-lib.js   # Core library implementation
├── index.js                   # Package entry point
├── package.json
└── README.md

License

MIT