@arcaelas/dynamite 1.0.15 → 1.0.18

package/package.json

@@ -47,7 +47,45 @@
     "docs": "mkdocs gh-deploy --force",
     "deploy": "npm version patch && npm publish --access=public",
     "prepublishOnly": "yarn build",
-    "postpublish": "find src -type f \\( -name '*.js' -o -name '*.d.ts' -o -name '*.map' \\) -delete"
+    "postpublish": "find src -type f \\( -name '*.js' -o -name '*.d.ts' -o -name '*.map' \\) -delete",
+    "test": "yarn test:db:start && yarn test:run; yarn test:db:stop",
+    "test:run": "node --expose-gc ./node_modules/.bin/jest src/index.test.ts --runInBand --verbose",
+    "test:watch": "yarn test:db:start && node --expose-gc ./node_modules/.bin/jest src/index.test.ts --watch --runInBand",
+    "test:db:start": "docker run -d -p 8000:8000 --name dynamite-test-db amazon/dynamodb-local -jar DynamoDBLocal.jar -sharedDb || echo 'DynamoDB ya está corriendo'",
+    "test:db:stop": "docker stop dynamite-test-db && docker rm dynamite-test-db || true",
+    "test:db:clean": "docker stop dynamite-test-db && docker rm dynamite-test-db; docker run -d -p 8000:8000 --name dynamite-test-db amazon/dynamodb-local -jar DynamoDBLocal.jar -sharedDb"
   },
-  "version": "1.0.15"
+  "version": "1.0.18",
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "moduleNameMapper": {
+      "^~/(.*)$": "<rootDir>/src/$1",
+      "^@type/(.*)$": "<rootDir>/src/@types/$1"
+    },
+    "transform": {
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "tsconfig": {
+            "experimentalDecorators": true,
+            "emitDecoratorMetadata": true,
+            "esModuleInterop": true,
+            "target": "ES2022",
+            "module": "commonjs"
+          }
+        }
+      ]
+    },
+    "testTimeout": 60000,
+    "maxWorkers": 1,
+    "detectOpenHandles": false,
+    "forceExit": true
+  }
 }

package/src/@types/index.d.ts

@@ -0,0 +1,102 @@
+export declare const HasManyBrand: unique symbol;
+export declare const BelongsToBrand: unique symbol;
+export declare const HasOneBrand: unique symbol;
+export declare const NonAttributeBrand: unique symbol;
+export declare const CreationOptionalBrand: unique symbol;
+export type HasMany<T> = T[] & {
+    [HasManyBrand]?: true;
+};
+export type BelongsTo<T> = (T | null) & {
+    [BelongsToBrand]?: true;
+};
+export type HasOne<T> = (T | null) & {
+    [HasOneBrand]?: true;
+};
+export type NonAttribute<T> = T & {
+    [NonAttributeBrand]?: true;
+};
+export type CreationOptional<T> = T & {
+    [CreationOptionalBrand]?: true;
+};
+export type InferAttributes<T> = {
+    [K in keyof T as T[K] extends (...args: any[]) => any ? never : T[K] extends {
+        [HasManyBrand]?: true;
+    } ? never : T[K] extends {
+        [BelongsToBrand]?: true;
+    } ? never : T[K] extends {
+        [HasOneBrand]?: true;
+    } ? never : T[K] extends {
+        [NonAttributeBrand]?: true;
+    } ? never : K]: T[K];
+};
+export type FilterableAttributes<T> = {
+    [K in keyof InferAttributes<T>]: InferAttributes<T>[K];
+};
+export type WhereOptions<T> = {
+    where?: Partial<FilterableAttributes<T>>;
+    skip?: number;
+    limit?: number;
+    order?: "ASC" | "DESC";
+    attributes?: (keyof FilterableAttributes<T>)[];
+    include?: {
+        [K in keyof T]?: T[K] extends HasMany<any> | BelongsTo<any> | HasOne<any> ? IncludeRelationOptions | true : never;
+    };
+};
+/** Filtros de query sin cláusula where */
+export type QueryFilters<T> = Omit<WhereOptions<T>, "where">;
+/** @deprecated Usa QueryFilters */
+export type WhereOptionsWithoutWhere<T> = QueryFilters<T>;
+export type QueryOperator = "=" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "contains" | "begins-with";
+/** Entrada de validador con soporte lazy */
+export interface ValidatorEntry {
+    fn: (value: any) => boolean | string;
+    lazy?: boolean;
+}
+export interface Column {
+    name: string;
+    index?: true;
+    indexSort?: true;
+    primaryKey?: boolean;
+    nullable?: boolean;
+    unique?: true;
+    createdAt?: boolean;
+    updatedAt?: boolean;
+    softDelete?: boolean;
+    lazy_validators?: ((value: any) => boolean | string)[];
+    relation?: RelationMetadata;
+}
+export interface RelationMetadata {
+    type: "hasMany" | "belongsTo" | "hasOne";
+    targetModel: () => any;
+    foreignKey: string;
+    localKey?: string;
+}
+export interface WrapperEntry {
+    name: string;
+    columns: Map<string | symbol, Column>;
+    relations: Map<string | symbol, RelationMetadata>;
+}
+/** Alias para WrapperEntry (usado internamente con SCHEMA symbol) */
+export type SchemaEntry = WrapperEntry;
+export type IncludeRelationOptions = {
+    where?: Record<string, any>;
+    attributes?: string[];
+    order?: "ASC" | "DESC";
+    skip?: number;
+    limit?: number;
+    include?: Record<string, IncludeRelationOptions | true>;
+};
+/** Opciones de query para métodos where(), first(), last(), etc. */
+export type QueryOptions<T> = {
+    order?: "ASC" | "DESC";
+    skip?: number;
+    limit?: number;
+    attributes?: (keyof InferAttributes<T>)[];
+    include?: {
+        [K in keyof T]?: T[K] extends HasMany<any> | BelongsTo<any> | HasOne<any> ? IncludeRelationOptions | true : never;
+    };
+};
+/** @deprecated Usa QueryOptions */
+export type WhereQueryOptions<T> = QueryOptions<T>;
+export type Mutate = (value: any) => any;
+export type Validate = (value: any) => boolean | string;

