@stonyx/orm 0.3.2-beta.8 → 0.3.2-beta.80

package/dist/dynamodb/operation-builder.js

@@ -0,0 +1,109 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(tableName, item, conditionExpression) {
+    const params = { TableName: tableName, Item: item };
+    if (conditionExpression)
+        params.ConditionExpression = conditionExpression;
+    return params;
+}
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(tableName, key, updates) {
+    const names = {};
+    const values = {};
+    const setClauses = [];
+    for (const [attr, val] of Object.entries(updates)) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        setClauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    return {
+        TableName: tableName,
+        Key: key,
+        UpdateExpression: `SET ${setClauses.join(', ')}`,
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+        ReturnValues: 'NONE',
+    };
+}
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(tableName, conditions, exclusiveStartKey) {
+    const params = { TableName: tableName };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    if (conditions && Object.keys(conditions).length > 0) {
+        const names = {};
+        const values = {};
+        const clauses = [];
+        for (const [attr, val] of Object.entries(conditions)) {
+            const nameAlias = `#${attr}`;
+            const valAlias = `:${attr}`;
+            names[nameAlias] = attr;
+            values[valAlias] = val;
+            clauses.push(`${nameAlias} = ${valAlias}`);
+        }
+        params.FilterExpression = clauses.join(' AND ');
+        params.ExpressionAttributeNames = names;
+        params.ExpressionAttributeValues = values;
+    }
+    return params;
+}
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(tableName, indexName, keyConditions, exclusiveStartKey) {
+    const names = {};
+    const values = {};
+    const clauses = [];
+    for (const [attr, val] of Object.entries(keyConditions)) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    const params = {
+        TableName: tableName,
+        IndexName: indexName,
+        KeyConditionExpression: clauses.join(' AND '),
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+    };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    return params;
+}

package/dist/dynamodb/type-map.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+declare const typeMap: Record<string, DynamoScalarType>;
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export declare function getDynamoType(attrType: string): DynamoScalarType;
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export declare function getDynamoKeyType(attrType: string): 'S' | 'N';
+export default typeMap;

package/dist/dynamodb/type-map.js

@@ -0,0 +1,48 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap = {
+    string: 'S',
+    number: 'N',
+    float: 'N',
+    boolean: 'BOOL',
+    date: 'S',
+    timestamp: 'N',
+    passthrough: 'S',
+    trim: 'S',
+    uppercase: 'S',
+    ceil: 'N',
+    floor: 'N',
+    round: 'N',
+};
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType) {
+    return typeMap[attrType] ?? 'S';
+}
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType) {
+    const t = getDynamoType(attrType);
+    return t === 'N' ? 'N' : 'S';
+}
+export default typeMap;

package/dist/main.js

