dynamodb-eloquent

library1.0.21jsnpmunverified

DynamoDB Eloquent is a TypeScript ORM for Amazon DynamoDB, inspired by Laravel Eloquent. Current stable version is 1.0.21, released as a single initial version. It provides a familiar ActiveRecord-style interface for DynamoDB operations including CRUD, filtering, scanning, pagination, and migrations. Key differentiators: simple repository pattern, automatic index mapping, built-in migration system, and support for secondary indexes with sorting. It runs in Node.js and supports both JavaScript and TypeScript.

database

npm install dynamodb-eloquent

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DYNAMODB-ELOQUENT

dynamodb-eloquent

databasejavascriptv1.0.21

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DynamoDBRepository

✓ import { DynamoDBRepository } from 'dynamodb-eloquent'

✗ const DynamoDBRepository = require('dynamodb-eloquent')

ES module import is required; package does not export a CommonJS default.

DynamoDBRepository

✓ import DynamoDBRepository from 'dynamodb-eloquent'

✗ import { DynamoDBRepository } from 'dynamodb-eloquent'

Default export is also available, but the named export is the documented pattern.

DynamoDBRepository

✓ const { DynamoDBRepository } = require('dynamodb-eloquent')

✗ const DynamoDBRepository = require('dynamodb-eloquent').default

CommonJS require destructuring works for named exports.

Demonstrates how to define a repository class extending DynamoDBRepository and perform basic CRUD operations.

import { DynamoDBRepository } from 'dynamodb-eloquent'; class UserRepository extends DynamoDBRepository { protected table = 'Users'; protected mappingIndex = { email: 'email', }; } const userRepo = new UserRepository(); async function main() { await userRepo.create({ id: '1', name: 'Bill' }); const user = await userRepo.findOrFail('1'); console.log(user.name); // Bill } main().catch(console.error);

Debug

Known issues

breakingPackage uses mappingIndex to define GSI names; missing index will cause errors on findBy operations.

fix

Ensure mappingIndex includes each GSI name used in queries.

affects: >=1.0.0

gotchafindBy and findOneBy require an indexName parameter; querying without index will throw.

fix

Always pass the GSI name as second argument to findBy/findOneBy.

affects: >=1.0.0

gotchadelete method expects primary key value only, not full object.

fix

Use userRepo.delete('id-value') not userRepo.delete({id: 'id-value'}).

affects: >=1.0.0

deprecatedscanData method is deprecated in favor of scanDataV2.

fix

Use scanDataV2 instead of scanData.

affects: >=1.0.0

gotchaEnvironment variables for AWS credentials must be set before first operation.

fix

Set AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_PROFILE in environment.

affects: >=1.0.0

Errors

Common errors & fixes

MissingRequiredParameter: Missing required key 'Key' in params

Calling delete or update without providing the primary key value.

fix

Pass the primary key value (e.g., id) as a string to delete() or include 'id' in update params.

ValidationException: The provided key element does not match the schema

Passing wrong data type for key (e.g., number instead of string) or missing sort key.

fix

Ensure key values match table schema (string vs number) and include sort key if defined.

Error: Attribute 'email' is not used in any index

Using mappingIndex with an index name that does not exist in DynamoDB table.

fix

Verify the GSI name exists in AWS console or create it, and update mappingIndex accordingly.

TypeError: dynamodb_eloquent.migration:create is not a script

Trying to run migration scripts without adding them to package.json scripts.

fix

Add the scripts as shown in documentation and ensure the package is installed.

Upgrade

Version history

1.0.21latest on npm

Audit

Dependencies

aws-sdkrequiredAWS SDK for JavaScript is required to interact with DynamoDB.

dotenvoptionalUsed for loading environment variables from .env file.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ducxinh/dynamodb-eloquent ↗

packagedynamodb-eloquent ↗

homepagehttps://github.com/ducxinh/dynamodb-eloquent ↗