package/src/@types/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/*
+@file index.ts
+@descripcion Tipos públicos de Dynamite ORM
+@autor Miguel Alejandro
+@fecha 2025-08-07
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/src/core/client.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file client.ts
+ * @description Centralized Dynamite client with multi-client support and table sync
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+import { DynamoDBClient, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";
+/**
+ * Configuration for Dynamite client initialization
+ */
+export interface DynamiteConfig extends DynamoDBClientConfig {
+    tables: Array<new (...args: any[]) => any>;
+}
+/**
+ * Centralized Dynamite client for managing DynamoDB connections and table synchronization
+ */
+export declare class Dynamite {
+    private client;
+    private tables;
+    private connected;
+    private synced;
+    /**
+     * Initialize Dynamite client with configuration
+     * @param config Dynamite client configuration
+     */
+    constructor(config: DynamiteConfig);
+    /**
+     * Synchronize all declared tables and their GSIs
+     */
+    sync(): Promise<void>;
+    /**
+     * Connect the client for Table operations
+     */
+    connect(): void;
+    /**
+     * Get the underlying DynamoDB client
+     */
+    getClient(): DynamoDBClient;
+    /**
+     * Check if client is connected and tables are synced
+     */
+    isReady(): boolean;
+    /**
+     * Disconnect and cleanup DynamoDB client
+     */
+    disconnect(): void;
+    /**
+     * Ejecutar operaciones en una transacción atómica.
+     * Si cualquier operación falla, todas se revierten automáticamente.
+     *
+     * @param callback Función que recibe el contexto de transacción
+     * @returns Resultado del callback
+     *
+     * @example
+     * await dynamite.tx(async (tx) => {
+     *   const user = await User.create({ name: "Juan" }, tx);
+     *   await Order.create({ user_id: user.id, total: 100 }, tx);
+     * });
+     */
+    tx<R>(callback: (tx: TransactionContext) => Promise<R>): Promise<R>;
+    /**
+     * Create table with automatic GSI detection and creation
+     * @param ctor Table class constructor
+     */
+    private createTableWithGSI;
+}
+/**
+ * Set global client for Table class operations
+ * @param client DynamoDB client instance
+ */
+export declare const setGlobalClient: (client: DynamoDBClient) => void;
+/**
+ * Get global client for Table class operations
+ */
+export declare const getGlobalClient: () => DynamoDBClient;
+/**
+ * Check if global client is available
+ */
+export declare const hasGlobalClient: () => boolean;
+/**
+ * Require global client for Table operations (throws if not available)
+ */
+export declare const requireClient: () => DynamoDBClient;
+/**
+ * Contexto de transacción para agrupar operaciones atómicas.
+ * Máximo 25 operaciones por transacción (límite DynamoDB).
+ */
+export declare class TransactionContext {
+    private operations;
+    private client;
+    constructor(client: DynamoDBClient);
+    /**
+     * Agregar operación Put a la transacción
+     */
+    addPut(table_name: string, item: Record<string, any>): void;
+    /**
+     * Agregar operación Delete a la transacción
+     */
+    addDelete(table_name: string, key: Record<string, any>): void;
+    /**
+     * Confirmar todas las operaciones de la transacción.
+     * Si alguna falla, todas se revierten.
+     */
+    commit(): Promise<void>;
+}

