@stonyx/orm 0.3.2-beta.16 → 0.3.2-beta.160

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 {};