@arcaelas/dynamite 1.0.0

package/src/core/table.ts

@@ -0,0 +1,226 @@
+/* src/core/table.ts
+ * Dinamite ORM — runtime
+ * --------------------------------------------------
+ * CRUD + autocreación de tablas (DynamoDB v3)
+ * Serialización estricta mediante toJSON()
+ * © 2025 Miguel Alejandro
+ */
+import {
+  CreateTableCommand,
+  DeleteItemCommand,
+  DynamoDBClient,
+  DynamoDBClientConfig,
+  PutItemCommand,
+  ScanCommand,
+} from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import wrapper, { STORE, WrapperEntry } from "./wrapper";
+
+/* ────────────────────────── Conexión global ────────────────────────── */
+let client: DynamoDBClient | undefined;
+export function connect(cfg: DynamoDBClientConfig): void {
+  client = new DynamoDBClient(cfg);
+}
+
+/* ─────────── Creación automática de tablas a partir del wrapper ────── */
+async function createTable(ctor: Function): Promise<void> {
+  if (!client) throw new Error("connect() no llamado");
+  const meta = wrapper.get(ctor);
+  if (!meta) throw new Error(`Clase ${ctor.name} no registrada en wrapper`);
+
+  const cols = [...meta.columns.values()];
+  const pk = cols.find((c) => c.index);
+  if (!pk) throw new Error(`PartitionKey faltante en ${ctor.name}`);
+
+  const sk = cols.find((c) => c.indexSort);
+
+  const attr = new Map<string, "S" | "N" | "B">();
+  attr.set(pk.name, "S");
+  if (sk) attr.set(sk.name, "S");
+
+  type KS = { AttributeName: string; KeyType: "HASH" | "RANGE" };
+  const schema: KS[] = [{ AttributeName: pk.name, KeyType: "HASH" }];
+  if (sk && sk.name !== pk.name)
+    schema.push({ AttributeName: sk.name, KeyType: "RANGE" });
+
+  await client.send(
+    new CreateTableCommand({
+      TableName: meta.name,
+      BillingMode: "PAY_PER_REQUEST",
+      AttributeDefinitions: [...attr].map(([AttributeName, AttributeType]) => ({
+        AttributeName,
+        AttributeType,
+      })),
+      KeySchema: schema,
+    })
+  );
+}
+
+/* ────────────────────────────── Table ──────────────────────────────── */
+export default class Table<T extends object = object> {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  private [STORE]!: { [K in keyof T]?: T[K] };
+
+  constructor(data: Partial<T> = {}) {
+    requireClient();
+    const meta = mustMeta(Object.getPrototypeOf(this).constructor);
+
+    /* defaults via setters */
+    meta.columns.forEach((c) => {
+      if (!(c.name in data)) (this as any)[c.name] = undefined;
+    });
+
+    Object.assign(this, data);
+  }
+
+  /* -------- serializa SOLO columnas válidas -------- */
+  toJSON(): Record<string, unknown> {
+    const meta = mustMeta(Object.getPrototypeOf(this).constructor);
+    const buf = (this as any)[STORE] ?? {};
+    const out: Record<string, unknown> = {};
+
+    for (const [prop, col] of meta.columns) {
+      if (prop in buf) out[col.name] = buf[prop];
+      else if (prop in this) out[col.name] = (this as any)[prop];
+    }
+    return out;
+  }
+
+  /* ────────────── Métodos de instancia ────────────── */
+  async save(): Promise<this> {
+    // @ts-ignore
+    const id: unknown = this.id;
+    const Ctor = this.constructor as typeof Table<any>;
+    const record = this.toJSON();
+
+    if (id === undefined || id === null) {
+      delete (record as any).id;
+      const fresh = await (Ctor as any).create(record);
+      Object.assign(this, fresh);
+    } else {
+      await (Ctor as any).update(String(id), record);
+    }
+    return this;
+  }
+
+  async update(patch: Partial<T>): Promise<this> {
+    // @ts-ignore
+    const id: unknown = this.id;
+    if (id === undefined || id === null)
+      throw new Error("update() requiere id");
+
+    Object.assign(this, patch);
+    const Ctor = this.constructor as typeof Table<any>;
+    await (Ctor as any).update(String(id), this.toJSON());
+    return this;
+  }
+
+  async destroy(): Promise<void> {
+    // @ts-ignore
+    const id: unknown = this.id;
+    if (id === undefined || id === null)
+      throw new Error("destroy() requiere id");
+    const Ctor = this.constructor as typeof Table<any>;
+    await (Ctor as any).destroy(String(id));
+  }
+
+  /* ─────────────── CRUD estáticos ──────────────── */
+
+  static async create<M extends Table>(
+    this: new (d?: Partial<M>) => M,
+    data: Partial<M>
+  ): Promise<M> {
+    const meta = mustMeta(this);
+    const payload = new this(data).toJSON(); // filtrado
+
+    const put = () =>
+      client!.send(
+        new PutItemCommand({
+          TableName: meta.name,
+          Item: marshall(payload, { removeUndefinedValues: true }),
+        })
+      );
+
+    try {
+      await put();
+    } catch (err: any) {
+      if (err?.name === "ResourceNotFoundException") {
+        await createTable(this);
+        await put();
+      } else throw err;
+    }
+    return new this(data);
+  }
+
+  static async update<M extends Table>(
+    this: new (d?: Partial<M>) => M,
+    id: string,
+    record: Partial<M> // ← ya es JSON completo desde instancia
+  ): Promise<void> {
+    const meta = mustMeta(this);
+    const payload = { ...record, id };
+
+    const put = () =>
+      client!.send(
+        new PutItemCommand({
+          TableName: meta.name,
+          Item: marshall(payload, { removeUndefinedValues: true }),
+        })
+      );
+
+    try {
+      await put();
+    } catch (err: any) {
+      if (err?.name === "ResourceNotFoundException") {
+        await createTable(this);
+        await put();
+      } else throw err;
+    }
+  }
+
+  static async destroy<M extends Table>(
+    this: new () => M,
+    id: string
+  ): Promise<null> {
+    requireClient();
+    try {
+      await client!.send(
+        new DeleteItemCommand({
+          TableName: mustMeta(this).name,
+          Key: marshall({ id }),
+        })
+      );
+    } catch (err: any) {
+      if (err.name === "ResourceNotFoundException") return null;
+      throw err;
+    }
+    return null;
+  }
+
+  static async where<M extends Table>(this: new (d?: any) => M): Promise<M[]> {
+    requireClient();
+    try {
+      const res = await client!.send(
+        new ScanCommand({ TableName: mustMeta(this).name })
+      );
+      return (res.Items ?? []).map((i) => new this(unmarshall(i)));
+    } catch (err: any) {
+      if (err.name === "ResourceNotFoundException") return [];
+      throw err;
+    }
+  }
+}
+
+/* ─────────────────── Utilidades internas ─────────────────── */
+function requireClient(): void {
+  if (!client) throw new Error("connect() debe llamarse antes de usar Table");
+}
+function mustMeta(ctor: Function): WrapperEntry {
+  const meta = wrapper.get(ctor);
+  if (!meta) throw new Error(`Metadata no encontrada para ${ctor.name}`);
+  return meta;
+}
+
+/* ─────────────────── Exportaciones internas ───────────────── */
+export { STORE };
+export type { WrapperEntry };