package/src/core/client.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * @file client.ts
+ * @description Centralized Dynamite client with multi-client support and table sync
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-27
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionContext = exports.requireClient = exports.hasGlobalClient = exports.getGlobalClient = exports.setGlobalClient = exports.Dynamite = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const decorator_1 = require("./decorator");
+/**
+ * Centralized Dynamite client for managing DynamoDB connections and table synchronization
+ */
+class Dynamite {
+    /**
+     * Initialize Dynamite client with configuration
+     * @param config Dynamite client configuration
+     */
+    constructor(config) {
+        this.connected = false;
+        this.synced = false;
+        const { tables, ...clientConfig } = config;
+        this.client = new client_dynamodb_1.DynamoDBClient(clientConfig);
+        this.tables = tables;
+    }
+    /**
+     * Synchronize all declared tables and their GSIs
+     */
+    async sync() {
+        if (this.synced && this.connected)
+            return;
+        await Promise.all(this.tables.map((table) => this.createTableWithGSI(table)));
+        this.synced = true;
+    }
+    /**
+     * Connect the client for Table operations
+     */
+    connect() {
+        if (this.connected)
+            return;
+        (0, exports.setGlobalClient)(this.client);
+        this.connected = true;
+    }
+    /**
+     * Get the underlying DynamoDB client
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Check if client is connected and tables are synced
+     */
+    isReady() {
+        return this.connected && this.synced;
+    }
+    /**
+     * Disconnect and cleanup DynamoDB client
+     */
+    disconnect() {
+        try {
+            this.client.destroy();
+            this.connected = false;
+            this.synced = false;
+            if (globalClient === this.client)
+                globalClient = undefined;
+        }
+        catch (error) {
+            console.warn("Error during Dynamite disconnect:", error);
+        }
+    }
+    /**
+     * Ejecutar operaciones en una transacción atómica.
+     * Si cualquier operación falla, todas se revierten automáticamente.
+     *
+     * @param callback Función que recibe el contexto de transacción
+     * @returns Resultado del callback
+     *
+     * @example
+     * await dynamite.tx(async (tx) => {
+     *   const user = await User.create({ name: "Juan" }, tx);
+     *   await Order.create({ user_id: user.id, total: 100 }, tx);
+     * });
+     */
+    async tx(callback) {
+        const ctx = new TransactionContext(this.client);
+        const result = await callback(ctx);
+        await ctx.commit();
+        return result;
+    }
+    /**
+     * Create table with automatic GSI detection and creation
+     * @param ctor Table class constructor
+     */
+    async createTableWithGSI(ctor) {
+        const meta = ctor[decorator_1.SCHEMA];
+        if (!meta)
+            throw new Error(`Class ${ctor.name} not registered. Use decorators.`);
+        const cols = Object.values(meta.columns);
+        const pk = cols.find((c) => c.store?.index);
+        if (!pk)
+            throw new Error(`PartitionKey missing in ${ctor.name}`);
+        const sk = cols.find((c) => c.store?.indexSort);
+        const attr = new Map();
+        attr.set(pk.name || 'id', "S");
+        if (sk)
+            attr.set(sk.name || 'id', "S");
+        // Temporalmente deshabilitamos la creación automática de GSI hasta implementar relaciones
+        const gsiDefinitions = [];
+        const schema = [{ AttributeName: pk.name || 'id', KeyType: "HASH" }];
+        if (sk && sk.name !== pk.name)
+            schema.push({ AttributeName: sk.name || 'id', KeyType: "RANGE" });
+        try {
+            await this.client.send(new client_dynamodb_1.CreateTableCommand({
+                TableName: meta.name,
+                BillingMode: "PAY_PER_REQUEST",
+                AttributeDefinitions: [...attr].map(([AttributeName, AttributeType]) => ({
+                    AttributeName,
+                    AttributeType,
+                })),
+                KeySchema: schema,
+                ...(gsiDefinitions.length > 0 && {
+                    GlobalSecondaryIndexes: gsiDefinitions,
+                }),
+            }));
+        }
+        catch (error) {
+            if (error.name !== "ResourceInUseException")
+                throw error;
+        }
+    }
+}
+exports.Dynamite = Dynamite;
+let globalClient;
+/**
+ * Set global client for Table class operations
+ * @param client DynamoDB client instance
+ */
+const setGlobalClient = (client) => {
+    globalClient = client;
+};
+exports.setGlobalClient = setGlobalClient;
+/**
+ * Get global client for Table class operations
+ */
+const getGlobalClient = () => {
+    if (!globalClient)
+        throw new Error("No global DynamoDB client set. Call setGlobalClient() first.");
+    return globalClient;
+};
+exports.getGlobalClient = getGlobalClient;
+/**
+ * Check if global client is available
+ */
+const hasGlobalClient = () => {
+    return globalClient !== undefined;
+};
+exports.hasGlobalClient = hasGlobalClient;
+/**
+ * Require global client for Table operations (throws if not available)
+ */
+const requireClient = () => {
+    if (!globalClient) {
+        throw new Error("DynamoDB client no configurado. Use Dynamite.connect() primero.");
+    }
+    return globalClient;
+};
+exports.requireClient = requireClient;
+/**
+ * Contexto de transacción para agrupar operaciones atómicas.
+ * Máximo 25 operaciones por transacción (límite DynamoDB).
+ */
+class TransactionContext {
+    constructor(client) {
+        this.operations = [];
+        this.client = client;
+    }
+    /**
+     * Agregar operación Put a la transacción
+     */
+    addPut(table_name, item) {
+        this.operations.push({
+            Put: {
+                TableName: table_name,
+                Item: (0, util_dynamodb_1.marshall)(item, { removeUndefinedValues: true }),
+            },
+        });
+    }
+    /**
+     * Agregar operación Delete a la transacción
+     */
+    addDelete(table_name, key) {
+        this.operations.push({
+            Delete: {
+                TableName: table_name,
+                Key: (0, util_dynamodb_1.marshall)(key),
+            },
+        });
+    }
+    /**
+     * Confirmar todas las operaciones de la transacción.
+     * Si alguna falla, todas se revierten.
+     */
+    async commit() {
+        if (this.operations.length === 0)
+            return;
+        if (this.operations.length > 25) {
+            throw new Error(`Transacción excede el límite de 25 operaciones (tiene ${this.operations.length})`);
+        }
+        await this.client.send(new client_dynamodb_1.TransactWriteItemsCommand({
+            TransactItems: this.operations,
+        }));
+    }
+}
+exports.TransactionContext = TransactionContext;
+//# sourceMappingURL=client.js.map

