mini DynamoDB client using undici

Description

This module allows a minimal set of DynamoDB operations using the aws-json protocol with "undici" as http agent. The @fgiova/aws-signature module is used for signing requests to optimize performance.

Supported operations:

• Single item: putItem, getItem, deleteItem, updateItem
• Query and Scan with filters, pagination, and GSI support
• Batch operations: batchWriteItem, batchGetItem
• Transactions: transactWriteItems, transactGetItems

Requirements

Node.js ^22.14.0 || >= 24.10.0

Installation

npm install @fgiova/mini-dynamo-client

Usage

import { MiniDynamoClient } from "@fgiova/mini-dynamo-client";

const client = new MiniDynamoClient("eu-central-1");

// Put an item
await client.putItem({
    TableName: "my-table",
    Item: {
        pk: { S: "user#1" },
        sk: { S: "profile" },
        name: { S: "Francesco" },
        age: { N: "30" },
    },
});

// Get an item
const { Item } = await client.getItem({
    TableName: "my-table",
    Key: {
        pk: { S: "user#1" },
        sk: { S: "profile" },
    },
});

// Update an item
await client.updateItem({
    TableName: "my-table",
    Key: {
        pk: { S: "user#1" },
        sk: { S: "profile" },
    },
    UpdateExpression: "SET #n = :name",
    ExpressionAttributeNames: { "#n": "name" },
    ExpressionAttributeValues: { ":name": { S: "Updated" } },
    ReturnValues: "ALL_NEW",
});

// Query items
const result = await client.query({
    TableName: "my-table",
    KeyConditionExpression: "pk = :pk",
    ExpressionAttributeValues: {
        ":pk": { S: "user#1" },
    },
});

// Delete an item
await client.deleteItem({
    TableName: "my-table",
    Key: {
        pk: { S: "user#1" },
        sk: { S: "profile" },
    },
});

// Batch write (automatically chunked if > 25 items)
await client.batchWriteItem({
    RequestItems: {
        "my-table": [
            { PutRequest: { Item: { pk: { S: "item#1" }, sk: { S: "data" } } } },
            { DeleteRequest: { Key: { pk: { S: "item#2" }, sk: { S: "data" } } } },
        ],
    },
});

// Batch get (automatically chunked if > 100 keys)
const batchResult = await client.batchGetItem({
    RequestItems: {
        "my-table": {
            Keys: [
                { pk: { S: "item#1" }, sk: { S: "data" } },
                { pk: { S: "item#2" }, sk: { S: "data" } },
            ],
        },
    },
});

// Transactions
await client.transactWriteItems({
    TransactItems: [
        {
            Put: {
                TableName: "my-table",
                Item: { pk: { S: "tx#1" }, sk: { S: "data" }, name: { S: "A" } },
            },
        },
        {
            Delete: {
                TableName: "my-table",
                Key: { pk: { S: "tx#2" }, sk: { S: "data" } },
            },
        },
    ],
});

API

MiniDynamoClient(region: string, endpoint?: string, undiciOptions?: Pool.Options, signer?: Signer | SignerOptions)

Single item operations

MiniDynamoClient.putItem(input: PutItemInput): Promise<PutItemOutput>
MiniDynamoClient.getItem(input: GetItemInput): Promise<GetItemOutput>
MiniDynamoClient.deleteItem(input: DeleteItemInput): Promise<DeleteItemOutput>
MiniDynamoClient.updateItem(input: UpdateItemInput): Promise<UpdateItemOutput>

Query and Scan

MiniDynamoClient.query(input: QueryInput): Promise<QueryOutput>
MiniDynamoClient.scan(input: ScanInput): Promise<ScanOutput>

Batch operations

MiniDynamoClient.batchWriteItem(input: BatchWriteItemInput): Promise<BatchWriteItemOutput>
MiniDynamoClient.batchGetItem(input: BatchGetItemInput): Promise<BatchGetItemOutput>

Transactions

MiniDynamoClient.transactWriteItems(input: TransactWriteItemsInput): Promise<TransactWriteItemsOutput>
MiniDynamoClient.transactGetItems(input: TransactGetItemsInput): Promise<TransactGetItemsOutput>

Lifecycle

MiniDynamoClient.destroy(signer?: boolean): Promise<any[]>

All types are defined in schemas.ts and are derived from the AWS DynamoDB API. The main difference is that batch operations are not limited to the AWS defaults (25 for BatchWriteItem, 100 for BatchGetItem), but accept any number of items and automatically split them into the batches needed to exhaust the total.

License

Licensed under MIT.