package/src/core/wrapper.ts

@@ -0,0 +1,103 @@
+/* src/core/wrapper.ts
+ * -------------------------------------------------
+ * Registro central (in-memory) de la configuración
+ * declarativa de cada modelo.  Agnóstico: no depende
+ * de DynamoDB ni de otros módulos de la librería.
+ *
+ * © 2025 Miguel Alejandro
+ */
+
+/* ------------------------------------------------------------------ */
+/* 1.  Tipos utilitarios                                              */
+/* ------------------------------------------------------------------ */
+export type Inmutable = string | number | boolean | null | object;
+
+export type Mutate = (value: any) => Inmutable;
+export type Default = Inmutable | (() => Inmutable);
+export type Validate = (value: any) => true | string;
+
+/* ------------------------------------------------------------------ */
+/* 2.  Descripción de columna y tabla                                 */
+/* ------------------------------------------------------------------ */
+export interface Column {
+  /** nombre físico en la tabla (DynamoDB) */
+  name: string;
+
+  /* Decoradores básicos */
+  default?: Default;
+  mutate?: Mutate[];
+  validate?: Validate[];
+
+  /* Metadatos de índice / unicidad */
+  index?: true; // Partition Key
+  indexSort?: true; // Sort Key
+  unique?: true; // constraint lógico (no se valida en Dynamo)
+}
+
+/**
+ * Configuración completa por tabla
+ */
+export interface WrapperEntry {
+  /** Nombre físico de la tabla (snake_plural o @Name) */
+  name: string;
+
+  /** Columnas asociadas a la clase. key = propiedad (string|symbol) */
+  columns: Map<string | symbol, Column>;
+}
+
+/* ------------------------------------------------------------------ */
+/* 3.  Contenedor global                                              */
+/* ------------------------------------------------------------------ */
+export type Wrapper = Map<Function, WrapperEntry>;
+
+/**
+ * Mapa singleton (clase → configuración)
+ * Exportado como default para uso interno de la librería.
+ */
+const wrapper: Wrapper = new Map();
+export default wrapper;
+
+/* ------------------------------------------------------------------ */
+/* 4.  Símbolo de almacenamiento de valores reales                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Buffer privado en cada instancia de Table donde se guardan
+ * los valores procesados por los setters virtuales.
+ *
+ * Se exporta para que los decoradores puedan leer/escribir,
+ * pero **NO** se vuelve a exportar desde la raíz del paquete.
+ */
+export const STORE: unique symbol = Symbol("dynamite:values");
+
+/* ------------------------------------------------------------------ */
+/* 5.  Pequeños helpers opcionales                                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Asegura que exista la entrada en el wrapper para la clase dada.
+ * Devuelve la entrada (recién creada o existente).
+ */
+export function ensureConfig(ctor: Function, tableName: string): WrapperEntry {
+  let entry = wrapper.get(ctor);
+  if (!entry) {
+    entry = { name: tableName, columns: new Map() };
+    wrapper.set(ctor, entry);
+  }
+  return entry;
+}
+
+/**
+ * Obtiene (o crea) el objeto Column para una propiedad concreta.
+ */
+export function ensureColumn(
+  entry: WrapperEntry,
+  prop: string | symbol,
+  columnName: string
+): Column {
+  let col = entry.columns.get(prop);
+  if (!col) {
+    col = { name: columnName, mutate: [], validate: [] };
+    entry.columns.set(prop, col);
+  }
+  return col;
+}