package/src/core/decorator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file decorator.ts
+ * @description Sistema de decoradores minimalista con Symbol storage
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-28
+ */
+export declare const SCHEMA: unique symbol;
+export declare const VALUES: unique symbol;
+declare function toSnakePlural(str: string): string;
+/**
+ * @description Factory para crear decoradores con soporte de argumentos y composición
+ * @param callback Función que recibe (schema, col, params) para configurar la columna
+ * @returns Función que acepta argumentos y retorna PropertyDecorator
+ * @example
+ * ```typescript
+ * const Default = decorator((schema, col, params) => {
+ *   const fallback = params[0];
+ *   col.get.push((value) => value ?? fallback());
+ * });
+ * // Uso: @Default(uuid)
+ * ```
+ */
+export declare function decorator(callback: (schema: any, col: any, params: any[]) => void): (...params: any[]) => (target: any, propertyKey: string | symbol) => void;
+/**
+ * @description Factory para decoradores de relación
+ * @param relation_type Tipo de relación ("hasMany", "hasOne", "belongsTo")
+ * @param RelatedTable Clase de la tabla relacionada
+ * @param options Opciones de relación (foreignKey, localKey)
+ * @returns PropertyDecorator
+ */
+export declare function relationDecorator(relation_type: string, RelatedTable: any, options?: any): (target: any, propertyKey: string | symbol) => void;
+/**
+ * @description Función helper para obtener metadatos del esquema
+ * @param ctor Constructor de la clase
+ * @returns SchemaEntry
+ */
+export declare function getSchema(ctor: Function): any;
+/**
+ * @description Función helper para verificar que existe esquema
+ * @param ctor Constructor de la clase
+ * @returns SchemaEntry
+ */
+export declare function ensureSchema(ctor: Function): any;
+export { toSnakePlural };

