@arcaelas/dynamite 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 arcaela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+![Arcaelas Insiders](https://raw.githubusercontent.com/arcaelas/dist/main/banner/svg/dark.svg#gh-dark-mode-only)
+![Arcaelas Insiders](https://raw.githubusercontent.com/arcaelas/dist/main/banner/svg/light.svg#gh-light-mode-only)
+
+# Dinamite ORM
+
+> A **decorator‑first**, zero‑boilerplate ORM for DynamoDB (AWS SDK v3).
+>
+> _Auto‑provisions tables · Runs anywhere Node.js runs · Written in TypeScript only_
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@arcaelas/dinamite"><img src="https://img.shields.io/npm/v/@arcaelas/dinamite?color=cb3837" alt="npm"></a>
+  <img src="https://img.shields.io/bundlephobia/minzip/@arcaelas/dinamite?label=gzip" alt="size">
+  <img src="https://img.shields.io/github/license/arcaelas/dinamite" alt="MIT">
+</p>
+
+---
+
+## Contents
+
+- [Install](#install)
+- [Hello World](#hello-world)
+- [Decorators Reference](#decorators-reference)
+- [Model API](#model-api)
+
+  - [Static CRUD](#static-crud)
+  - [Instance CRUD](#instance-crud)
+  - [Serialization](#serialization)
+
+- [Configuration](#configuration)
+
+  - [Connection](#connection)
+  - [Naming rules & pluralisation](#naming-rules--pluralisation)
+  - [Running on DynamoDB Local](#running-on-dynamodb-local)
+
+- [Type Reference](#type-reference)
+- [Recipes](#recipes)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+
+---
+
+## Install
+
+```bash
+npm i @arcaelas/dinamite
+# peer deps (unless already installed)
+npm i @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb pluralize
+```
+
+---
+
+## Hello World
+
+```ts
+import {
+  connect,
+  Table,
+  Index, // PK
+  CreatedAt,
+  UpdatedAt,
+  Default,
+} from "@arcaelas/dinamite";
+
+connect({
+  region: "us-east-1",
+  // DynamoDB Local example
+  endpoint: "http://localhost:7007",
+  credentials: { accessKeyId: "x", secretAccessKey: "x" },
+});
+
+class User extends Table {
+  @Index() // Partition Key
+  declare id: string;
+
+  @Default(() => "")
+  declare name: string;
+
+  @CreatedAt() // ISO‑string timestamp
+  declare created: string;
+
+  @UpdatedAt()
+  declare updated: string;
+}
+
+const bob = await User.create({ id: "u1", name: "Bob" });
+
+bob.name = "Robert";
+await bob.save(); // upsert
+
+console.log(await User.where());
+await bob.destroy();
+```
+
+First call auto‑creates a table `users` (`user` → **snake + plural**).
+
+---
+
+## Decorators Reference
+
+| Decorator          | Purpose                                               | Extras |
+| ------------------ | ----------------------------------------------------- | ------ |
+| `@Index()`         | **Partition key**. Exactly one «PK» per model.        |        |
+| `@IndexSort()`     | **Sort key**. Requires previous `@Index()`.           |        |
+| `@PrimaryKey()`    | Shortcut: _PK + SK on same property_.                 |        |
+| `@Default(fn)`     | Lazy default value, evaluated once per instance.      |        |
+| `@Mutate(fn)`      | Sequential value transformer. Runs before validators. |        |
+| `@Validate(fn\[])` | Sync validator(s); return `true` or error `string`.   |        |
+| `@NotNull()`       | Built‑in not‑null / not‑empty validation.             |        |
+| `@CreatedAt()`     | Timestamp (ISO) on first assignment.                  |        |
+| `@UpdatedAt()`     | Timestamp (ISO) **every** assignment.                 |        |
+| `@Name("alias")`   | Override table _or_ column name.                      |        |
+
+Execution order: **Default → Mutate\[] → Validate\[]**
+
+---
+
+## Model API
+
+### Static CRUD
+
+```ts
+User.create(data); // PutItem (auto‑table‑creation)
+User.update(id, patch); // PutItem replacement
+User.destroy(id); // DeleteItem
+User.where(); // Scan → User[]
+```
+
+### Instance CRUD
+
+```ts
+const u = new User({ id: "42", name: "Neo" });
+await u.save(); // inserts
+
+u.name = "The One";
+await u.save(); // updates
+
+await u.update({ name: "Thomas" });
+await u.destroy();
+```
+
+### Serialization
+
+`model.toJSON()` → **only fields declared via decorators** are included.
+Undefined values are stripped before `marshall()` (`removeUndefinedValues`).
+
+---
+
+## Configuration
+
+### Connection
+
+```ts
+connect({
+  region: "…",
+  endpoint: "https://…", // optional – for DynamoDB Local
+  credentials: {
+    accessKeyId: "…",
+    secretAccessKey: "…",
+  },
+});
+```
+
+### Naming rules & pluralisation
+
+- `PascalCase` / `camelCase` → `snake_case`
+- Singular → **plural** using [`pluralize`](https://www.npmjs.com/package/pluralize)
+
+Override with `@Name("my_table")`.
+
+### Running on DynamoDB Local
+
+```bash
+docker run -p 7007:8000 amazon/dynamodb-local
+```
+
+---
+
+## Type Reference
+
+```ts
+type Inmutable = string | number | boolean | null | object;
+
+type Mutate = (value: any) => Inmutable;
+type Default = Inmutable | (() => Inmutable);
+type Validate = (value: any) => true | string;
+
+interface Column {
+  name: string;
+  default?: Default;
+  mutate?: Mutate[];
+  validate?: Validate[];
+  index?: true; // PK
+  indexSort?: true; // SK
+  unique?: true; // not yet enforced
+}
+
+interface WrapperEntry {
+  name: string; // physical table
+  columns: Map<string | symbol, Column>; // property → Column
+}
+```
+
+Internal state lives in **`src/core/wrapper.ts`**.
+
+---
+
+## Recipes
+
+### Soft‑delete flag
+
+```ts
+class Post extends Table {
+  @Index() declare id: string;
+  @Default(() => false) declare deleted: boolean;
+
+  async softDelete() {
+    this.deleted = true;
+    await this.save();
+  }
+}
+```
+
+### Custom mutator – email normalisation
+
+```ts
+import { Mutate } from "@arcaelas/dinamite";
+
+const lower: Mutate = (v) => String(v).toLowerCase();
+
+class Subscriber extends Table {
+  @Index() declare id: string;
+  @Mutate(lower) declare email: string;
+}
+```
+
+### Using DynamoDB Streams + Lambda
+
+Because tables are created at runtime you can safely deploy stacks without `resources`, then subscribe Lambdas to the **physical table names** emitted by Dinamite (`User` → `users`, unless overridden).
+
+---
+
+## Troubleshooting
+
+| Error                                 | Explanation & fix                                                                                           |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `Metadata no encontrada`              | Model file imported before decorators executed – avoid circular imports; ensure `connect()` runs **first**. |
+| `PartitionKey faltante`               | No `@Index()` in the model. Add one.                                                                        |
+| `Two keys can not have the same name` | PK & SK attribute clash. Use `@PrimaryKey()` or distinct column names.                                      |
+| `UnrecognizedClientException`         | Wrong credentials / DynamoDB Local not running.                                                             |
+
+---
+
+## Contributing
+
+1. Fork → feature → PR. Conventional commits (`feat:`, `fix:`…).
+2. `yarn test` must pass (Jest + ESLint).
+3. Document new features in this README.
+
+_Made with ❤️ by [Miguel Alejandro](https://github.com/arcaelas)_ – MIT License.

package/__tests__/crud.spec.ts

@@ -0,0 +1,77 @@
+/* __tests__/crud.spec.ts
+ * -----------------------------------------------------------
+ * CRUD end-to-end contra DynamoDB Local (puerto 7007)
+ */
+
+import { DeleteTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+
+import { connect, default as Table } from "../src/core/table";
+import wrapper from "../src/core/wrapper";
+
+import Default from "../src/decorators/default";
+import Name from "../src/decorators/name";
+import NotNull from "../src/decorators/not_null";
+import PrimaryKey from "../src/decorators/primary_key";
+
+const ddbCfg = {
+  region: "local",
+  endpoint: "http://localhost:7007",
+  credentials: { accessKeyId: "x", secretAccessKey: "x" },
+};
+
+beforeAll(() => connect(ddbCfg));
+
+afterEach(async () => {
+  /* Eliminar todas las tablas creadas por los tests */
+  const ddb = new DynamoDBClient(ddbCfg);
+  for (const e of wrapper.values()) {
+    try {
+      await ddb.send(new DeleteTableCommand({ TableName: e.name }));
+    } catch (_) {
+      /* tabla puede no existir */
+    }
+  }
+  wrapper.clear();
+});
+
+describe("CRUD Dinamite ORM (DynamoDB Local)", () => {
+  jest.setTimeout(10_000);
+
+  it("create → update → where → destroy", async () => {
+    @Name("crud_users1")
+    class User extends Table {
+      @PrimaryKey()
+      declare id: string;
+
+      @NotNull()
+      declare email: string;
+
+      @Default(() => new Date().toISOString())
+      declare created_at: string;
+    }
+
+    /* ---------- create (auto-crea tabla) ---------- */
+    const u1 = await User.create({ id: "u1", email: "a@b.com" });
+    expect(u1.email).toBe("a@b.com");
+
+    /* ---------- update ---------- */
+    await User.update("u1", { email: "c@d.com" });
+    const [after] = await User.where();
+    expect(after.email).toBe("c@d.com");
+
+    /* ---------- destroy ---------- */
+    await User.destroy("u1");
+    expect(await User.where()).toHaveLength(0);
+  });
+
+  it("where() devuelve [] si la tabla no existe", async () => {
+    @Name("ghosts")
+    class Ghost extends Table {
+      @PrimaryKey()
+      declare id: string;
+    }
+
+    const rows = await Ghost.where();
+    expect(rows).toEqual([]);
+  });
+});

package/__tests__/decorators.spec.ts

@@ -0,0 +1,134 @@
+/* __tests__/decorators.spec.ts
+ * -----------------------------------------------------------
+ * Suite para verificar todos los decoradores Dinamite ORM.
+ */
+
+import wrapper, { STORE } from "../src/core/wrapper";
+
+import CreatedAt from "../src/decorators/created_at";
+import Default from "../src/decorators/default";
+import Index from "../src/decorators/index";
+import IndexSort from "../src/decorators/index_sort";
+import Mutate from "../src/decorators/mutate";
+import Name from "../src/decorators/name";
+import NotNull from "../src/decorators/not_null";
+import PrimaryKey from "../src/decorators/primary_key";
+import UpdatedAt from "../src/decorators/updated_at";
+import Validate from "../src/decorators/validate";
+
+describe("Decoradores Dinamite ORM", () => {
+  beforeEach(() => wrapper.clear());
+
+  /* ---------------------------------------------------------- */
+  it("nombre de tabla por defecto (snake_plural) cuando no se usa @Name", () => {
+    class Book {
+      @NotNull()
+      declare title: string;
+    }
+    const meta = wrapper.get(Book)!;
+    expect(meta.name).toBe("books"); // Book → books
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@Name (clase y propiedad)", () => {
+    @Name("usuarios")
+    class User {
+      @Name("correo")
+      declare email: string;
+    }
+
+    const meta = wrapper.get(User)!;
+    expect(meta.name).toBe("usuarios");
+    expect(meta.columns.get("email")!.name).toBe("correo");
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@Index + @IndexSort (PK + SK)", () => {
+    class Post {
+      @Index() // Partition Key
+      declare slug: string;
+
+      @IndexSort() // Sort Key
+      declare created: string;
+    }
+
+    const meta = wrapper.get(Post)!;
+    const pkCol = meta.columns.get("slug")!;
+    const skCol = meta.columns.get("created")!;
+
+    expect(pkCol.index).toBe(true);
+    expect(skCol.indexSort).toBe(true);
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@PrimaryKey (combinado)", () => {
+    class Comment {
+      @PrimaryKey()
+      declare id: string;
+    }
+
+    const meta = wrapper.get(Comment)!;
+    const col = meta.columns.get("id")!;
+
+    expect(col.index).toBe(true);
+    expect(col.indexSort).toBe(true);
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@Default + @Mutate + @Validate pipeline", () => {
+    @Name("tests")
+    class Model {
+      @Default(() => 10)
+      @Mutate((v) => (v as number) * 2)
+      @Validate((v) => ((v as number) >= 20 ? true : "menor a 20"))
+      declare score: number;
+    }
+
+    const m = new Model();
+    (m as any).score = undefined; // dispara pipeline
+    expect(m.score).toBe(20);
+    expect((m as any)[STORE].score).toBe(20);
+
+    expect(() => {
+      m.score = 5 as any;
+    }).toThrow("menor a 20");
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@NotNull rechaza null/undefined/cadena vacía", () => {
+    class File {
+      @NotNull()
+      declare path: string;
+    }
+
+    const f = new File();
+    expect(() => ((f as any).path = null)).toThrow();
+    expect(() => ((f as any).path = " ")).toThrow();
+    f.path = "/tmp/file";
+    expect(f.path).toBe("/tmp/file");
+  });
+
+  /* ---------------------------------------------------------- */
+  it("@CreatedAt y @UpdatedAt gestionan timestamps", () => {
+    class Audit {
+      @CreatedAt()
+      declare created: string;
+
+      @UpdatedAt()
+      declare updated: string;
+    }
+
+    const a = new Audit();
+    (a as any).created = undefined;
+    (a as any).updated = undefined;
+
+    const firstCreated = a.created;
+    const firstUpdated = a.updated;
+
+    return new Promise((r) => setTimeout(r, 10)).then(() => {
+      (a as any).updated = undefined;
+      expect(a.created).toBe(firstCreated);
+      expect(a.updated).not.toBe(firstUpdated);
+    });
+  });
+});

package/__tests__/instance-crud.spec.ts

@@ -0,0 +1,86 @@
+/* __tests__/instance-crud.spec.ts
+ * ------------------------------------------------------------------
+ * CRUD usando métodos de **instancia** de Dinamite ORM con DynamoDB Local.
+ * Se asume que DynamoDB Local está corriendo en http://localhost:7007.
+ * ------------------------------------------------------------------ */
+import {
+  connect,
+  CreatedAt,
+  Name,
+  NotNull,
+  PrimaryKey,
+  Table,
+  UpdatedAt,
+} from "../src";
+
+// ---------- conexión DynamoDB Local ----------
+beforeAll(() =>
+  connect({
+    region: "local",
+    endpoint: "http://localhost:7007",
+    credentials: { accessKeyId: "x", secretAccessKey: "x" },
+  })
+);
+
+// ---------- Modelo de prueba ----------
+@Name("users")
+class User extends Table {
+  @PrimaryKey()
+  declare id: string;
+
+  @NotNull() // ← registra la columna en el wrapper
+  declare email: string;
+
+  @CreatedAt()
+  declare created: string;
+
+  @UpdatedAt()
+  declare updated: string;
+}
+
+describe("CRUD Dinamite ORM – instancia", () => {
+  it("where() antes de existir la tabla → []", async () => {
+    const rows = await User.where();
+    expect(rows).toEqual([]);
+  });
+
+  it("save() → crea, update() → modifica, destroy() → elimina", async () => {
+    /* ---------- save (create) ---------- */
+    const u = new User({ id: "u1", email: "a@b.com" });
+    await u.save();
+
+    let rows = await User.where();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].email).toBe("a@b.com");
+
+    const firstCreated = rows[0].created;
+    const firstUpdated = rows[0].updated;
+
+    /* ---------- update ---------- */
+    await u.update({ email: "c@d.com" });
+
+    rows = await User.where();
+    expect(rows[0].email).toBe("c@d.com");
+    expect(rows[0].updated).not.toBe(firstUpdated);
+    expect(rows[0].created).toBe(firstCreated);
+
+    /* ---------- destroy ---------- */
+    await u.destroy();
+
+    rows = await User.where();
+    expect(rows).toEqual([]);
+  });
+
+  it("la tabla realmente contiene el ítem mientras existe", async () => {
+    const u = new User({ id: "u2", email: "real@test.com" });
+    await u.save();
+
+    let rows = await User.where();
+    expect(rows.map((x) => x.id)).toContain("u2");
+
+    await u.destroy();
+
+    rows = await User.where();
+    expect(rows.map((x) => x.id)).not.toContain("u2");
+  });
+});

package/jest.config.ts

@@ -0,0 +1,23 @@
+// jest.config.ts
+import type { Config } from "@jest/types";
+
+const config: Config.InitialOptions = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/__tests__/**/*.spec.ts"],
+  collectCoverageFrom: ["src/**/*.ts"],
+  coverageDirectory: "coverage",
+  coverageReporters: ["text", "lcov"],
+  verbose: true,
+  clearMocks: true, // Limpia mocks automáticamente
+  transform: {
+    "^.+\\.tsx?$": "ts-jest",
+  },
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/src/$1",
+  },
+  // Ignorar node_modules y cobertura
+  testPathIgnorePatterns: ["/node_modules/", "/coverage/"],
+};
+
+export default config;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@arcaelas/dynamite",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "3.329.0",
+    "@aws-sdk/lib-dynamodb": "3.329.0",
+    "pluralize": "^8.0.0",
+    "uuid": "^11.1.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.6",
+    "jest": "^30.0.3",
+    "reflect-metadata": "^0.2.2",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}