package/src/decorators/created_at.ts

@@ -0,0 +1,17 @@
+/*
+ * Dinamite ORM — @CreatedAt Decorator (wrapper)
+ * -------------------------------------------
+ * Establece un valor por defecto con la fecha/hora actual (ISO‑string)
+ * usando @Default.
+ *
+ * © 2025 Miguel Alejandro
+ */
+
+import Default from "./default";
+
+/**
+ * Asigna automáticamente la fecha de creación en nuevas instancias.
+ */
+export default function CreatedAt(): PropertyDecorator {
+  return Default(() => new Date().toISOString());
+}

package/src/decorators/default.ts

@@ -0,0 +1,56 @@
+/*
+ * Dinamite ORM — @Default
+ * -----------------------
+ * Registra un valor por defecto y crea (si falta) el
+ * getter/setter virtual de la propiedad.
+ */
+
+import { Column, STORE, ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function Default(factory: () => unknown): PropertyDecorator {
+  if (typeof factory !== "function") {
+    throw new TypeError("@Default requiere una función factory");
+  }
+
+  return (target: object, prop: string | symbol): void => {
+    const ctor = (target as any).constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+    const column = ensureColumn(entry, prop, String(prop));
+
+    if (column.default)
+      throw new Error(`@Default duplicado en '${String(prop)}'`);
+    column.default = factory;
+
+    if (!Object.getOwnPropertyDescriptor(ctor.prototype, prop)?.set) {
+      defineVirtual(ctor.prototype, column, prop);
+    }
+  };
+}
+
+/* ------------------------------------------------------------------ */
+function defineVirtual(proto: any, col: Column, prop: string | symbol): void {
+  Object.defineProperty(proto, prop, {
+    get() {
+      return (this[STORE] ?? {})[prop];
+    },
+    set(val: unknown) {
+      const buf = (this[STORE] ??= {});
+
+      if (val === undefined && col.default !== undefined) {
+        val = typeof col.default === "function" ? col.default() : col.default;
+      }
+      if (col.mutate) for (const m of col.mutate) val = m(val);
+      if (col.validate) {
+        for (const v of col.validate) {
+          const r = v(val);
+          if (r !== true)
+            throw new Error(typeof r === "string" ? r : "Validación fallida");
+        }
+      }
+      buf[prop] = val;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}

package/src/decorators/index.ts

@@ -0,0 +1,26 @@
+/*
+ * Dinamite ORM — @Index (Partition Key)
+ * -------------------------------------
+ * Marca la propiedad como clave de partición.
+ */
+
+import { ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function Index(): PropertyDecorator {
+  return (target: object, prop: string | symbol): void => {
+    const ctor = (target as any).constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+
+    /* Evitar duplicados */
+    const already = [...entry.columns.values()].find((c) => c.index);
+    if (already && already !== entry.columns.get(prop)) {
+      throw new Error(
+        `La tabla ${ctor.name} ya tiene PartitionKey (${already.name})`
+      );
+    }
+
+    const col = ensureColumn(entry, prop, String(prop));
+    col.index = true;
+  };
+}

package/src/decorators/index_sort.ts

@@ -0,0 +1,32 @@
+/*
+ * Dinamite ORM — @IndexSort (Sort Key)
+ * ------------------------------------
+ * Marca la propiedad como clave de ordenamiento.
+ */
+
+import { ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function IndexSort(): PropertyDecorator {
+  return (target: object, prop: string | symbol): void => {
+    const ctor = (target as any).constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+
+    const pkExists = [...entry.columns.values()].some((c) => c.index);
+    if (!pkExists) {
+      throw new Error(
+        `PartitionKey no definido en ${ctor.name}; declara @Index primero`
+      );
+    }
+
+    const already = [...entry.columns.values()].find((c) => c.indexSort);
+    if (already && already !== entry.columns.get(prop)) {
+      throw new Error(
+        `La tabla ${ctor.name} ya tiene SortKey (${already.name})`
+      );
+    }
+
+    const col = ensureColumn(entry, prop, String(prop));
+    col.indexSort = true;
+  };
+}

package/src/decorators/mutate.ts

@@ -0,0 +1,54 @@
+/*
+ * Dinamite ORM — @Mutate
+ * ----------------------
+ * Registra funciones transformadoras para un campo y virtualiza
+ * la propiedad si aún no existe.
+ */
+
+import type { Column, Mutate } from "../core/wrapper";
+import { STORE, ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function Mutate(fn: Mutate): PropertyDecorator {
+  if (typeof fn !== "function") throw new TypeError("@Mutate requiere función");
+
+  return (target: object, prop: string | symbol): void => {
+    const ctor = (target as any).constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+    const col = ensureColumn(entry, prop, String(prop));
+
+    col.mutate ??= [];
+    col.mutate.push(fn);
+
+    if (!Object.getOwnPropertyDescriptor(ctor.prototype, prop)?.set) {
+      defineVirtual(ctor.prototype, col, prop);
+    }
+  };
+}
+
+/* ------------------------------------------------------------------ */
+function defineVirtual(proto: any, col: Column, prop: string | symbol): void {
+  Object.defineProperty(proto, prop, {
+    get() {
+      return (this[STORE] ?? {})[prop];
+    },
+    set(val: unknown) {
+      const buf = (this[STORE] ??= {});
+
+      if (val === undefined && col.default !== undefined) {
+        val = typeof col.default === "function" ? col.default() : col.default;
+      }
+      if (col.mutate) for (const m of col.mutate) val = m(val);
+      if (col.validate) {
+        for (const v of col.validate) {
+          const r = v(val);
+          if (r !== true)
+            throw new Error(typeof r === "string" ? r : "Validación fallida");
+        }
+      }
+      buf[prop] = val;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}

package/src/decorators/name.ts

@@ -0,0 +1,50 @@
+/*
+ * Dinamite ORM — @Name
+ * --------------------
+ * • @Name("tabla")    → nombre físico de la tabla
+ * • @Name("columna")  → alias de columna
+ *
+ * Permite sobrescribir el nombre AUTO-generado (snake_plural)
+ * sin lanzar conflicto.
+ */
+
+import { ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function Name(
+  label: string
+): ClassDecorator & PropertyDecorator {
+  if (!label || typeof label !== "string") {
+    throw new TypeError("@Name requiere una cadena no vacía");
+  }
+
+  return (target: any, prop?: string | symbol): void => {
+    const ctor = prop === undefined ? target : target.constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+
+    if (prop === undefined) {
+      /* ---------- Nombre de la tabla ---------- */
+
+      const auto = toSnakePlural(ctor.name);
+
+      // Solo error si ya se modificó conscientemente antes.
+      if (entry.name !== auto && entry.name !== label && entry.name) {
+        throw new Error(
+          `La clase ${ctor.name} ya tiene un @Name distinto (${entry.name})`
+        );
+      }
+      entry.name = label;
+    } else {
+      /* ---------- Alias de columna ---------- */
+
+      const col = ensureColumn(entry, prop, label);
+
+      if (col.name && col.name !== label) {
+        throw new Error(
+          `La columna '${String(prop)}' ya tiene @Name distinto (${col.name})`
+        );
+      }
+      col.name = label;
+    }
+  };
+}

package/src/decorators/not_null.ts

@@ -0,0 +1,21 @@
+/*
+ * Dinamite ORM — @NotNull Decorator (wrapper)
+ * ------------------------------------------
+ * Valida que el valor no sea null, undefined ni cadena vacía.
+ * Internamente aplica @Validate con una función sincrónica.
+ *
+ * © 2025 Miguel Alejandro
+ */
+
+import Validate from "./validate";
+
+/**
+ * Decorador wrapper que asegura no-null / no-empty.
+ */
+export default function NotNull(): PropertyDecorator {
+  return (Validate as any)((value, key) => {
+    if (value === null || value === undefined) return false;
+    if (typeof value === "string" && value.trim() === "") return false;
+    return true;
+  });
+}

package/src/decorators/primary_key.ts

@@ -0,0 +1,26 @@
+/*
+ * Dinamite ORM — @PrimaryKey
+ * --------------------------
+ * Declara simultáneamente Partition Key y Sort Key
+ * sobre la misma propiedad.
+ */
+
+import Index from "./index";
+import IndexSort from "./index_sort";
+
+/**
+ * Atajo para definir clave primaria compuesta (PK + SK).
+ * El parámetro `name` queda reservado por si en el futuro
+ * se almacena un identificador lógico de índice, pero hoy
+ * NO se pasa a ningún decorador interno.
+ */
+export default function PrimaryKey(name = "primary"): PropertyDecorator {
+  if (typeof name !== "string" || !name.trim()) {
+    throw new TypeError("@PrimaryKey requiere un nombre de índice válido");
+  }
+
+  return (target: object, prop: string | symbol): void => {
+    Index()(target, prop); // Partition Key
+    IndexSort()(target, prop); // Sort Key
+  };
+}

package/src/decorators/updated_at.ts

@@ -0,0 +1,18 @@
+/*
+ * Dinamite ORM — @UpdatedAt Decorator (wrapper)
+ * --------------------------------------------
+ * Actualiza la fecha/hora cada vez que la propiedad recibe un nuevo valor
+ * (incluyendo actualizaciones mediante Model.save()).
+ * Internamente aplica @Mutate con una factory de timestamp ISO.
+ *
+ * © 2025 Miguel Alejandro
+ */
+
+import Mutate from "./mutate";
+
+/**
+ * Actualiza automáticamente la marca temporal en cada asignación.
+ */
+export default function UpdatedAt(): PropertyDecorator {
+  return Mutate(() => new Date().toISOString());
+}

package/src/decorators/validate.ts

@@ -0,0 +1,59 @@
+/*
+ * Dinamite ORM — @Validate
+ * ------------------------
+ * Registra validadores y crea virtual si falta.
+ */
+
+import { Column, STORE, ensureColumn, ensureConfig } from "../core/wrapper";
+import { toSnakePlural } from "../utils/naming";
+
+export default function Validate(
+  validators:
+    | ((v: unknown) => true | string)
+    | ((v: unknown) => true | string)[]
+): PropertyDecorator {
+  const list = Array.isArray(validators) ? validators : [validators];
+  if (!list.length || list.some((v) => typeof v !== "function")) {
+    throw new TypeError("@Validate requiere funciones");
+  }
+
+  return (target: object, prop: string | symbol): void => {
+    const ctor = (target as any).constructor;
+    const entry = ensureConfig(ctor, toSnakePlural(ctor.name));
+    const col = ensureColumn(entry, prop, String(prop));
+
+    col.validate ??= [];
+    col.validate.push(...list);
+
+    if (!Object.getOwnPropertyDescriptor(ctor.prototype, prop)?.set) {
+      defineVirtual(ctor.prototype, col, prop);
+    }
+  };
+}
+
+/* ------------------------------------------------------------------ */
+function defineVirtual(proto: any, col: Column, prop: string | symbol): void {
+  Object.defineProperty(proto, prop, {
+    get() {
+      return (this[STORE] ?? {})[prop];
+    },
+    set(val: unknown) {
+      const buf = (this[STORE] ??= {});
+
+      if (val === undefined && col.default !== undefined) {
+        val = typeof col.default === "function" ? col.default() : col.default;
+      }
+      if (col.mutate) for (const m of col.mutate) val = m(val);
+      if (col.validate) {
+        for (const v of col.validate) {
+          const r = v(val);
+          if (r !== true)
+            throw new Error(typeof r === "string" ? r : "Validación fallida");
+        }
+      }
+      buf[prop] = val;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}