package/src/core/decorator.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * @file decorator.ts
+ * @description Sistema de decoradores minimalista con Symbol storage
+ * @autor Miguel Alejandro
+ * @fecha 2025-01-28
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALUES = exports.SCHEMA = void 0;
+exports.decorator = decorator;
+exports.relationDecorator = relationDecorator;
+exports.getSchema = getSchema;
+exports.ensureSchema = ensureSchema;
+exports.toSnakePlural = toSnakePlural;
+// Symbols para autocontención (exportados desde table.ts pero también aquí compatibilidad)
+exports.SCHEMA = Symbol('dynamite:schema');
+exports.VALUES = Symbol('dynamite:values');
+// Helper simple para snake_case plural
+function toSnakePlural(str) {
+    const snake = str
+        .replace(/([A-Z])/g, "_$1")
+        .toLowerCase()
+        .replace(/^_/, "");
+    return snake.endsWith("s") ? snake : snake + "s";
+}
+/**
+ * @description Factory para crear decoradores con soporte de argumentos y composición
+ * @param callback Función que recibe (schema, col, params) para configurar la columna
+ * @returns Función que acepta argumentos y retorna PropertyDecorator
+ * @example
+ * ```typescript
+ * const Default = decorator((schema, col, params) => {
+ *   const fallback = params[0];
+ *   col.get.push((value) => value ?? fallback());
+ * });
+ * // Uso: @Default(uuid)
+ * ```
+ */
+function decorator(callback) {
+    return (...params) => {
+        return function (target, propertyKey) {
+            const table_class = target.constructor;
+            const column_name = String(propertyKey);
+            // Inicializar SCHEMA si no existe
+            if (!table_class[exports.SCHEMA]) {
+                table_class[exports.SCHEMA] = {
+                    name: toSnakePlural(table_class.name),
+                    primary_key: 'id',
+                    columns: {}
+                };
+            }
+            // Crear columna si no existe
+            if (!table_class[exports.SCHEMA].columns[column_name]) {
+                table_class[exports.SCHEMA].columns[column_name] = {
+                    name: column_name,
+                    get: [],
+                    set: [],
+                    store: {}
+                };
+            }
+            const col = table_class[exports.SCHEMA].columns[column_name];
+            // Ejecutar callback con (schema, col, params)
+            callback(table_class, col, params);
+        };
+    };
+}
+/**
+ * @description Factory para decoradores de relación
+ * @param relation_type Tipo de relación ("hasMany", "hasOne", "belongsTo")
+ * @param RelatedTable Clase de la tabla relacionada
+ * @param options Opciones de relación (foreignKey, localKey)
+ * @returns PropertyDecorator
+ */
+function relationDecorator(relation_type, RelatedTable, options = {}) {
+    return function (target, propertyKey) {
+        const table_class = target.constructor;
+        const column_name = String(propertyKey);
+        if (!table_class[exports.SCHEMA]) {
+            table_class[exports.SCHEMA] = {
+                name: toSnakePlural(table_class.name),
+                primary_key: 'id',
+                columns: {}
+            };
+        }
+        // **Validación: No sobreescribir columnas existentes**
+        if (table_class[exports.SCHEMA].columns[column_name]) {
+            throw new Error(`Column '${column_name}' already exists. Cannot apply relation decorator.`);
+        }
+        // Crear columna virtual para relación
+        table_class[exports.SCHEMA].columns[column_name] = {
+            name: column_name,
+            get: [],
+            set: [],
+            store: {
+                relation: {
+                    type: relation_type,
+                    target: RelatedTable,
+                    foreignKey: options.foreignKey,
+                    localKey: options.localKey,
+                    nullable: options.nullable
+                }
+            }
+        };
+    };
+}
+/**
+ * @description Función helper para obtener metadatos del esquema
+ * @param ctor Constructor de la clase
+ * @returns SchemaEntry
+ */
+function getSchema(ctor) {
+    const schema = ctor[exports.SCHEMA];
+    if (!schema) {
+        throw new Error(`Schema not found for ${ctor.name}. Use decorators first.`);
+    }
+    return schema;
+}
+/**
+ * @description Función helper para verificar que existe esquema
+ * @param ctor Constructor de la clase
+ * @returns SchemaEntry
+ */
+function ensureSchema(ctor) {
+    if (!ctor[exports.SCHEMA]) {
+        ctor[exports.SCHEMA] = {
+            name: toSnakePlural(ctor.name),
+            primary_key: 'id',
+            columns: {}
+        };
+    }
+    return ctor[exports.SCHEMA];
+}
+//# sourceMappingURL=decorator.js.map