@arcaelas/dynamite 1.0.17 → 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.17"
+  "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

@@ -1,5 +1,6 @@
 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[] & {
@@ -8,6 +9,9 @@ export type HasMany<T> = T[] & {
 export type BelongsTo<T> = (T | null) & {
     [BelongsToBrand]?: true;
 };
+export type HasOne<T> = (T | null) & {
+    [HasOneBrand]?: true;
+};
 export type NonAttribute<T> = T & {
     [NonAttributeBrand]?: true;
 };
@@ -19,6 +23,8 @@ export type InferAttributes<T> = {
         [HasManyBrand]?: true;
     } ? never : T[K] extends {
         [BelongsToBrand]?: true;
+    } ? never : T[K] extends {
+        [HasOneBrand]?: true;
     } ? never : T[K] extends {
         [NonAttributeBrand]?: true;
     } ? never : K]: T[K];
@@ -26,18 +32,6 @@ export type InferAttributes<T> = {
 export type FilterableAttributes<T> = {
     [K in keyof InferAttributes<T>]: InferAttributes<T>[K];
 };
-type SelectResult<T, A extends keyof T> = Pick<T, A>;
-type ResolveIncludeType<T, K extends keyof T> = T[K] extends HasMany<infer U> ? U[] : T[K] extends BelongsTo<infer U> ? U | null : never;
-export type IncludeOptions = {
-    where?: Record<string, any>;
-    attributes?: string[];
-    limit?: number;
-    skip?: number;
-    order?: "ASC" | "DESC";
-};
-export type QueryResult<T, A extends keyof T = keyof T, I extends Record<string, any> = {}> = SelectResult<T & {
-    [K in keyof I]: K extends keyof T ? ResolveIncludeType<T, K> : never;
-}, A>;
 export type WhereOptions<T> = {
     where?: Partial<FilterableAttributes<T>>;
     skip?: number;
@@ -45,16 +39,21 @@ export type WhereOptions<T> = {
     order?: "ASC" | "DESC";
     attributes?: (keyof FilterableAttributes<T>)[];
     include?: {
-        [K in keyof T]?: T[K] extends HasMany<any> | BelongsTo<any> ? IncludeOptions | {} : never;
+        [K in keyof T]?: T[K] extends HasMany<any> | BelongsTo<any> | HasOne<any> ? IncludeRelationOptions | true : never;
     };
 };
-export type WhereOptionsWithoutWhere<T> = Omit<WhereOptions<T>, "where">;
+/** 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;
-    default?: any | (() => any);
-    mutate?: ((value: any) => any)[];
-    validate?: ((value: any) => boolean | string)[];
     index?: true;
     indexSort?: true;
     primaryKey?: boolean;
@@ -62,9 +61,12 @@ export interface Column {
     unique?: true;
     createdAt?: boolean;
     updatedAt?: boolean;
+    softDelete?: boolean;
+    lazy_validators?: ((value: any) => boolean | string)[];
+    relation?: RelationMetadata;
 }
 export interface RelationMetadata {
-    type: "hasMany" | "belongsTo";
+    type: "hasMany" | "belongsTo" | "hasOne";
     targetModel: () => any;
     foreignKey: string;
     localKey?: string;
@@ -74,6 +76,8 @@ export interface WrapperEntry {
     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[];
@@ -82,15 +86,17 @@ export type IncludeRelationOptions = {
     limit?: number;
     include?: Record<string, IncludeRelationOptions | true>;
 };
-export type WhereQueryOptions<T> = {
+/** 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> ? IncludeRelationOptions | true : never;
+        [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;
-export {};

package/src/core/client.d.ts

@@ -44,6 +44,20 @@ export declare class Dynamite {
      * 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
@@ -67,3 +81,25 @@ 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

@@ -5,13 +5,11 @@
  * @autor Miguel Alejandro
  * @fecha 2025-01-27
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireClient = exports.hasGlobalClient = exports.getGlobalClient = exports.setGlobalClient = exports.Dynamite = void 0;
+exports.TransactionContext = exports.requireClient = exports.hasGlobalClient = exports.getGlobalClient = exports.setGlobalClient = exports.Dynamite = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-const wrapper_1 = __importDefault(require("./wrapper"));
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const decorator_1 = require("./decorator");
 /**
  * Centralized Dynamite client for managing DynamoDB connections and table synchronization
  */
@@ -72,39 +70,47 @@ class Dynamite {
             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 = wrapper_1.default.get(ctor);
+        const meta = ctor[decorator_1.SCHEMA];
         if (!meta)
-            throw new Error(`Class ${ctor.name} not registered in wrapper`);
-        const cols = [...meta.columns.values()];
-        const pk = cols.find((c) => c.index);
+            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.indexSort);
+        const sk = cols.find((c) => c.store?.indexSort);
         const attr = new Map();
-        attr.set(pk.name, "S");
+        attr.set(pk.name || 'id', "S");
         if (sk)
-            attr.set(sk.name, "S");
-        let gsiIndex = 1;
-        const gsiDefinitions = [...meta.relations.values()]
-            .filter((relation) => relation.type === "hasMany")
-            .map((relation) => {
-            const { foreignKey } = relation;
-            if (!attr.has(foreignKey))
-                attr.set(foreignKey, "S");
-            return {
-                IndexName: `GSI${gsiIndex++}_${foreignKey}`,
-                KeySchema: [{ AttributeName: foreignKey, KeyType: "HASH" }],
-                Projection: { ProjectionType: "ALL" },
-            };
-        });
-        const schema = [{ AttributeName: pk.name, KeyType: "HASH" }];
+            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, KeyType: "RANGE" });
+            schema.push({ AttributeName: sk.name || 'id', KeyType: "RANGE" });
         try {
             await this.client.send(new client_dynamodb_1.CreateTableCommand({
                 TableName: meta.name,
@@ -161,4 +167,51 @@ const requireClient = () => {
     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

package/src/core/method.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file method.ts
+ * @descripcion Sistema de métodos extensibles para Table
+ * @autor Miguel Alejandro
+ */
+/** Handler para métodos estáticos: (TableClass, args) => result */
+export type StaticMethodHandler<R = any> = (table: any, args: any[]) => R | Promise<R>;
+/** Handler para métodos de instancia: (TableClass, instance, args) => result */
+export type InstanceMethodHandler<R = any> = (table: any, instance: any, args: any[]) => R | Promise<R>;
+/**
+ * @description Configura la clase Table para el sistema de métodos
+ * @param TableClass Clase Table
+ */
+export declare function setTableClass(TableClass: any): void;
+/**
+ * @description Registra un método estático en Table y lo define en la clase
+ * @param name Nombre del método
+ * @param handler Función que implementa el método
+ * @example
+ * ```typescript
+ * registerStaticMethod('customFind', function(t, args) {
+ *   const meta = mustMeta(t);
+ *   return instances;
+ * });
+ * // Uso: User.customFind(...)
+ * ```
+ */
+export declare function registerStaticMethod<R = any>(name: string, handler: StaticMethodHandler<R>): void;
+/**
+ * @description Registra un método de instancia en Table y lo define en el prototype
+ * @param name Nombre del método
+ * @param handler Función que implementa el método
+ * @example
+ * ```typescript
+ * registerInstanceMethod('duplicate', function(t, m, args) {
+ *   return t.create({ ...m.toJSON(), id: undefined });
+ * });
+ * // Uso: user.duplicate()
+ * ```
+ */
+export declare function registerInstanceMethod<R = any>(name: string, handler: InstanceMethodHandler<R>): void;
+/**
+ * @description Obtiene un método estático registrado
+ */
+export declare function getStaticMethod(name: string): StaticMethodHandler | undefined;
+/**
+ * @description Obtiene un método de instancia registrado
+ */
+export declare function getInstanceMethod(name: string): InstanceMethodHandler | undefined;
+/**
+ * @description Ejecuta un método estático registrado
+ */
+export declare function callStaticMethod<R = any>(name: string, table: any, args: any[]): R | Promise<R>;
+/**
+ * @description Ejecuta un método de instancia registrado
+ */
+export declare function callInstanceMethod<R = any>(name: string, table: any, instance: any, args: any[]): R | Promise<R>;
+/**
+ * @description Verifica si un método estático está registrado
+ */
+export declare function hasStaticMethod(name: string): boolean;
+/**
+ * @description Verifica si un método de instancia está registrado
+ */
+export declare function hasInstanceMethod(name: string): boolean;
+/**
+ * @description Lista todos los métodos estáticos registrados
+ */
+export declare function listStaticMethods(): string[];
+/**
+ * @description Lista todos los métodos de instancia registrados
+ */
+export declare function listInstanceMethods(): string[];