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: 12 days 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 4 years ago)
• Default Branch: master
• Last Pushed: 2024-01-11T15:45:28.000Z (6 months ago)
• Last Synced: 2024-05-01T11:32:02.453Z (2 months ago)
• Topics: dynamodb, library, nodejs, query, strongly-typed, typescript
• Language: TypeScript
• Homepage:
• Size: 2.04 MB
• Stars: 133
• Watchers: 7
• Forks: 2
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Lists

• awesome-typescript - DDB-Table
• awesome-typescript - DDB-Table
• awesome-typescript - DDB-Table
• awesome-typescript - DDB-Table

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)