dyna-record

library0.7.2jsnpmunverified

Dyna-Record (v0.7.2) is a strongly typed TypeScript ORM and data modeler for Amazon DynamoDB that implements the single-table design and adjacency list patterns with ACID-compliant transactions. Released on npm with a monthly cadence, it requires Node.js >=22 and TypeScript >=6. Key differentiators from other DynamoDB ORMs like DynamoDB Toolbox include native decorator-based entity definitions, runtime schema validation, and full ESM support. Ships TypeScript types.

database

npm install dyna-record

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DYNA-RECORD

dyna-record

databasejavascriptv0.7.2

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.

DynaRecord

✓ import DynaRecord from 'dyna-record'

✗ const DynaRecord = require('dyna-record')

ESM-only since v0.7.0. CommonJS users must use dynamic import().

Table

✓ import { Table } from 'dyna-record'

✗ import Table from 'dyna-record/Table'

Named export, not subpath import.

Entity

✓ import { Entity } from 'dyna-record'

Decorator for entity classes.

PartitionKey

✓ import { PartitionKey } from 'dyna-record'

✗ type PartitionKey = string

Built-in type, not a string alias.

SortKey

✓ import { SortKey } from 'dyna-record'

Built-in type for sort key.

PartitionKeyAttribute

✓ import { PartitionKeyAttribute } from 'dyna-record'

Property decorator for partition key.

Defines a DynamoDB table, an entity class, and creates a record using CRUD operations.

import DynaRecord, { Table, Entity, PartitionKeyAttribute, SortKeyAttribute, PartitionKey, SortKey } from 'dyna-record'; @Table({ name: 'my-table' }) abstract class MyTable extends DynaRecord { @PartitionKeyAttribute({ alias: 'PK' }) public readonly pk: PartitionKey; @SortKeyAttribute({ alias: 'SK' }) public readonly sk: SortKey; } @Entity({ name: 'User' }) class User extends MyTable { @Attribute({ name: 'user_id' }) public userId: string; @Attribute() public name: string; } const user = await User.create({ userId: 'u1', name: 'Alice', pk: 'USER#u1', sk: 'METADATA#u1', }); console.log(user.name);

Debug

Known issues

breakingESM-only since v0.7.0: require() on dyna-record fails on Node <22.12.

fix

Use dynamic import(): `const DynaRecord = await import('dyna-record')` or upgrade Node to 22.12+ with ESM.

affects: >=0.7.0

breakingDecorators require TC39 Stage 3 pattern: Do not enable experimentalDecorators in tsconfig.

fix

Remove `experimentalDecorators` from tsconfig.json; use TypeScript >=5.0.

affects: >=0.1.0

deprecatedOld v0.6.x APIs (e.g., `createTable`) removed; use `Table` decorator with `name` property.

fix

Replace `createTable('my-table')` with `@Table({ name: 'my-table' })`.

affects: >=0.7.0

gotchaRuntime schema validation: attribute types must match decorators; mismatches throw at runtime.

fix

Ensure all entity properties have matching @Attribute decorators with correct types.

affects: >=0.1.0

gotchaSingle-table design: PK and SK aliases must be consistent across entities to avoid hot partitions.

fix

Use partition key alias pattern (e.g., 'USER#<id>') consistently; avoid generic keys.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'dyna-record' or its corresponding type declarations.

Missing npm install or ESM import issue.

fix

Run `npm install dyna-record`. Ensure typeRoots includes node_modules or use `esModuleInterop`.

DynaRecord is not a constructor.

Using CommonJS require() on ESM-only package.

fix

Replace `const DynaRecord = require('dyna-record')` with `import DynaRecord from 'dyna-record'` or `await import('dyna-record')`.

Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option to remove this warning.

TypeScript 5.x+ defaults to TC39 decorators, but experimentalDecorators is still set.

fix

Remove `experimentalDecorators: true` from tsconfig.json.

TypeError: Class extends value undefined is not a constructor or null

Circular imports with Entity classes.

fix

Use lazy import or forward references for related entities.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

aws-sdkrequiredRuntime dependency for DynamoDB client operations

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/dsdavis4/dyna-record ↗

packagedyna-record ↗

homepagehttps://github.com/dsdavis4/dyna-record#readme ↗