@@ -54,6 +54,10 @@ export default class Orm {
         Orm.instance = this;
     }
     async init() {
+        // Self-register so log.db works even when @stonyx/orm is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'white', logMethod = 'db' } = config.orm;
+        log.defineType(logMethod, logColor);
         const { paths, restServer } = config.orm;
         const promises = ['Model', 'Serializer', 'Transform'].map(type => {
             const lowerCaseType = type.toLowerCase();
@@ -115,6 +119,12 @@ export default class Orm {
             this.db = this.sqlDb;
             promises.push(this.sqlDb.init());
         }
+        else if (config.orm.dynamodb) {
+            const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+            this.sqlDb = new DynamoDBDB();
+            this.db = this.sqlDb;
+            promises.push(this.sqlDb.init());
+        }
         else if (this.options.dbType !== 'none') {
             const db = new DB();
             this.db = db;

package/dist/manage-record.js

@@ -52,13 +52,34 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
             relationship.push(record);
         pendingHasMany.splice(0);
     }
+    // FK-based inverse hasMany wiring — when a child record is created with a
+    // foreign-key field (e.g. `owner: 'owner-1'` on an animal), find any parent
+    // whose hasMany registry targets this model and push the child into the
+    // parent's shared array.  This covers edge cases where the child is created
+    // in a separate async frame without a belongsTo handler firing.
+    const hasManyReg = getHasManyRegistry();
+    if (hasManyReg) {
+        for (const [parentModelName, targetMap] of hasManyReg) {
+            const childArrayMap = targetMap.get(modelName);
+            if (!childArrayMap)
+                continue;
+            // Check if rawData contains a FK field matching the parent model name
+            const fkValue = rawData[parentModelName];
+            if (fkValue === undefined || fkValue === null)
+                continue;
+            const parentArray = childArrayMap.get(fkValue);
+            if (parentArray && !parentArray.includes(record)) {
+                parentArray.push(record);
+            }
+        }
+    }
     // Fulfill pending belongsTo relationships
     const pendingBelongsToQueue = getPendingBelongsToRegistry();
     const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
     const pendingBelongsTo = Array.isArray(pendingBelongsToRaw) ? pendingBelongsToRaw : undefined;
     if (pendingBelongsTo) {
         const belongsToReg = getBelongsToRegistry();
-        const hasManyReg = getHasManyRegistry();
+        const pendingHasManyReg = getHasManyRegistry();
         for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
             // Update the belongsTo relationship on the source record
             sourceRecord.__relationships[relationshipKey] = record;
@@ -72,7 +93,7 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
                 }
             }
             // Wire inverse hasMany if it exists
-            const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+            const inverseHasMany = pendingHasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
             if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
                 inverseHasMany.push(sourceRecord);
             }
@@ -83,14 +104,24 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
     // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
     const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
     if (shouldPersist) {
+        // Capture ID before persist — SQL adapters re-key pending IDs to real DB IDs,
+        // but relationship registries were keyed with this original ID
+        const registryId = record.id;
         const response = { data: { id: record.id } };
-        orm.sqlDb.persist('create', modelName, { rawData }, response).catch((err) => {
+        orm.sqlDb.persist('create', modelName, { rawData }, response)
+            .catch((err) => {
             orm.emitPersistError({
                 operation: 'create',
                 modelName,
                 recordId: record.id,
                 error: err instanceof Error ? err : new Error(String(err)),
             });
+        })
+            .finally(() => {
+            // Evict non-memory records after persist to prevent unbounded heap growth (stonyx#81)
+            if (store._memoryResolver && !store._memoryResolver(modelName)) {
+                store.evictRecord(modelName, record.id, registryId);
+            }
         });
     }
     return record;

package/dist/postgres/connection.d.ts

@@ -6,6 +6,7 @@ interface PgConfig {
     password: string;
     database: string;
     connectionLimit: number;
+    [key: string]: unknown;
 }
 /**
  * Create or return the singleton pg Pool.

package/dist/postgres/connection.js

@@ -7,15 +7,17 @@ export async function getPool(pgConfig, extensions = ['vector']) {
     if (pool)
         return pool;
     const { default: pg } = await import('pg');
+    const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, ...poolOpts } = pgConfig;
     pool = new pg.Pool({
-        host: pgConfig.host,
-        port: pgConfig.port,
-        user: pgConfig.user,
-        password: pgConfig.password,
-        database: pgConfig.database,
-        max: pgConfig.connectionLimit,
+        host,
+        port,
+        user,
+        password,
+        database,
+        max: connectionLimit,
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 10000,
+        ...poolOpts,
     });
     // Enable requested PostgreSQL extensions
     for (const ext of extensions) {

package/dist/relationships.js

@@ -38,4 +38,4 @@ export function getPendingRegistry() {
 export function getPendingBelongsToRegistry() {
     return relationships.get('pendingBelongsTo');
 }
-export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending'];
+export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending', 'pendingBelongsTo'];

package/dist/serializer.js

@@ -79,8 +79,33 @@ export default class Serializer {
                 // Pass relationship key name to handler for pending fulfillment
                 const handlerOptions = { ...options, _relationshipKey: key };
                 const childRecord = handler(record, data, handlerOptions);
-                rec[key] = childRecord;
-                relatedRecords[key] = childRecord;
+                // hasMany relationships use a getter so format()/toJSON() always read
+                // the live registry array instead of a stale snapshot captured at
+                // serialization time.  This is critical when child records are created
+                // in a later async frame — the belongsTo inverse wiring pushes into
+                // the shared registry array, and the getter ensures the parent sees it.
+                const isHasMany = handler.__relationshipType === 'hasMany';
+                if (isHasMany) {
+                    // `childRecord` IS the shared registry array — define a getter that
+                    // always dereferences through the same array reference.
+                    const registryArray = childRecord;
+                    Object.defineProperty(rec, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { relatedRecords[key] = v; }
+                    });
+                    Object.defineProperty(relatedRecords, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { Object.defineProperty(relatedRecords, key, { value: v, writable: true, enumerable: true, configurable: true }); }
+                    });
+                }
+                else {
+                    rec[key] = childRecord;
+                    relatedRecords[key] = childRecord;
+                }
                 continue;
             }
             // Aggregate property handling — use the rawData value, not the aggregate descriptor

package/dist/store.d.ts

@@ -46,6 +46,16 @@ export default class Store {
     private _isMemoryModel;
     set(key: string, value: Map<number | string, unknown>): void;
     remove(key: string, id?: number | string): void;
+    /**
+     * Evict a record from the store with full relationship registry cleanup,
+     * WITHOUT calling record.clean(). This preserves the caller's reference
+     * to the returned record (used by memory:false post-persist eviction).
+     *
+     * @param registryId - The ID used when the record's relationships were
+     *   registered. For SQL models with pending IDs, this is the original
+     *   negative pending ID (before the adapter re-keyed to the real DB ID).
+     */
+    evictRecord(modelName: string, id: unknown, registryId?: unknown): void;
     unloadRecord(model: string, id: unknown, options?: UnloadOptions): void;
     unloadAllRecords(model: string, options?: UnloadOptions): void;
     private _removeFromHasManyArrays;

package/dist/store.js

@@ -1,5 +1,5 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 function isStoreRecord(value) {
     return typeof value === 'object' && value !== null && '__data' in value;
@@ -127,6 +127,40 @@ export default class Store {
             return this.unloadRecord(key, id);
         this.unloadAllRecords(key);
     }
+    /**
+     * Evict a record from the store with full relationship registry cleanup,
+     * WITHOUT calling record.clean(). This preserves the caller's reference
+     * to the returned record (used by memory:false post-persist eviction).
+     *
+     * @param registryId - The ID used when the record's relationships were
+     *   registered. For SQL models with pending IDs, this is the original
+     *   negative pending ID (before the adapter re-keyed to the real DB ID).
+     */
+    evictRecord(modelName, id, registryId) {
+        const modelStore = this.data.get(modelName);
+        if (!modelStore)
+            return;
+        if (typeof id !== 'string' && typeof id !== 'number')
+            return;
+        const raw = modelStore.get(id);
+        if (!raw || !isStoreRecord(raw))
+            return;
+        const visited = new Set([`${modelName}:${id}`]);
+        // Remove from hasMany arrays and nullify belongsTo references using current ID
+        // (the adapter updates record.id, so value-based matches need the current ID)
+        this._removeFromHasManyArrays(modelName, id, visited);
+        this._nullifyBelongsToReferences(modelName, id, visited);
+        // Clean up relationship registry entries using the registry key
+        // (belongsTo/hasMany registries were keyed by the ID at registration time,
+        // which may differ from the current ID if SQL persist re-keyed the record)
+        const cleanupId = registryId ?? id;
+        this._cleanupRelationshipRegistries(modelName, cleanupId);
+        // If registryId differs from id, also clean with current id as safety net
+        if (registryId !== undefined && registryId !== id) {
+            this._cleanupRelationshipRegistries(modelName, id);
+        }
+        modelStore.delete(id);
+    }
     unloadRecord(model, id, options = {}) {
         const modelStore = this.data.get(model);
         if (!modelStore) {
@@ -230,6 +264,31 @@ export default class Store {
         const pendingMap = getPendingRegistry().get(modelName);
         if (pendingMap)
             pendingMap.delete(recordId);
+        // Clean pendingBelongsTo entries in both directions
+        const pendingBelongsToMap = getPendingBelongsToRegistry();
+        if (pendingBelongsToMap) {
+            // Direction 1: evicted record was the TARGET others were waiting for
+            const targetEntries = pendingBelongsToMap.get(modelName);
+            if (targetEntries)
+                targetEntries.delete(recordId);
+            // Direction 2: evicted record was the SOURCE with unresolved forward-references
+            for (const [, targetIdMap] of pendingBelongsToMap) {
+                for (const [targetId, entries] of targetIdMap) {
+                    if (!Array.isArray(entries))
+                        continue;
+                    const filtered = entries.filter((e) => {
+                        const entry = e;
+                        return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+                    });
+                    if (filtered.length === 0) {
+                        targetIdMap.delete(targetId);
+                    }
+                    else if (filtered.length < entries.length) {
+                        targetIdMap.set(targetId, filtered);
+                    }
+                }
+            }
+        }
     }
     /**
      * Extracts hasMany and non-bidirectional belongsTo children from a record

package/dist/types/orm-types.d.ts

@@ -42,6 +42,11 @@ export interface OrmRestServerConfig {
     route: string;
     metaRoute: boolean;
 }
+export interface OrmDynamoDBConfig {
+    region?: string;
+    endpoint?: string;
+    [key: string]: unknown;
+}
 export interface OrmSection {
     db: OrmDbConfig;
     paths: OrmPaths;
@@ -49,6 +54,9 @@ export interface OrmSection {
     mysql?: OrmMysqlConfig;
     postgres?: OrmPostgresConfig;
     timescale?: OrmPostgresConfig;
+    dynamodb?: OrmDynamoDBConfig;
+    logColor?: string;
+    logMethod?: string;
     [key: string]: unknown;
 }
 export interface OrmConfig {

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.8",
+  "version": "0.3.2-beta.80",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,16 +61,24 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.38",
-    "@stonyx/events": "0.1.1-beta.9",
-    "stonyx": "0.2.3-beta.53"
+    "@stonyx/cron": "0.2.1-beta.70",
+    "@stonyx/events": "0.1.1-beta.51",
+    "stonyx": "0.2.3-beta.68"
   },
   "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
     "@stonyx/rest-server": ">=0.2.1-beta.14",
     "mysql2": "^3.0.0",
     "pg": "^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     },
@@ -82,8 +90,8 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.30",
-    "@stonyx/utils": "0.2.3-beta.23",
+    "@stonyx/rest-server": "0.2.1-beta.71",
+    "@stonyx/utils": "0.2.3-beta.25",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
@@ -95,6 +103,7 @@
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'",
+    "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/commands.ts

@@ -28,6 +28,13 @@ const commands: Record<string, Command> = {
     description: 'Generate a MySQL migration from current model schemas',
     bootstrap: true,
     run: async (args) => {
+      const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const description = args?.join(' ') || 'migration';
       const { generateMigration } = await import('./mysql/migration-generator.js');
       const result = await generateMigration(description);
@@ -39,6 +46,25 @@ const commands: Record<string, Command> = {
       }
     }
   },
+  'db:sync': {
+    description: 'Provision DynamoDB tables and GSIs from current model schemas',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+
+      if (!config.orm.dynamodb) {
+        console.error('DynamoDB is not configured. Set DYNAMODB_REGION (and optionally DYNAMODB_ENDPOINT) to enable DynamoDB mode.');
+        process.exit(1);
+      }
+
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      const db = new DynamoDBDB();
+      await db.init();
+      await db.startup();
+      await db.shutdown();
+      console.log('DynamoDB tables synced successfully.');
+    }
+  },
   'db:migrate': {
     description: 'Apply pending MySQL migrations',
     bootstrap: true,
@@ -46,6 +72,11 @@ const commands: Record<string, Command> = {
       const config = (await import('stonyx/config')).default;
       const mysqlConfig = config.orm.mysql;
 
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       if (!mysqlConfig) {
         console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
         process.exit(1);
@@ -92,6 +123,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not support migration rollback. Manage table changes via the AWS console or db:sync.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {
@@ -138,6 +175,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {

package/src/dynamodb/connection.ts

@@ -0,0 +1,49 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+
+export interface DynamoDBConfig {
+  region?: string;
+  endpoint?: string;
+  [key: string]: unknown;
+}
+
+// Type aliases — declared loose so we don't need to import the real SDK types
+// at compile time (they're optional peer deps).
+export type DocumentClient = {
+  send(command: unknown): Promise<unknown>;
+};
+
+export type DynamoDBClientConstructor = new (options: unknown) => { config: unknown };
+export type DocumentClientFromFn = { from(client: unknown): DocumentClient };
+
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export async function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient> {
+  const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb' as string) as {
+    DynamoDBClient: DynamoDBClientConstructor;
+  };
+  const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb' as string) as {
+    DynamoDBDocumentClient: DocumentClientFromFn;
+  };
+
+  const clientOptions: Record<string, unknown> = {};
+  if (dbConfig.region) clientOptions.region = dbConfig.region;
+  if (dbConfig.endpoint) clientOptions.endpoint = dbConfig.endpoint;
+
+  const rawClient = new DynamoDBClient(clientOptions);
+  return DynamoDBDocumentClient.from(rawClient);
+}
+
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export function destroyDocumentClient(_client: DocumentClient | null): null {
+  return null;
+}