aws-dynamodb-query

A simple and elegant DynamoDB client for Node.js.

npm install aws-dynamodb-query

Features

• AWS SDK v3 — Built on @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
• Fluent API — Chainable query builder that reads like English
• Async/Await — Every operation returns a Promise
• ESM native — Modern ES modules, Node 18+

Quick Start

import DynamoDB from 'aws-dynamodb-query';

// With credentials
const db = new DynamoDB({
	accessKeyId: 'XXXXXXXXXX',
	secretAccessKey: 'XXXXXXXXXX',
	region: 'us-east-1',
});

// With IAM role (Lambda, EC2, ECS)
const db = new DynamoDB();

Usage

// Get
const user = await db.table('users').where('id').eq('123').get();

// Query with index
const orders = await db.table('orders').index('index-customer_id').where('customer_id').eq('cus_123').filter('status').eq('active').limit(10).descending().query();

// Scan
const all = await db.table('users').scan();

// Insert (fails if key exists)
await db.table('users').insert({ id: '123', name: 'Alice' });

// Update
await db.table('users').where('id').eq('123').update({ name: 'Bob' });

// Upsert
await db.table('users').insert_or_update({ id: '123', login_count: db.add(1) });

// Delete
await db.table('users').where('id').eq('123').delete();

Pagination

let lastKey = null;
do {
	const result = await db.table('users').resume(lastKey).limit(100).query();

	console.log(result.items);
	lastKey = result.lastKey;
} while (lastKey);

Operators

| Method | Operator | | --------------------------- | ------------------------ | | .eq(value) | = | | .ne(value) | <> | | .lt(value) / .le(value) | < / <= | | .gt(value) / .ge(value) | > / >= | | .between(a, b) | BETWEEN | | .begins_with(value) | begins_with() | | .contains(value) | contains() | | .not_contains(value) | NOT contains() | | .in([values]) | IN (...) | | .not_null() | attribute_exists() | | .null() | attribute_not_exists() |

Type Helpers

db.add(5); // Increment number
db.del(db.SS(['a'])); // Remove from set
db.S('hello'); // String
db.SS(['a', 'b']); // String Set
db.N(42); // Number
db.NS([1, 2, 3]); // Number Set
db.L([1, 'a']); // List

Schema Pre-registration

Avoid describeTable API calls:

db.schema([
	{
		TableName: 'users',
		KeySchema: [{ AttributeName: 'id', KeyType: 'HASH' }],
	},
]);

Configuration

DynamoDB.config({
	stringset_parse_as_set: true,
	numberset_parse_as_set: true,
	empty_string_replace_as: '\0',
});

Documentation

Credits

Based on the original work of @awspilot/dynamodb.

License

MIT