npm package: @fgiova/mini-dynamo-client
Description: [![NPM version](https://img.shields.io/npm/v/@fgiova/mini-dynamo-client.svg?style=flat)](https://www.npmjs.com/package/@fgiova/mini-dynamo-client) ![CI workflow](https://github.com/fgiova/mini-dynamo-client/actions/workflows/node.js.yml/badge.svg) [![Type
Author: Francesco Giovannini
Latest version: 1.1.0

# mini DynamoDB client using undici

[![NPM version](https://img.shields.io/npm/v/@fgiova/mini-dynamo-client.svg?style=flat)](https://www.npmjs.com/package/@fgiova/mini-dynamo-client)
![CI workflow](https://github.com/fgiova/mini-dynamo-client/actions/workflows/node.js.yml/badge.svg)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![Linted with Biome](https://img.shields.io/badge/Linted_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)

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

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
```bash
npm install @fgiova/mini-dynamo-client
```

## Usage

```typescript
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

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

### Single item operations

```typescript
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

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

### Batch operations

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

### Transactions

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

### Lifecycle

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

All types are defined in [schemas.ts](./src/schemas.ts) and are derived from the [AWS DynamoDB API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB.html).<br />
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](./LICENSE).