https://github.com/spencerlepine/dynamo-query
⚡ Type-safe ORM for AWS DynamoDB NoSQL, inspired by Prisma
https://github.com/spencerlepine/dynamo-query
aws-dynamodb dynamo dynamo-db dynamo-sdk dynamodb nosql nosql-query-builder orm prisma prisma-orm query-builder querybuilder sql-query-builder
Last synced: about 2 months ago
JSON representation
⚡ Type-safe ORM for AWS DynamoDB NoSQL, inspired by Prisma
- Host: GitHub
- URL: https://github.com/spencerlepine/dynamo-query
- Owner: spencerlepine
- License: other
- Created: 2025-03-03T17:20:01.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-03-03T19:07:08.000Z (10 months ago)
- Last Synced: 2025-03-03T19:21:45.006Z (10 months ago)
- Topics: aws-dynamodb, dynamo, dynamo-db, dynamo-sdk, dynamodb, nosql, nosql-query-builder, orm, prisma, prisma-orm, query-builder, querybuilder, sql-query-builder
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/dynamo-query
- Size: 4.31 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Dynamo-Query
> This is a type-safe ORM for AWS DynamoDB NoSQL, inspired by [Prisma.io](https://www.prisma.io/)
This package is for you if you're building data-driven applications and you're using AWS DynamoDB NoSQL as the main database.
If you're tired of writing raw SQL for querying AWS DynamoDB NoSQL database with complex filters, then this package is for you, too.
## 🧠 Why Dynamo-Query over `@aws-sdk/client-dynamodb`?
- ✅ Type-safe advanced filtering
- 💪 Build-in SQL query-builder
- 🚀 Dynamic, type-safe field-selection - maximizing performance
- 🍃 No more hard-coding SQL queries, just bring your models
## 🚶♂️ How to get started?
Install this package
```shell
npm install dynamo-query
yarn install dynamo-query
pnpm install dynamo-query
```
Instantiate the client
```typescript
import { createClient } from 'dynamo-query';
type User = {
id: string;
firstName: string;
lastName: string;
age: number;
createdAt: Date;
isSuperAdmin: boolean;
};
type Post = {
id: string;
title: string;
content: string;
createdBy: string; // foreign key - User.id
};
// Example 1 - Using connection string
const orm = createClient({
region: 'us-east-1', // AWS region
credentials: {
accessKeyId: '',
secretAccessKey: '',
},
models: t => ({
user: t.createModel({
tableName: 'Users',
partitionKey: 'userId',
options: { fields: ['name', 'email', 'createdAt'] },
}),
post: t.createModel({
tableName: 'Posts',
partitionKey: 'postId',
sortKey: 'createdAt',
options: { fields: ['title', 'content', 'authorId'] },
}),
}),
});
// Example 2 - Using custom endpoint (useful for local development/testing)
const orm = createClient({
region: 'us-east-1',
endpoint: 'http://localhost:8000', // Custom endpoint for local DynamoDB
credentials: {
accessKeyId: 'fakeMyKeyId',
secretAccessKey: 'fakeSecretAccessKey',
},
models: t => ({
user: t.createModel({
tableName: 'Users',
partitionKey: 'userId',
options: { fields: ['name', 'email', 'createdAt'] },
}),
post: t.createModel({
tableName: 'Posts',
partitionKey: 'postId',
sortKey: 'createdAt',
options: { fields: ['title', 'content', 'authorId'] },
}),
}),
});
// Example 3 - With additional model options
const orm = createClient({
region: 'us-east-1',
credentials: {
accessKeyId: '',
secretAccessKey: '',
},
models: t => ({
user: t.createModel({
tableName: '',
partitionKey: 'id',
options: {
fields: {
id: true, // Auto-generate IDs
timestamp: true, // Auto-generate createdAt/updatedAt
},
},
}),
post: t.createModel({
tableName: '',
partitionKey: 'id',
sortKey: 'createdAt',
options: {
fields: false, // Disable auto-generated fields
},
}),
}),
});
// Notes:
// - The 'partitionKey' is required and must match an attribute in your table
// - The 'sortKey' is optional and enables range queries when specified
// - Tables must be created beforehand with matching partition/sort keys
```
Make queries with simple filters
```typescript
const getFilteredUsers = async () => {
return await orm.user.findMany({
where: { firstName: { contains: 'Sam' } },
});
};
const getFilteredUsers = async () => {
return await orm.user.findMany({
where: { age: { gte: 18 } },
});
};
const getFilteredUsers = async () => {
return await orm.user.findMany({
where: { createdAt: { gte: new Date('2024-01-01') } },
});
};
const getFilteredposts = async () => {
return await orm.post.findMany({
where: { createdBy: { equals: '' } },
});
};
```
Make a query without any filters
```typescript
// This will return maximum of 100 items by default
const result = orm.user.findMany({});
```
Or, make a query by applying some complex filters, field-selections, and pagination logic:
```typescript
const getFilteredUsers = async () => {
return await orm.user.findMany({
where: {
firstName: {
startsWith: 'Sa',
endsWith: 'lyn',
mode: 'INSENSITIVE',
},
age: {
lte: 20,
gte: 10,
not: 15,
},
isSuperAdmin: {
not: true,
},
createdAt: {
lte: new Date('2024-12-31'),
gte: new Date('2024-12-01'),
not: new Date('2024-12-15'),
},
},
orderBy: {
firstName: 'ASC',
},
take: 10,
select: {
id: true,
firstName: true,
age: true,
},
nextCursor: '',
});
};
```
Find an item by ID
```typescript
// without field-selection
const result = orm.user.findOne({
where: { id: 'USER_ID' },
});
// with field-selection
const result = orm.user.findOne({
where: { id: 'USER_ID' },
select: { id: true, firstName: true },
});
```
Create an item
```typescript
type CreateUserInput = Partial;
const result = orm.user.create({
data: {
firstName: '',
lastName: '',
},
});
```
Update an item
```typescript
type UpdateUserInput = Partial;
const result = orm.user.update({
where: { id: '' },
data: {
firstName: '',
},
});
```
Delete an item
```typescript
const result = orm.user.delete({
where: { id: '' },
});
```
## 📝 Roadmap
- Core Query builder
- Comprehensive unit/e2e test coverage
- Bulk create / update operations
- Observability - query logging
- Filtering on more complex data types such as enums, enum arrays, string arrays & number arrays
## Contributing
We welcome contributions from the community! If you're interested in contributing to this project, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file to get started.
## Disclaimer
This project is a fork of [Mingyang-Li/cosmox](https://github.com/Mingyang-Li/cosmox) (credit to [@Mingyang-Li](https://github.com/Mingyang-Li)), inspired by Prisma, and is not an
official AWS product. Provided "as is" without warranty.
## License
[MIT](./LICENSE)