https://github.com/neuledge/ddb-table
🔒 Strongly typed library for querying and modeling DynamoDB documents in TypeScript.
https://github.com/neuledge/ddb-table
dynamodb library nodejs query strongly-typed typescript
Last synced: about 1 month ago
JSON representation
🔒 Strongly typed library for querying and modeling DynamoDB documents in TypeScript.
- Host: GitHub
- URL: https://github.com/neuledge/ddb-table
- Owner: neuledge
- License: mit
- Created: 2020-04-25T12:43:13.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-20T11:22:02.000Z (11 months ago)
- Last Synced: 2025-04-13T00:36:36.201Z (about 1 month ago)
- Topics: dynamodb, library, nodejs, query, strongly-typed, typescript
- Language: TypeScript
- Homepage:
- Size: 2.13 MB
- Stars: 129
- Watchers: 5
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
🔒 DDB-Table
Strongly typed library for querying and modeling DynamoDB documents in TypeScript.
**DDB-Table** was built to provide strongly-typed data structures over DynamoDB tables. Using **AWS
DocumentClient** & **TypeScript** you can easily fetch and store any JSON document and validate it’s
structure statically. Query secondary indexes and run complicated update expressions without any
error on runtime.
```ts
await table
.update('[email protected]')
.set('FullName', 'John Doe')
// 🚨 TypeScript Error: 'fullName' is not assignable to 'Email' | 'FullName'
.condition((cond) => cond.eq('fullName', 'Johnny Doe'))
.exec();
```
### Main Features
- **Strongly Typed** - End-to-end TypeScript validation for your data.
- **Easy Query Expressions** - Automatically escape name attributes and values.
- **Smart Projections** - Make sure you only access the fields you project.
- **Query & Scan Indexes** - Complete support for global or local indexes.
- **Pure JavaScript** - Also works without TypeScript.
### Sponsored by ❤️
If you like this project, please [consider sponsoring us](https://github.com/sponsors/neuledge) to help us continue to maintain and improve
this project.
## Install
```bash
npm i ddb-table
```
## Usage
```ts
import Table from 'ddb-table';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
interface MessageSchema {
threadId: string;
timestamp: number;
senderId: string;
message: string;
status: 'sent' | 'received';
tags?: Set;
attachments: {
name: string;
URL: string;
}[];
}
const client = new DynamoDBClient({
// settings...
});
// create the basic table definition
const messages = new Table({
tableName: 'Messages',
primaryKey: 'threadId',
sortKey: 'timestamp',
documentClient: DynamoDBDocument.from(client);
});
const updateRes = await messages
.update('[email protected]', 1588191225322)
.set('message', 'Hello World!')
.add('tags', new Set(['unread', 'important']))
.set('attachments', (exp) =>
exp.listAppend([{ name: 'Test', URL: 'demo.com' }]),
)
.return('ALL_NEW')
.exec();
console.log(updateRes.Attributes);
```
#### Working with indexes as well:
```ts
// create a secondary index definition
type SenderTimestampIndex = Pick<
MessageSchema,
'threadId' | 'timestamp' | 'senderId'
>;
const outboxIndex = messages.index<
SenderTimestampIndex,
'senderId',
'timestamp'
>('senderId-timestamp-index', 'senderId', 'timestamp');
const it = outboxIndex
.query()
.keyCondition((cond) => cond.eq('senderId', '[email protected]'))
.keyCondition((cond) =>
cond.between('timestamp', Date.now() - 3600e3, Date.now()),
)
.project({ threadId: 1, message: 1 })
.reverseIndex()
.entries();
for await (const item of it) {
console.log(item);
}
```
### Error Handling
```ts
import { DynamoDBExceptionName } from 'ddb-table';
try {
await table.put(...).exec();
} catch (err) {
if ((err as DynamoDBServiceException)?.name === DynamoDBExceptionName.ConditionalCheckFailedException) {
// handle exception
}
}
```
## License
[MIT](LICENSE) license © 2022 [Neuledge](https://neuledge.com)