@stonyx/orm 0.3.2-beta.33 → 0.3.2-beta.330

package/config/environment.js

@@ -1,12 +1,111 @@
-// project configuration, override-able by listed environment variables
-const {
-  DEBUG,
-  NODE_ENV,
-} = process.env;
-
-const environment = NODE_ENV ?? 'development';
-
-export default {
-  environment,
-  debug: DEBUG ?? environment === 'development',
-}
+const {
+  ORM_ACCESS_PATH,
+  ORM_MODEL_PATH,
+  ORM_REST_ROUTE,
+  ORM_SERIALIZER_PATH,
+  ORM_TRANSFORM_PATH,
+  ORM_VIEW_PATH,
+  ORM_USE_REST_SERVER,
+  DB_AUTO_SAVE,
+  DB_FILE,
+  DB_MODE,
+  DB_DIRECTORY,
+  DB_SCHEMA_PATH,
+  DB_SAVE_INTERVAL,
+  MYSQL_HOST,
+  MYSQL_PORT,
+  MYSQL_USER,
+  MYSQL_PASSWORD,
+  MYSQL_DATABASE,
+  MYSQL_CONNECTION_LIMIT,
+  MYSQL_MIGRATIONS_DIR,
+  MYSQL_WRITE_BATCH_SIZE,
+  MYSQL_WRITE_QUEUE_LIMIT,
+  PG_HOST,
+  PG_PORT,
+  PG_USER,
+  PG_PASSWORD,
+  PG_DATABASE,
+  PG_CONNECTION_LIMIT,
+  PG_MIGRATIONS_DIR,
+  PG_WRITE_BATCH_SIZE,
+  PG_WRITE_QUEUE_LIMIT,
+  TIMESCALE_HOST,
+  TIMESCALE_PORT,
+  TIMESCALE_USER,
+  TIMESCALE_PASSWORD,
+  TIMESCALE_DATABASE,
+  TIMESCALE_CONNECTION_LIMIT,
+  TIMESCALE_MIGRATIONS_DIR,
+  TIMESCALE_WRITE_BATCH_SIZE,
+  TIMESCALE_WRITE_QUEUE_LIMIT,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
+} = process.env;
+
+export default {
+  logColor: 'white',
+  logMethod: 'db',
+  
+  db: {
+    autosave: DB_AUTO_SAVE ?? 'false', // 'true' (cron interval), 'false' (disabled), 'onUpdate' (save after each write op)
+    file: DB_FILE ?? 'db.json',
+    mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
+    directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
+    saveInterval: DB_SAVE_INTERVAL ?? 60 * 60, // 1 hour
+    schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
+  },
+  paths: {
+    access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
+    model: ORM_MODEL_PATH ?? './models',
+    serializer: ORM_SERIALIZER_PATH ?? './serializers',
+    transform: ORM_TRANSFORM_PATH ?? './transforms',
+    view: ORM_VIEW_PATH ?? './views'
+  },
+  mysql: MYSQL_HOST ? {
+    host: MYSQL_HOST ?? 'localhost',
+    port: parseInt(MYSQL_PORT ?? '3306'),
+    user: MYSQL_USER ?? 'root',
+    password: MYSQL_PASSWORD ?? '',
+    database: MYSQL_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+    writeBatchSize: parseInt(MYSQL_WRITE_BATCH_SIZE ?? '500'),
+    writeQueueLimit: parseInt(MYSQL_WRITE_QUEUE_LIMIT ?? '10000'),
+  } : undefined,
+  postgres: PG_HOST ? {
+    host: PG_HOST ?? 'localhost',
+    port: parseInt(PG_PORT ?? '5432'),
+    user: PG_USER ?? 'postgres',
+    password: PG_PASSWORD ?? '',
+    database: PG_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(PG_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+    writeBatchSize: parseInt(PG_WRITE_BATCH_SIZE ?? '500'),
+    writeQueueLimit: parseInt(PG_WRITE_QUEUE_LIMIT ?? '10000'),
+  } : undefined,
+  timescale: TIMESCALE_HOST ? {
+    host: TIMESCALE_HOST ?? 'localhost',
+    port: parseInt(TIMESCALE_PORT ?? '5432'),
+    user: TIMESCALE_USER ?? 'postgres',
+    password: TIMESCALE_PASSWORD ?? '',
+    database: TIMESCALE_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+    writeBatchSize: parseInt(TIMESCALE_WRITE_BATCH_SIZE ?? '500'),
+    writeQueueLimit: parseInt(TIMESCALE_WRITE_QUEUE_LIMIT ?? '10000'),
+  } : 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/column-conversion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export declare function convertRow(row: Record<string, unknown>, columns: Record<string, string>, rule: ColumnRule): Record<string, unknown>;

package/dist/column-conversion.js

@@ -0,0 +1,34 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(row, columns, rule) {
+    const converted = {};
+    for (const [col, value] of Object.entries(row)) {
+        // `Object.hasOwn`, not `columns[col]`: a column named `toString` or
+        // `constructor` would otherwise reach the rule with a function as its
+        // "declared type". Inert for the shipped Postgres rule (strict equality
+        // against 'JSONB'), but `ColumnRule` is the extension point other drivers
+        // write against, and the obvious `if (columnType)` rule would invert.
+        converted[col] = rule(value, Object.hasOwn(columns, col) ? columns[col] : undefined);
+    }
+    return converted;
+}

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,31 @@
+/**
+ * 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;
+    tablePrefix?: string;
+    [key: string]: unknown;
+}
+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 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 { DynamoDBClient } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocumentClient } = 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 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) {
+    return null;
+}

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

@@ -0,0 +1,142 @@
+/**
+ * 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;
+    private _resolveTableName;
+    /** 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>;
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
+    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 {};