# @jayalfredprufrock/dynamo-box

> > [!WARNING] > **This project has been superseded by [dinah](https://github.com/jayalfredprufrock/dinah), a new and improved library.** > There will be no further development in this repo. Please migrate to [dinah](https://github.com/jayalfredprufrock/din

Latest version **0.13.0** (published 2026-07-01) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @jayalfredprufrock/dynamo-box
pnpm add @jayalfredprufrock/dynamo-box
yarn add @jayalfredprufrock/dynamo-box
bun add @jayalfredprufrock/dynamo-box
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.13.0 |
| Published | 2026-07-01 |
| First published | 2023-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 275.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 7 |
| Author | Andrew Smiley |
| Maintainers | jayalfredprufrock |
| Keywords | typebox, dynamodb, json-schema, dynamo, data-mapper, validation, repository |

## Links

- npm: https://www.npmjs.com/package/@jayalfredprufrock/dynamo-box
- Repository: https://github.com/jayalfredprufrock/dynamo-box
- Homepage: https://github.com/jayalfredprufrock/dynamo-box#readme
- Issues: https://github.com/jayalfredprufrock/dynamo-box/issues
- npm.io page: https://npm.io/package/@jayalfredprufrock/dynamo-box

## Dependencies (2)

- [sift](https://npm.io/package/sift.md) ^17.1.3
- [typed-emitter](https://npm.io/package/typed-emitter.md) ^2.1.0

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 0.13.0 (latest) — 2026-07-01
- 0.12.2 — 2025-03-27
- 0.12.1 — 2025-03-27
- 0.12.0 — 2025-03-27
- 0.11.5 — 2025-03-17
- 0.11.4 — 2024-12-05
- 0.11.3 — 2024-12-05
- 0.11.2 — 2024-12-03
- 0.11.1 — 2024-12-03
- 0.11.0 — 2024-11-26
- 0.10.0 — 2024-11-20
- 0.9.5 — 2024-11-18
- 0.9.4 — 2024-11-13
- 0.9.3 — 2024-11-07
- 0.9.2 — 2024-09-30
- … 25 more at https://npm.io/package/@jayalfredprufrock/dynamo-box/versions

## README

# dynamo-box

> [!WARNING] > **This project has been superseded by [dinah](https://github.com/jayalfredprufrock/dinah), a new and improved library.**
> There will be no further development in this repo. Please migrate to [dinah](https://github.com/jayalfredprufrock/dinah).

Dynamo-box leverages [TypeBox](https://github.com/sinclairzx81/typebox) to provide a strongly typed repository client for interacting with DynamoDb tables. **Remain safe in the box.**

This library also currently leverages [Dynamon](https://gitlab.com/monster-space-network/typemon/dynamon) for marshalling and building expressions, so be sure to visit their docs for additional usage information, especially in regards to conditional/update expressions.

```sh
npm i @jayalfredprufrock/dynamo-box typebox @typemon/dynamon
```

## Basic Usage

Consider the following schema that represents a user:

```typescript
import { Static, Type } from 'typebox';

export const UserSchema = Type.Object({
    id: Type.String(),
    name: Type.String(),
    email: Type.String(),
    createdAt: Type.Integer(),
    updatedAt: Type.Integer(),
});
```

Use `makeDdbRepository()` to create a fully-typed repository class:

```typescript
import { makeDdbRepository } from '@jayalfredprufrock/dynamo-box';

export class UserRepository = makeDdbRepository(UserSchema)({
    client: { region: 'us-east-1', endpoint: 'localhost' },
    tableName: 'users',
    partitionKey: 'id',
    transformInput: (input: UserInput) => {
        return {
            id: randomString(16),
            createdAt: Date.now(),
            ...input,
            updatedAt: Date.now(),
        };
    },
    gsis: {
        keysByEmail: {
            partitionKey: 'email',
            projection: 'KEYS',
        },
    },
});

const userRepo = new UserRepository();

// does a PUT, but throws if id already exists
const newUser = await userRepo.create({
    name: 'Dynamo Box',
    email: 'dynamo@box.com'
});

// last param of all methods allow advanced configuration
const user = await userRepo.getOrThrow({ id: newUser.id }, { consistentRead: true });

```

The class can also be extended:

```typescript
export class UserRepositoryExtended extends UserRepository {
    constructor() {
        super({
            tableName: usersTableName,
            client: new DynamoDBClient({ region: 'us-east-1', endpoint: 'localhost' }),
        });
    }

    async getByEmail(userEmail: string): Promise<User> {
        const email = userEmail.toLowerCase();

        const [userKeys] = await this.queryGsi('keysByEmail', { email });
        if (!userKeys) {
            throw new Error('User not found');
        }
        return this.getOrThrow({ id: userKeys.id });
    }
}
```

## Docs

Library is nearing 1.0 release, at which point full documentation will become available.
It is currently being used in production environments so I welcome brave community members to give it a spin in its current state. I don't suspect any major API changes at this point and I do my absolute best to respect SemVer.

---

### Wishlist

-   transact write/get items support
-   make special case for TTL field, support function that automatically sets it based on data
-   count() method that automatically projects partition key only and returns number
-   make it easier to override methods, potentially by not producing an anonymous class
-   automatically remove keys from update expressions? potentially anything "readonly" as well
-   getGsi() and getGsiOrThrow() that fetches one record
-   custom events (configurable logic, i.e. status change events)
-   safe "transform" operation that performs a GET + PUT (with transform function) that uses consistent read, conditional
    expression + automatic retry

---
_Source: https://npm.io/package/@jayalfredprufrock/dynamo-box · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
