@stonyx/orm 0.3.2-beta.65 → 0.3.2-beta.67

package/README.md

@@ -13,7 +13,7 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
 - **Serializers**: Map raw data into model-friendly structures, including nested properties.
 - **Transforms**: Apply custom transformations on data values automatically.
-- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL for production workloads.
+- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL/PostgreSQL/TimescaleDB/DynamoDB for production workloads.
 - **REST Server Integration**: Automatic route setup with customizable access control.
 - **Lifecycle Hooks**: Middleware-based before/after hooks for validation, authorization, side effects, and auditing.
 
@@ -65,13 +65,16 @@ const {
   MYSQL_DATABASE,
   MYSQL_CONNECTION_LIMIT,
   MYSQL_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
   orm: {
     logColor: 'white',
     logMethod: 'db',
-    
+
     db: {
       autosave: DB_AUTO_SAVE ?? 'false',
       file: DB_FILE ?? 'db.json',
@@ -96,6 +99,11 @@ export default {
       migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
       migrationsTable: '__migrations',
     } : undefined,
+    dynamodb: DYNAMODB_REGION ? {
+      region: DYNAMODB_REGION,
+      endpoint: DYNAMODB_ENDPOINT,          // optional, for DynamoDB Local
+      tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
+    } : undefined,
     restServer: {
       enabled: ORM_USE_REST_SERVER ?? 'true',
       route: ORM_REST_ROUTE ?? '/'
@@ -243,6 +251,31 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 | `stonyx db:migrate` | Apply pending migrations |
 | `stonyx db:migrate:rollback` | Rollback the most recent migration |
 | `stonyx db:migrate:status` | Show migration status |
+| `stonyx db:sync` | Sync DynamoDB table definitions to match current model schemas |
+
+### DynamoDB Mode
+
+Set the `DYNAMODB_REGION` environment variable to enable DynamoDB persistence. Tables are created with PAY_PER_REQUEST (on-demand) billing. Global Secondary Indexes (GSIs) are auto-provisioned at startup based on model `belongsTo` relationships — each FK column gets a GSI. `findAll()` with conditions routes to a GSI Query when the condition key matches a GSI partition key; non-indexed attribute conditions fall back to Scan + FilterExpression (expensive for large tables). ULID generation replaces auto-increment for numeric-ID models.
+
+```javascript
+dynamodb: {
+  region: 'us-east-1',
+  endpoint: 'http://localhost:8000', // optional, for DynamoDB Local
+  tablePrefix: 'myapp-',            // optional table name prefix
+}
+```
+
+Environment variables:
+
+* `DYNAMODB_REGION`: AWS region for DynamoDB (e.g., `'us-east-1'`).
+* `DYNAMODB_ENDPOINT`: Optional custom endpoint URL, useful for DynamoDB Local during development.
+* `DYNAMODB_TABLE_PREFIX`: Optional prefix prepended to all table names (e.g., `'myapp-'` yields `'myapp-animals'`).
+
+**Peer dependencies:** `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` must be installed when using the DynamoDB driver. The AWS SDK is dynamically imported and only loaded when the DynamoDB driver is selected.
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
 
 ### Running MySQL Tests
 

package/config/environment.js

@@ -33,6 +33,9 @@ const {
   TIMESCALE_DATABASE,
   TIMESCALE_CONNECTION_LIMIT,
   TIMESCALE_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
@@ -84,6 +87,11 @@ export default {
     migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
     migrationsTable: '__migrations',
   } : undefined,
+  dynamodb: DYNAMODB_REGION ? {
+    region: DYNAMODB_REGION,
+    endpoint: DYNAMODB_ENDPOINT || undefined,
+    tablePrefix: DYNAMODB_TABLE_PREFIX || '',
+  } : undefined,
   restServer: {
     enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
     route: ORM_REST_ROUTE ?? '/',

package/dist/commands.js

@@ -20,6 +20,11 @@ const commands = {
         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);
@@ -31,12 +36,33 @@ const commands = {
             }
         }
     },
+    '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,
         run: async () => {
             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);
@@ -75,6 +101,10 @@ const commands = {
         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) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
@@ -113,6 +143,10 @@ const commands = {
         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) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');

package/dist/dynamodb/connection.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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;
+}
+export type DocumentClient = {
+    send(command: unknown): Promise<unknown>;
+};
+export type DocumentClientConstructor = new (options: {
+    client: unknown;
+}) => DocumentClient;
+export type DynamoDBClientConstructor = new (options: unknown) => unknown;
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export declare function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient>;
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export declare function destroyDocumentClient(_client: DocumentClient | null): null;

package/dist/dynamodb/connection.js

@@ -0,0 +1,28 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export async function createDocumentClient(dbConfig) {
+    const { DynamoDB } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocument } = await import('@aws-sdk/lib-dynamodb');
+    const clientOptions = {};
+    if (dbConfig.region)
+        clientOptions.region = dbConfig.region;
+    if (dbConfig.endpoint)
+        clientOptions.endpoint = dbConfig.endpoint;
+    const rawClient = new DynamoDB(clientOptions);
+    return new DynamoDBDocument({ client: 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) {
+    return null;
+}

package/dist/dynamodb/dynamodb-db.d.ts

@@ -0,0 +1,131 @@
+/**
+ * DynamoDB driver implementing the SqlDb PAL contract.
+ *
+ * Drop-in replacement for PostgresDB / MysqlDB — zero ORM core changes.
+ * Selected via config.orm.dynamodb.
+ */
+import { createDocumentClient, destroyDocumentClient } from './connection.js';
+import type { DocumentClient, DynamoDBConfig } from './connection.js';
+import { buildPutItem, buildGetItem, buildUpdateItem, buildDeleteItem, buildScan, buildQuery } from './operation-builder.js';
+import { introspectModels, getTopologicalOrder } from '../postgres/schema-introspector.js';
+import { getDynamoKeyType } from './type-map.js';
+import { store } from '@stonyx/orm';
+import { createRecord } from '../manage-record.js';
+import { getPluralName } from '../plural-registry.js';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import type { OrmRecord } from '../types/orm-types.js';
+/**
+ * Load the DynamoDB DocumentClient command constructors via dynamic import.
+ * Returns a frozen object so it can be cached in deps.
+ */
+export declare function loadDocClientCommands(): Promise<{
+    PutCommand: new (params: unknown) => unknown;
+    GetCommand: new (params: unknown) => unknown;
+    UpdateCommand: new (params: unknown) => unknown;
+    DeleteCommand: new (params: unknown) => unknown;
+    ScanCommand: new (params: unknown) => unknown;
+    QueryCommand: new (params: unknown) => unknown;
+}>;
+export declare function loadTableCommands(): Promise<{
+    DynamoDBClient: new (opts: unknown) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    DescribeTableCommand: new (params: unknown) => unknown;
+    CreateTableCommand: new (params: unknown) => unknown;
+    UpdateTableCommand: new (params: unknown) => unknown;
+}>;
+interface PersistContext {
+    record?: OrmRecord;
+    recordId?: unknown;
+    oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
+}
+interface PersistResponse {
+    data?: {
+        id?: unknown;
+    };
+}
+/** Minimal Orm module shape needed at runtime — avoids circular import at top-level. */
+interface OrmModule {
+    default: {
+        instance: {
+            getRecordClasses(name: string): {
+                modelClass: {
+                    memory?: boolean;
+                };
+            };
+            isView?(name: string): boolean;
+        };
+    };
+}
+export interface DynamoDBDeps {
+    createDocumentClient: typeof createDocumentClient;
+    destroyDocumentClient: typeof destroyDocumentClient;
+    loadDocClientCommands: typeof loadDocClientCommands;
+    loadTableCommands: typeof loadTableCommands;
+    buildPutItem: typeof buildPutItem;
+    buildGetItem: typeof buildGetItem;
+    buildUpdateItem: typeof buildUpdateItem;
+    buildDeleteItem: typeof buildDeleteItem;
+    buildScan: typeof buildScan;
+    buildQuery: typeof buildQuery;
+    introspectModels: typeof introspectModels;
+    getTopologicalOrder: typeof getTopologicalOrder;
+    getDynamoKeyType: typeof getDynamoKeyType;
+    createRecord: typeof createRecord;
+    store: typeof store;
+    getPluralName: typeof getPluralName;
+    config: typeof config;
+    log: typeof log;
+    /** Injected for testing — import('@stonyx/orm') replacement */
+    _importOrm?: () => Promise<OrmModule>;
+    [key: string]: unknown;
+}
+export default class DynamoDBDB {
+    static instance: DynamoDBDB | undefined;
+    deps: DynamoDBDeps;
+    client: DocumentClient | null;
+    dbConfig: DynamoDBConfig;
+    /** GSI registry built during init from model introspection. */
+    private _gsiRegistry;
+    constructor(deps?: Partial<DynamoDBDeps>);
+    private requireClient;
+    /** Resolve Orm singleton — falls back to real import in production. */
+    private _getOrm;
+    init(): Promise<void>;
+    /**
+     * For each model, DescribeTable — CreateTable if missing (with GSIs, PAY_PER_REQUEST).
+     * For existing tables, check for missing GSIs and UpdateTable + poll for ACTIVE.
+     */
+    startup(): Promise<void>;
+    shutdown(): Promise<void>;
+    persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
+    findRecord(modelName: string, id: unknown): Promise<OrmRecord | undefined>;
+    findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;
+    loadMemoryRecords(): Promise<void>;
+    private _persistCreate;
+    private _persistUpdate;
+    private _persistDelete;
+    private _paginatedScan;
+    private _paginatedQuery;
+    /**
+     * Build the GSI registry from model introspection.
+     * Registry: modelName → attrName → gsiName
+     *
+     * FK columns (belonging to belongsTo relationships) get a GSI automatically.
+     */
+    private _buildGsiRegistry;
+    /**
+     * Find a GSI that can serve the given conditions.
+     */
+    private _findGsiMatch;
+    private _buildAttributeDefinitions;
+    private _buildGsiDefinitions;
+    private _waitForTableActive;
+    private _itemToRawData;
+    private _recordToItem;
+    private _evictIfNotMemory;
+    loadAllRecords(): Promise<void>;
+}
+export {};