Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[3.4.0] - 2026-09-08

Added

  • Cursor pagination: where() returns the instances with a non-enumerable cursor property whenever a limit is given. Passing it back as { cursor } reads only the next page, where skip reads and discards everything before it on every page.
  • createMany(rows, options?): creates several records with BatchWriteItem, 25 per request, retrying whatever DynamoDB leaves unprocessed. It cannot check for duplicate primary keys, which BatchWriteItem does not support.
  • deleteMany(ids, options?): deletes by primary key without reading the records first. Always a hard delete and it runs no hooks.
  • deleted query option: replaces _includeTrashed, which keeps working as a deprecated alias.
  • Top-level where option: the filters in WhereOptions.where are now merged with those of the first argument. Until now they were silently ignored.
  • New public types: QueryResult<M>, DynamiteConfig.

Changed

  • Reads by primary key use GetItem and BatchGetItem: = on the primary key is a single GetItem, and in a BatchGetItem of 100 keys per request, instead of one Query per value. Any extra filter is evaluated over the item already read, so the query stays a single request.
  • limit stops the read: pagination stops as soon as it has enough items, and the limit travels to DynamoDB as Limit when nothing is left to filter server-side. first() no longer reads the whole table.
  • Parallel Scan: a read with no limit that ends in a Scan is split into four segments. Same read units, a fraction of the latency. Without order the resulting order is arbitrary, as it already was.
  • Native ordering by sort key: a Query on the primary key ordered by the @IndexSort column uses ScanIndexForward instead of sorting in memory.
  • update() by primary key writes without reading: a single UpdateItem with the touched fields, conditioned on the record existing, whenever no @Set or @Validate of those fields declares the current argument. Instance update() does the same, using the values it already holds.
  • Batched writes: delete(), mass update(), sync() on a relation, createMany() and deleteMany() write in batches of 25.
  • Pivot tables are queried, never scanned: attach(), detach(), instance sync() and loading a @ManyToMany go through the pivot's <foreign_key>_index GSI, falling back to a Scan only when the index does not exist.
  • Dependencies: pluralize, uuid, @arcaelas/utils and @aws-sdk/lib-dynamodb were declared but never imported, and are gone. @aws-sdk/util-dynamodb was imported without being declared, and is now a dependency. The AWS SDK moved from an exact pin to ^3.329.0, so it dedupes against the consumer's copy.

Fixed

  • The primary key of a model renamed with @Name is now used correctly in delete, forceDestroy, increment and decrement.
  • Documentation: withTrashed(), onlyTrashed(), relationDecorator(), ColumnBuilder and WrapperEntry were documented and do not exist. The @BelongsTo signature was documented with its arguments swapped. connect() was documented as creating tables, which sync() does. The write pipeline was documented as (current, next) when it takes (next, current).

[3.2.1] - 2026-09-03

Fixed

  • WhereFilters typing: in/$in now accept an array of the column type ({ role: { $in: ["user", "assistant"] } }); before, the type demanded a single value and TypeScript rejected valid filters.

[3.2.0] - 2026-09-03

Changed

  • @PrimaryKey accepts any non-empty string id. ULID is still generated when no id is given, but existing UUID (or custom) keys no longer throw Invalid ULID.
  • @Index columns are GSIs: connect() registers every non-primary @Index column as a <field>_index GSI and sync() creates it, so where/first on those fields use QueryCommand. Before, only the foreign keys of @HasMany/@HasOne were considered.
  • $in on the primary key or a GSI runs one QueryCommand per distinct value instead of a full ScanCommand with an OR filter. Relation loading (include) benefits automatically.

Fixed

  • Primary key detection prefers the @PrimaryKey column over the first @Index column.
  • Self-healing after a missing GSI now removes the column's database name from the GSI registry.

[3.0.0] - 2026-06-06

Breaking Changes

  • Unified mutation options: static create, update, delete, increment, decrement and instance save, update, destroy, forceDestroy now take a single options object as their last argument: MutationOptions = { hook?: boolean; tx?: TransactionContext }.
  • Removed positional tx: the transaction is now passed inside the options object. Replace the old trailing tx argument with { tx } — for example User.create(data, { tx }) and order.destroy({ tx }).

Added

  • Lifecycle hooks: six instance-method decorators — @BeforeCreate, @AfterCreate, @BeforeUpdate, @AfterUpdate, @BeforeDestroy, @AfterDestroy. Opt-in per operation with { hook: true }. Inside a hook this is the entity instance; the update hooks receive the changes delta as their first argument. Multiple hooks of the same type run in declaration order and async hooks are awaited. In mass update/delete they run once per affected entity. before* hooks run before persisting and after* hooks run after (after commit inside a transaction). increment()/decrement() accept { tx } but do not trigger hooks.
  • TransactionContext.onCommit now accepts async callbacks.

[2.0.0] - 2026-04-02

Breaking Changes

  • Primitive decorators: @Get, @Set, @Validate replace @Mutate, @Column, @Serialize (removed).
  • @Default moved from get to set pipeline. Resolves at construction, not at read time.
  • @PrimaryKey generates ULID instead of UUID. Validates ULID format. Immutable after first assignment.
  • @NotNull is composition of @Validate. Removed store.nullable from schema.
  • @UpdatedAt respects explicit values. Only generates now() when no value is passed.
  • @BelongsTo signature unified to (model, foreignKey, localKey), same as @HasMany/@HasOne.
  • Set pipeline argument order changed from (current, next) to (next, current).
  • Constructor runs setters for all fields, not just those present in props.
  • connect() no longer creates tables. Only configures the DynamoDB client.
  • Removed: withTrashed(), onlyTrashed(), relationDecorator(), @Column, @Mutate, @Serialize.
  • where() throws error if field does not exist in schema.columns.

Added

  • sync(): creates tables, GSIs and pivot tables. Auto-detects GSIs from relations. Parallel operations with polling.
  • Smart where(): QueryCommand with PK or GSI, fallback to ScanCommand. Self-healing if GSI doesn't exist.
  • connect() computes expected GSIs from schemas without API calls.
  • update()/delete() PK optimization: direct GetItemCommand/DeleteItemCommand.
  • increment()/decrement(): atomic via UpdateItemCommand. Static, instance and transactional.
  • create() uniqueness: ConditionExpression: attribute_not_exists(pk).
  • ULID: internal generator, no dependencies. Monotonic, sequential, lexicographically sortable.
  • Transactions: addUpdate(), onCommit(), __isPersisted post-commit, auto-chunking in batches of 25.
  • Typing: Schema with real types. WhereOptions with recursive typed include. PickByType<T, V>. order accepts objects.

Fixed

  • @CreatedAt now sets store.createdAt = true for default sort.
  • Relation cache simplified with dirty flag.
  • processIncludes assigns via setter.
  • _mapPropertiesToDB removed (dead code).
  • where() normalization unified.

Tests

  • 165 tests against DynamoDB Local: decorators, CRUD, recursive relations, ManyToMany, combined filters, bulk 3000, Query vs Scan, pipeline contracts, PK immutability, PK duplicates, ULID sequentiality.

[1.0.23] - 2025-12-13

Fixed

  • mkdocs.yml: Corrected navigation structure pointing to non-existent paths (guides/, api/)
  • TOC anchors: Fixed 47 broken anchor links across ES/DE documentation files
  • Removed accents from anchors (#introducción → #introduccion)
  • Fixed triple-dash anchors (#primarykey---claves → #primarykey-claves)
  • docs/index.es.md, docs/index.de.md: Fixed homepage links to correct paths
  • docs/installation.*.md: Fixed API reference links (./api/table.md → ./references/table.md)
  • docs/getting-started.*.md: Fixed core-concepts and examples links
  • docs/references/client.*.md: Fixed decorators link format (./decorators/ → ./decorators.md)
  • docs/references/decorators.de.md: Removed TOC entries for non-existent sections (file is incomplete)
  • docs/examples/relations.*.md: Fixed decorator reference links to correct anchors
  • docs/examples/advanced.*.md: Fixed core-concepts cross-reference link

Documentation

  • Resolved all MkDocs build warnings (from 47 to 0 broken links)
  • Improved multilingual documentation consistency (EN/ES/DE)
  • Fixed German navbar appearing on 404 pages due to incorrect link paths

[1.0.20] - 2025-12-12

Added

  • API.md - Comprehensive API documentation covering decorators, schemas, and methods
  • docs/references/table.md - Complete Table class API reference in English
  • docs/references/types.md - Full TypeScript types documentation in English
  • src/@types/index.ts - Centralized TypeScript type definitions for better type inference
  • eslint.config.js - ESLint configuration for consistent code quality
  • scripts/generate_seed.ts - Utility script for generating test seed data
  • scripts/load_seed.ts - Utility script for loading seed data into DynamoDB
  • tsx.config.json - TSX runtime configuration for development

Changed

  • Reorganized documentation structure from guides/, api/, advanced/ into unified references/ directory
  • Renamed example files for consistency: basic-model → basic, advanced-queries → advanced, relationships → relations
  • Moved getting-started.md from guides/ to documentation root for easier access
  • Updated ~40 internal documentation links to match new structure
  • Simplified navigation in index.md with cleaner hierarchy
  • Lowercase changelog filenames for cross-platform consistency
  • Refactored src/core/table.ts with improved query handling and relationship loading
  • Enhanced src/core/decorator.ts with optimized getter/setter pipelines
  • Improved src/core/client.ts with better DynamoDB connection handling
  • Optimized all decorators in src/decorators/*.ts for better performance
  • Refactored src/utils/relations.ts with cleaner relationship resolution logic
  • Updated src/index.ts exports for simplified module structure
  • Reduced src/index.test.ts test suite for faster execution
  • Updated package.json with improved scripts and dependencies
  • Cleaned up yarn.lock removing redundant dependency entries

Removed

  • docs/examples/validation.* - Redundant examples, content merged into basic examples
  • docs/guides/relationships.* - Duplicate content, consolidated into relations examples
  • docs/api/table.md and docs/api/types.md - Replaced with new English versions in references/
  • src/core/method.ts - Functionality consolidated into table.ts

Fixed

  • Corrected table.md and types.md language (were incorrectly in Spanish, now properly in English)
  • Fixed all broken internal documentation links across 39 files
  • Resolved inconsistent file naming conventions in examples directory

Performance

  • Reduced test file complexity for faster CI/CD execution
  • Optimized yarn.lock with -2873 lines of redundant entries
  • Net codebase reduction of -9220 lines while maintaining functionality

Documentation

  • Complete documentation restructure following: Get Started → Installation → Examples → References → Changelog
  • Multilingual support maintained (EN/ES/DE) across all documentation files
  • Improved cross-referencing between related documentation sections

[1.0.17] - 2025-12-03

Added

  • @Serialize(fromDB, toDB) - Bidirectional data transformation decorator
  • @DeleteAt() - Soft delete decorator with timestamp
  • Dynamite.tx() - Atomic transactions with automatic rollback
  • TransactionContext class for managing transactional operations
  • withTrashed() method to include soft-deleted records
  • onlyTrashed() method to query only soft-deleted records
  • Support for null as fallback in @Serialize parameters

Changed

  • Enhanced destroy() method to support soft delete when @DeleteAt is present
  • destroy() now accepts optional TransactionContext parameter for transactional operations
  • Improved documentation with @Serialize and @DeleteAt examples
  • Consolidated decorator documentation into /guides/decorators.md

Removed

  • /api/decorators/ directory (21 files) - content merged into /guides/decorators.md

Documentation

  • Added comprehensive @Serialize documentation with encryption, compression examples
  • Added @DeleteAt documentation with trash system patterns
  • Added Dynamite.tx() transaction API documentation
  • Updated model examples to include new decorators
  • Consolidated multilingual documentation (EN/ES/DE)

[1.0.13] - 2025-10-13

Current Release

This is a stable release of @arcaelas/dynamite - a modern, decorator-first ORM for DynamoDB with full TypeScript support.

Features

Core Functionality

  • Full-featured ORM with decorator-first approach
  • Complete TypeScript support with type safety
  • Auto table creation and management
  • Zero boilerplate configuration

Decorators

  • Core Decorators: @PrimaryKey(), @Index(), @IndexSort(), @Name()
  • Data Decorators: @Default(), @Mutate(), @Validate(), @NotNull()
  • Timestamp Decorators: @CreatedAt(), @UpdatedAt()
  • Relationship Decorators: @HasMany(), @BelongsTo()

TypeScript Types

  • CreationOptional<T> - Mark fields as optional during creation
  • NonAttribute<T> - Exclude computed properties from database
  • HasMany<T> - One-to-many relationships
  • BelongsTo<T> - Many-to-one relationships
  • InferAttributes<T> - Type inference for model attributes

Query Operations

  • Basic CRUD operations (create, read, update, delete)
  • Advanced query operators: =, !=, <, <=, >, >=, in, not-in, contains, begins-with
  • Pagination support with limit and skip
  • Sorting with order (ASC/DESC)
  • Attribute selection with attributes array
  • Complex filtering with multiple conditions

Relationships

  • One-to-many relationships via @HasMany()
  • Many-to-one relationships via @BelongsTo()
  • Nested relationship loading with include
  • Filtered relationship queries
  • Recursive relationship support

Data Validation & Transformation

  • Field validation with custom validators
  • Data mutation/transformation before save
  • Multi-step validation chains
  • Not-null constraints
  • Email, age, and custom format validation

Configuration

  • AWS DynamoDB connection support
  • DynamoDB Local development support
  • Custom endpoint configuration
  • Flexible credential management
  • Environment variable support

Dependencies

  • @aws-sdk/client-dynamodb: ^3.329.0
  • @aws-sdk/lib-dynamodb: ^3.329.0
  • pluralize: ^8.0.0
  • uuid: ^11.1.0

Documentation

  • Comprehensive README with examples
  • TypeScript types documentation
  • API reference guide
  • Development setup instructions
  • Troubleshooting guide
  • Best practices and performance tips

[1.0.0] - Initial Release

Added

  • Initial release of @arcaelas/dynamite
  • Base Table class implementation
  • Core decorator system
  • DynamoDB client wrapper
  • Metadata management system
  • Basic CRUD operations
  • Query builder functionality
  • Relationship support foundation
  • TypeScript definitions
  • Jest testing setup

Version History Summary

  • v3.0.0 (Current) - Lifecycle hooks (@Before/@After) and unified { hook, tx } mutation options (breaking: positional tx removed)
  • v1.0.23 - Documentation link fixes, TOC anchor corrections, multilingual consistency
  • v1.0.20 - Documentation restructure, codebase optimization, API.md creation
  • v1.0.17 - Added @Serialize, @DeleteAt, Dynamite.tx() transactions
  • v1.0.13 - Stable release with full feature set
  • v1.0.0 - Initial public release
  • Repository: https://github.com/arcaelas/dynamite
  • Issues: https://github.com/arcaelas/dynamite/issues
  • NPM Package: https://www.npmjs.com/package/@arcaelas/dynamite
  • Author: Arcaelas Insiders

Migration Guides

Upgrading to v1.0.20

If you have external links to the documentation, update them: - docs/guides/getting-started.md → docs/getting-started.md - docs/api/* → docs/references/* - docs/guides/decorators.md → docs/references/decorators.md - docs/examples/basic-model.md → docs/examples/basic.md - docs/examples/advanced-queries.md → docs/examples/advanced.md - docs/examples/relationships.md → docs/examples/relations.md

No breaking changes to the API. All features are backward compatible.

Upgrading to v1.0.13

No breaking changes from v1.0.0. All features are backward compatible.

Contributing

See GitHub Repository for contribution guidelines.

Note: For detailed usage examples and API documentation, please refer to the GitHub Repository.