@syllkom/hyper-db 1.0.1

package/README.md

@@ -0,0 +1,528 @@
+## 1. HyperDB
+
+**HyperDB** es una base de datos binaria, fragmentada (sharded) y orientada a documentos para Node.js. Su diseño se centra en el alto rendimiento, la ausencia de dependencias externas (Zero-dependency) y una experiencia de desarrollo fluida mediante el uso de `Proxy` de JavaScript.
+
+### ¿Para qué sirve?
+Sirve para almacenar estructuras de datos complejas y profundas sin cargar todo el conjunto de datos en memoria RAM. HyperDB divide automáticamente los objetos anidados en archivos binarios separados, cargándolos bajo demanda (Lazy Loading) y gestionando la memoria mediante un sistema LRU (Least Recently Used).
+
+### ¿A quién está dirigido?
+*   Desarrolladores de **Node.js** que requieren almacenamiento persistente local rápido.
+*   Proyectos que necesitan atomicidad en la escritura sin la complejidad de bases de datos SQL o NoSQL pesadas (como MongoDB).
+*   Sistemas embebidos o aplicaciones de escritorio (Electron) donde minimizar las dependencias es crítico.
+
+---
+
+## 2. Características Principales
+
+*   **Fragmentación Automática (Sharding):** Al guardar un objeto (`{}`) dentro de la base de datos, HyperDB lo detecta y automáticamente lo separa en su propio archivo binario (`.bin`), referenciándolo en el índice padre. Esto permite manejar bases de datos de gran tamaño sin saturar la memoria.
+*   **API Transparente (Proxy):** La interacción con la base de datos es idéntica a manipular un objeto JavaScript nativo (`db.data.usuario = "x"`). No requiere métodos `get()` o `set()` explícitos para el uso básico.
+*   **Serialización V8:** Utiliza el motor de serialización nativo de V8 (`v8.serialize/deserialize`), lo que lo hace significativamente más rápido y compacto que JSON.
+*   **Escritura Atómica:** Garantiza la integridad de los datos escribiendo primero en archivos temporales (`.tmp`) y renombrándolos al finalizar.
+*   **Gestión de Memoria (LRU Cache):** Incluye un gestor de memoria interno que descarga archivos poco utilizados cuando se supera un límite configurado (por defecto 20MB).
+*   **Debouncing de Escritura:** Agrupa múltiples operaciones de escritura en un corto periodo de tiempo para reducir el I/O en disco.
+*   **Zero-dependency:** No utiliza librerías de terceros, solo módulos nativos de Node.js (`fs`, `path`, `crypto`, `v8`).
+
+---
+
+## 3. Limitaciones Conocidas
+
+*   **Entorno:** Exclusivo para **Node.js (>= 18.0.0)** debido al uso de `fs/promises` y sintaxis moderna.
+*   **Tipos de Datos:** La fragmentación automática (creación de nuevos archivos) solo ocurre con objetos planos (`Plain Objects`). Instancias de clases personalizadas se serializan pero no generan nuevos fragmentos automáticamente a menos que se configure explícitamente.
+*   **Consultas Avanzadas:** No posee un motor de consultas integrado (como SQL `WHERE` o Mongo `find`). Las búsquedas requieren recorrer el objeto o implementar índices manuales.
+*   **Sincronía Aparente:** Aunque la API parece síncrona (asignación de variables), las escrituras en disco ocurren de forma asíncrona y diferida (debounced). Si el proceso de Node.js se mata abruptamente (SIGKILL) antes del *flush*, podrían perderse los últimos cambios en memoria (aunque el método `flush()` mitiga esto).
+
+---
+
+## 4. Instalación y Configuración
+
+### Requisitos Previos
+*   Node.js v18.0.0 o superior.
+
+### Instalación
+Dado que es un paquete local o git, se instala vía:
+
+```bash
+npm install git+https://github.com/Syllkom/HyperDB.git
+# O si tienes los archivos locales:
+npm install ./ruta-a-hyper-db
+```
+
+### Inicialización Básica
+Para iniciar la base de datos, se debe instanciar la clase `HyperDB`.
+
+```javascript
+import { HyperDB } from 'hyper-db';
+
+const db = new HyperDB({
+    folder: './mi_base_de_datos', // Carpeta donde se guardarán los archivos
+    memory: 50,                   // Límite de caché en MB
+    depth: 2,                     // Profundidad de carpetas para el sharding
+    index: { 
+        threshold: 10,            // Operaciones antes de forzar guardado del índice
+        debounce: 5000            // Tiempo de espera para guardar índice (ms)
+    },
+    nodes: { 
+        threshold: 5,             // Operaciones antes de forzar guardado de nodos
+        debounce: 3000            // Tiempo de espera para guardar nodos (ms)
+    }
+});
+```
+
+---
+
+## 5. Arquitectura y Mapas
+
+### Estructura de Archivos Generada
+HyperDB organiza los datos en una estructura jerárquica para evitar saturar un solo directorio.
+
+```text
+./mi_base_de_datos/
+├── index.bin          # Índice maestro (Entry point)
+├── root.bin           # Datos de la raíz
+└── data/              # Almacenamiento fragmentado
+    ├── A1/            # Carpetas generadas por ID (según profundidad)
+    │   └── B2C3.bin   # Archivo binario con datos de un sub-objeto
+    └── ...
+```
+
+### Flujo de Datos (Arquitectura)
+
+```mermaid
+graph TD
+    User[Usuario / App] -->|Operación get/set| Proxy[HyperDB Proxy]
+    Proxy -->|Intercepta| Cluster[Cluster Manager]
+    
+    subgraph "Lógica de Cluster"
+        Cluster -->|Es primitivo?| IndexData[Memoria Local]
+        Cluster -->|Es Objeto nuevo?| Shard[Shard Logic]
+    end
+    
+    Shard -->|Genera ID| ID_Gen[Crypto ID]
+    Shard -->|Serializa| V8[V8 Serializer]
+    
+    IndexData -->|Debounce Timer| FileMan[File Manager]
+    Shard -->|Write| Disk[Disk I/O]
+    
+    FileMan -->|Persiste| Disk
+    Disk -->|Cache| Memory[Memory LRU]
+    Disk -->|File System| FS[fs / fs.promises]
+```
+
+---
+
+## 6. Ejemplos de Uso
+
+### Caso 1: Escritura y Lectura Básica
+Este ejemplo muestra cómo guardar datos simples y cómo HyperDB los persiste.
+
+```javascript
+import { HyperDB } from 'hyper-db';
+
+const db = new HyperDB({ folder: './db' });
+
+// 1. Asignación directa (SET)
+// Esto escribe en memoria inmediatamente y programa la escritura en disco.
+db.data.nombre = "HyperDB";
+db.data.version = 1.0;
+
+// 2. Lectura (GET)
+console.log(db.data.nombre); // Salida: "HyperDB"
+```
+
+### Caso 2: Fragmentación Automática (Sharding)
+Al asignar un objeto, HyperDB crea un archivo separado. Esto es útil para listas de usuarios o datos masivos.
+
+```javascript
+// Al asignar un objeto, se crea un nuevo archivo binario en ./db/data/...
+// El índice principal solo guardará una referencia: { "configuracion": { "$file": "xx/xxxx.bin" } }
+db.data.configuracion = {
+    tema: "oscuro",
+    notificaciones: true,
+    limites: {
+        diario: 100
+    }
+};
+
+// Acceso transparente (Lazy Loading)
+// Al acceder a .configuracion, HyperDB carga el archivo correspondiente automáticamente.
+console.log(db.data.configuracion.tema); 
+```
+
+### Caso 3: Persistencia y Cierre
+Cómo asegurar que los datos se guarden antes de cerrar la aplicación.
+
+```javascript
+async function cerrarApp() {
+    console.log("Guardando datos...");
+    
+    // Fuerza la escritura de todos los procesos pendientes en el Pipe
+    await db.flush(); 
+    
+    console.log("Datos guardados. Saliendo.");
+    process.exit(0);
+}
+```
+
+### Caso 4: Gestión de Ramas (Flow & Proxy)
+Uso avanzado de la lógica de "Flow" para interceptar o manejar rutas específicas.
+
+```javascript
+// Obtener estadísticas de uso de memoria
+console.log(db.memory()); 
+// Salida: { used: "1.20 MB", limit: "20.00 MB", items: 5 }
+
+// Eliminar una propiedad (y su archivo asociado si era un shard)
+delete db.data.configuracion;
+// Esto elimina la referencia y, tras el proceso de 'prune' o limpieza, el archivo físico.
+```
+
+## 7. Referencia de API Interna
+
+Aunque la interacción principal es vía Proxy, estas clases componen el sistema:
+
+| Clase | Descripción |
+| :--- | :--- |
+| **HyperDB** | Fachada principal. Configura inyecciones de dependencias y expone `this.data`. |
+| **Disk** | Maneja I/O. Posee métodos `read`, `write`, `remove`. Usa colas (`Pipe`) para evitar colisiones de escritura. |
+| **Memory** | Caché LRU. Evita leer del disco si el objeto ya está cargado. |
+| **Shard** | Lógica de fragmentación. Decide cuándo y dónde crear nuevos archivos binarios (`forge`) y limpia referencias (`purge`). |
+| **Cluster** | Coordina el índice y los datos. Intercepta las escrituras para decidir si van al archivo actual o a un nuevo shard. |
+| **Flow** | Utilidad para manejar estructuras de árbol y referencias a Proxies activos. |
+
+---
+
+## 8. Configuración Detallada y Parámetros
+
+El constructor de `HyperDB` acepta un objeto de opciones complejo que permite afinar el comportamiento de la base de datos, desde la ubicación de los archivos hasta la agresividad del sistema de caché y escritura.
+
+### Estructura del Objeto `options`
+
+```javascript
+const options = {
+    folder: './data',   // Ruta base del almacenamiento
+    memory: 20,         // Límite de memoria en MB
+    depth: 2,           // Profundidad de subcarpetas para sharding
+    
+    // Configuración del Índice Principal (index.bin)
+    index: {
+        threshold: 10,  // Operaciones antes de escritura forzada
+        debounce: 5000  // Tiempo de espera (ms) para escritura diferida
+    },
+    
+    // Configuración de Nodos/Fragmentos (archivos .bin individuales)
+    nodes: {
+        threshold: 5,   // Operaciones antes de escritura forzada
+        debounce: 3000  // Tiempo de espera (ms) para escritura diferida
+    },
+
+    // Inyección de Dependencias (Avanzado)
+    $class: {
+        Disk: null,     // Clase o instancia personalizada para I/O
+        Index: null,    // Clase o instancia para gestión del índice
+        Flow: null,     // Clase o instancia para flujo de navegación
+        Cluster: null,  // Clase o instancia para gestión de clusters
+        Shard: null,    // Clase o instancia para lógica de sharding
+        Memory: null    // Clase o instancia para gestión de RAM
+    }
+};
+```
+
+### Explicación de Parámetros
+
+1.  **`folder`**: Define dónde se crearán los archivos. Si no existe, la clase `Disk` intentará crearla recursivamente.
+2.  **`memory`**: Define el "techo suave" (soft limit) del caché LRU en Megabytes. Si los objetos cargados superan este tamaño, los menos usados se eliminan de la RAM.
+3.  **`depth`**: Controla cómo se generan los IDs de los shards.
+    *   `depth: 0`: Todos los archivos se guardan planos en la carpeta `data`.
+    *   `depth: 2`: Se crea una estructura de carpetas basada en los primeros 2 caracteres del hash (ej. `data/A1/A1B2...bin`). Esto evita límites del sistema de archivos en directorios con miles de archivos.
+4.  **`threshold` (Umbral)**: Número de operaciones de escritura (`set` / `delete`) que ocurren en memoria antes de forzar una escritura física en disco.
+5.  **`debounce` (Retardo)**: Milisegundos que el sistema espera tras una escritura en memoria antes de guardar en disco si no se alcanza el umbral. *Reinicia el temporizador con cada nueva operación.*
+
+---
+
+## 9. Mecánica Interna de E/S (Disk & Memory)
+
+HyperDB implementa su propio sistema de gestión de archivos y memoria para garantizar rendimiento y consistencia.
+
+### Clase `Disk` (library/Disk.js)
+
+Es el motor de persistencia. Sus responsabilidades clave son:
+
+*   **Atomicidad (`write` / `writeSync`):**
+    Nunca sobrescribe un archivo directamente.
+    1.  Serializa los datos con `v8`.
+    2.  Escribe en un archivo temporal (`filename.bin.tmp`).
+    3.  Fuerza el volcado al disco físico (`fsync`).
+    4.  Renombra el temporal al nombre final. Esto previene corrupción de datos si el proceso falla a mitad de escritura.
+
+*   **Cola de Promesas (`Pipe`):**
+    Para evitar condiciones de carrera en operaciones asíncronas sobre el mismo archivo, `Disk` utiliza un `Map` llamado `Pipe`.
+    *   Si se solicitan 3 escrituras seguidas al mismo archivo, se encadenan en una promesa secuencial (`.then().then()`).
+
+*   **Mantenimiento (`prune`):**
+    Escanea recursivamente los directorios de datos. Si encuentra carpetas vacías (remanentes de shards eliminados), las borra para mantener el sistema de archivos limpio.
+
+### Clase `Memory` (library/Memory.js)
+
+Implementa un caché **LRU (Least Recently Used)** personalizado.
+
+*   **Cálculo de Tamaño:** Usa `v8.serialize(data).length` para estimar el peso real en bytes de los objetos.
+*   **Pinned Keys:** Ciertas claves críticas (como `index.bin` y `root.bin`) pueden marcarse como "pinned" para que nunca sean desalojadas del caché, garantizando que la estructura base siempre esté disponible.
+*   **Eviction Policy:** Cuando `currentSize + dataSize > limit`, elimina el elemento más antiguo (`cache.keys().next().value`) hasta tener espacio.
+
+---
+
+## 10. Lógica de Fragmentación y Clúster
+
+El corazón de la capacidad de escalar de HyperDB reside en la interacción entre `Cluster.js` y `Shard.js`.
+
+### El proceso de `forge` (Forjado)
+Cuando se asigna un objeto a una propiedad:
+
+1.  **Detección:** `Cluster` detecta que el valor es un objeto plano (`Plain Object`).
+2.  **Delegación:** Llama a `Shard.forge(index, value)`.
+3.  **Recursividad:** `Shard` recorre el objeto. Si encuentra sub-objetos anidados que también son *shardables*, los separa recursivamente.
+4.  **Generación de ID:** `Shard` genera un ID aleatorio hexadecimal (ej. `A1B2C3D4`) y calcula su ruta basada en la `depth`.
+5.  **Persistencia:** Escribe el contenido del objeto en el archivo `.bin` generado.
+6.  **Referencia:** Devuelve un objeto "puntero": `{ $file: "A1/A1B2C3D4.bin" }`.
+7.  **Actualización del Padre:** El objeto padre guarda solo el puntero, no los datos completos.
+
+### Diagrama de Flujo de Escritura (Cluster)
+
+```mermaid
+graph TD
+    Input["Set Key: Value"] --> Check{"Es Objeto?"}
+    Check -- No --> SaveDirect[Guardar valor en Index actual]
+    Check -- Sí --> ShardForge[Llamar a Shard.forge]
+    
+    ShardForge --> GenID[Generar ID Único]
+    ShardForge --> WriteFile[Escribir Value en ID.bin]
+    ShardForge --> ReturnRef["Retornar { $file: ID.bin }"]
+    
+    ReturnRef --> SaveDirect
+    SaveDirect --> CheckThres{"Contador >= Threshold?"}
+    
+    CheckThres -- Sí --> DiskWrite[Escribir Index en Disco ahora]
+    CheckThres -- No --> SetTimer[Iniciar Timer Debounce]
+    SetTimer -->|Timeout| DiskWrite
+```
+
+---
+
+## 11. Sistema de Flow y Proxies
+
+HyperDB utiliza `Proxy` de ES6 para interceptar todas las operaciones. La clase `Flow` y el mecanismo de `DB.js` gestionan la "navegación" por la base de datos.
+
+*   **Navegación Lazy:** Cuando accedes a `db.data.usuario.perfil`, el sistema no carga `perfil` hasta que lo tocas.
+*   **Apertura Dinámica:** Si el valor recuperado es un puntero `{ $file: "..." }`, el método `Proxy` en `DB.js` detecta esto, lee el archivo desde `Disk` (o `Memory`), crea un nuevo `Cluster` para ese archivo y devuelve un nuevo `Proxy` envolviendo esos datos.
+*   **Flow Tree:** La clase `Flow` mantiene un árbol paralelo de referencias. Esto permite inyectar lógica personalizada o metadatos en rutas específicas del árbol de datos sin contaminar los datos almacenados.
+
+---
+
+## 12. Inyección de Dependencias y Extensibilidad
+
+HyperDB permite reemplazar casi cualquiera de sus componentes internos pasando clases o instancias en el constructor. Esto es útil para testing (mocks) o para cambiar el comportamiento (ej. guardar en S3 en lugar de disco local).
+
+### Ejemplo: Reemplazar el almacenamiento (Mocking)
+
+Si quieres usar HyperDB puramente en memoria (sin escribir a disco) para pruebas unitarias:
+
+```javascript
+import { HyperDB, Disk } from 'hyper-db';
+
+// Creamos un Disk personalizado o configurado solo en memoria
+// Nota: La clase Disk original ya soporta esto si no se le da folder, 
+// pero aquí forzamos el comportamiento mediante inyección.
+
+class InMemoryDisk extends Disk {
+    write(filename, data) {
+        // Sobrescribir para no tocar 'fs'
+        this.memory.set(filename, data);
+        return Promise.resolve(true);
+    }
+    // ... implementar resto de métodos necesarios
+}
+
+const db = new HyperDB({
+    $class: {
+        Disk: new InMemoryDisk() 
+    }
+});
+```
+
+### Inyección de Funciones Compartidas
+El código en `DB.js` verifica `DB.shared`. Esto permite añadir métodos globales disponibles en cualquier nivel del proxy.
+
+```javascript
+// (Internamente en una versión modificada de HyperDB)
+this.shared = {
+    hola: function() { console.log("Hola desde", this.index.$file); }
+}
+
+// Uso:
+// db.data.users.hola() -> Imprime el archivo donde viven los usuarios
+```
+
+---
+
+## 13. Mantenimiento y Manejo de Errores
+
+### Manejo de Errores (`onError`)
+La clase `Disk` acepta un callback `onError`. Por defecto, imprime a `console.error`.
+
+```javascript
+const db = new HyperDB({
+    $class: {
+        Disk: new Disk({
+            onError: (err) => {
+                // Enviar a sistema de logs (Sentry, Datadog, etc.)
+                alertAdmin("Error crítico de IO en DB", err);
+            }
+        })
+    }
+});
+```
+
+### Limpieza de Archivos (`Prune`)
+Con el tiempo, al borrar objetos, pueden quedar carpetas vacías en la estructura de shards. El método `prune` las elimina.
+
+```javascript
+// Se recomienda ejecutar esto en tareas cron o al inicio/cierre
+await db.disk.prune();
+```
+
+### Recuperación de Fallos
+Si la aplicación se cierra inesperadamente (`SIGKILL`), los archivos `.tmp` pueden quedar en la carpeta de datos.
+*   **Al inicio:** HyperDB no limpia automáticamente los `.tmp`.
+*   **Integridad:** Dado que la operación de renombrado (`fs.rename`) es atómica en sistemas POSIX, el archivo `.bin` original estará intacto o será la nueva versión completa. No hay estados intermedios de archivo corrupto.
+
+---
+
+## Resumen de Archivos Fuente
+
+*   **`package.json`**: Metadatos y scripts (sin tests definidos).
+*   **`Disk.js`**: Capa física. `fs`, `v8`, `Pipe`, `Memory`.
+*   **`Memory.js`**: Capa lógica de caché. LRU, cálculo de tamaño.
+*   **`Shard.js`**: Lógica de particionado. Generación de IDs, purga recursiva.
+*   **`Flow.js`**: Utilidad de estructura de árbol para metadatos de navegación.
+*   **`DB.js`**: Entry point. Gestión de Proxies e Inyección de Dependencias.
+*   **`Cluster.js`**: Gestión de nodos. `Index`, `File` (debounce/threshold), `Cluster` (lógica get/set).
+*   **`index.js`**: Exportador de módulos.
+
+Aquí tienes la tercera y última parte de la documentación técnica de **HyperDB**. Esta sección cubre **Seguridad**, **Optimización de Rendimiento**, **Solución de Problemas** y una **Referencia Rápida de API**.
+
+---
+
+## 14. Consideraciones de Seguridad
+
+Dado que HyperDB opera directamente sobre el sistema de archivos local y utiliza serialización binaria, existen vectores de seguridad específicos que deben considerarse.
+
+### 1. Deserialización de Datos (`v8.deserialize`)
+HyperDB utiliza el motor nativo de V8 para serializar/deserializar datos.
+*   **Riesgo:** La deserialización de datos no confiables puede llevar a la ejecución de código arbitrario o comportamientos inestables si el archivo binario ha sido manipulado externamente.
+*   **Mitigación:** Asegúrese de que la carpeta de datos (`./data` por defecto) tenga permisos de escritura **exclusivos** para el usuario del sistema que ejecuta el proceso Node.js. Nunca apunte HyperDB a una carpeta donde usuarios externos puedan subir archivos.
+
+### 2. Permisos de Archivos (File System)
+HyperDB necesita permisos de lectura y escritura (`fs.read`, `fs.write`, `fs.mkdir`, `fs.rm`).
+*   **Requisito:** El proceso Node.js debe tener control total sobre el directorio raíz definido en `options.folder`.
+*   **Error Común:** Ejecutar la aplicación como `root` y luego como `user` puede causar errores de `EACCES` si los archivos fueron creados por `root`.
+
+### 3. Inyección de Dependencias
+La característica de inyección (`$class`) permite reemplazar componentes internos.
+*   **Precaución:** Si su aplicación permite configuración externa que se pasa directamente al constructor de `HyperDB`, un atacante podría inyectar clases maliciosas. Valide siempre el objeto `options` antes de pasarlo al constructor.
+
+---
+
+## 15. Guía de Rendimiento y Buenas Prácticas
+
+Para obtener el máximo rendimiento (High-Performance) prometido por HyperDB, siga estas directrices:
+
+### Estrategia de Sharding (Fragmentación)
+El sharding automático es potente, pero tiene un costo de I/O (crear archivo, abrir handle, escribir).
+
+*   **Cuándo usarlo:** Para objetos grandes o listas que crecen indefinidamente (ej. `db.data.usuarios`, `db.data.logs`).
+*   **Cuándo evitarlo:** Para objetos pequeños o de configuración (ej. `{ x: 1, y: 2 }`). Si un objeto tiene pocas propiedades primitivas, es mejor dejarlo dentro del archivo padre (`Index`) en lugar de aislarlo en un nuevo archivo.
+*   **Consejo:** HyperDB decide hacer shard si asignas un `Plain Object`. Si asignas primitivos (`string`, `number`), se quedan en el archivo actual.
+
+### Ajuste de Memoria (`Memory Limit`)
+*   **Escenario:** Servidor con mucha RAM.
+    *   **Acción:** Aumente `options.memory`. Por defecto es 20MB. Subirlo a 100MB o 500MB reducirá drásticamente las lecturas a disco, ya que más shards permanecerán "calientes" en RAM.
+*   **Escenario:** Entorno Serverless (AWS Lambda) o contenedores pequeños.
+    *   **Acción:** Mantenga el límite bajo (10-20MB) y reduzca `options.index.debounce` a valores cercanos a 0 o 100ms para asegurar que los datos se escriban antes de que la función se congele.
+
+### Uso de `flush()`
+Las operaciones de escritura son asíncronas y diferidas ("debounced").
+*   **Mejor Práctica:** Siempre llame a `await db.flush()` antes de finalizar el proceso o en puntos críticos de la lógica de negocio donde la persistencia inmediata es obligatoria.
+
+---
+
+## 16. Solución de Problemas Frecuentes
+
+### Problema: "Los cambios no se guardan al reiniciar"
+*   **Causa:** La aplicación se detuvo forzosamente (Crash o `SIGKILL`) antes de que el temporizador de *debounce* (por defecto 3-5 segundos) se disparara.
+*   **Solución:** Reduzca los tiempos de `debounce` en la configuración o asegúrese de capturar eventos de cierre (`process.on('SIGINT', ...)`) y llamar a `db.flush()`.
+
+### Problema: "Error: Invalid options"
+*   **Causa:** Se pasó `null`, `undefined` o un tipo no objeto al constructor.
+*   **Verificación:** Asegúrese de instanciar con `{}` como mínimo: `new HyperDB({})`.
+
+### Problema: Consumo excesivo de inodos en disco
+*   **Causa:** `depth: 0` con miles de objetos crea miles de archivos en una sola carpeta.
+*   **Solución:** Use `depth: 2` o superior en la configuración. Esto distribuye los archivos en subcarpetas (ej. `A1/B2/...`), lo cual es más amigable para sistemas de archivos como EXT4 o NTFS.
+
+### Problema: "Object exceeds cache limit"
+*   **Síntoma:** Advertencia en consola `[HyperDB:Memory] Object '...' exceeds cache limit`.
+*   **Causa:** Está intentando guardar un solo objeto (un solo shard) que es más grande que el límite total de memoria asignado a la DB.
+*   **Solución:** Aumente `options.memory` o divida ese objeto gigante en sub-objetos más pequeños para que HyperDB pueda fragmentarlo.
+
+---
+
+## 17. Referencia Rápida de API Pública
+
+Resumen de los métodos y propiedades expuestos para el desarrollador.
+
+### Constructor
+```javascript
+const db = new HyperDB(options);
+```
+Ver sección de configuración para detalles de `options`.
+
+### Propiedades
+*   **`db.data`**: (Proxy) El punto de entrada principal para leer y escribir datos. Se comporta como un objeto JS estándar.
+*   **`db.disk`**: (Instancia de `Disk`) Acceso directo a operaciones de archivo (bajo nivel).
+*   **`db.index`**: (Instancia de `Index`) Acceso al gestor del archivo índice raíz.
+
+### Métodos
+*   **`db.open(...path)`**: 
+    *   *Descripción:* Abre manualmente una ruta específica y devuelve un Proxy para ese nodo.
+    *   *Uso:* `const userConfig = db.open('users', 'id_123', 'config');`
+*   **`db.flush()`**: 
+    *   *Descripción:* Fuerza la escritura de todas las operaciones pendientes en la cola (`Pipe`) y espera a que terminen.
+    *   *Retorno:* `Promise<true>`
+*   **`db.memory()`**: 
+    *   *Descripción:* Devuelve estadísticas del uso de memoria actual.
+    *   *Retorno:* `{ used: string, limit: string, items: number }`
+*   **`delete db.data.propiedad`**: 
+    *   *Descripción:* Elimina la clave y, eventualmente, purga el archivo asociado del disco.
+
+### Métodos Internos (Accesibles vía `db.disk`)
+*   **`db.disk.prune()`**: 
+    *   *Async.* Escanea y elimina carpetas vacías en el directorio de datos.
+
+---
+
+## 18. Comparativa Técnica
+
+Para entender dónde encaja HyperDB:
+
+| Característica | HyperDB | JSON (fs.writeFile) | SQLite | MongoDB |
+| :--- | :--- | :--- | :--- | :--- |
+| **Formato** | Binario (V8) Fragmentado | Texto Plano (Monolítico) | Binario (Relacional) | Binario (BSON) |
+| **Carga en RAM** | **Lazy (Solo lo necesario)** | Todo el archivo | Paginada | Paginada |
+| **Escritura** | Atómica y Parcial | Reescribe todo el archivo | Transaccional (SQL) | Documento |
+| **Dependencias** | **Cero (Nativo)** | Cero | `sqlite3` (binding C++) | Driver + Servidor |
+| **Consultas** | Traversal (JS nativo) | Array methods | SQL | Query Language |
+| **Uso Ideal** | Config, Estado local, Grafos de objetos | Config simple | Datos tabulares | Big Data / Cloud |
+
+**Conclusión:** HyperDB es ideal cuando JSON se queda corto por rendimiento/memoria, pero SQLite es excesivo o demasiado rígido (schemas) para la estructura de datos dinámica que maneja la aplicación.
+
+---

package/index.js

@@ -0,0 +1,17 @@
+import { HyperDB } from './library/DB.js';
+import { Shard } from './library/Shard.js';
+import { File, Index, Cluster } from './library/Cluster.js';
+import { Flow } from './library/Flow.js';
+import { Memory } from './library/Memory.js';
+import { Disk } from './library/Disk.js';
+
+export {
+    HyperDB,
+    Shard,
+    File,
+    Index,
+    Cluster,
+    Flow,
+    Memory,
+    Disk
+}

package/library/Cluster.js

@@ -0,0 +1,161 @@
+import { Shard } from "./Shard.js";
+
+export class File {
+    #count = 0;
+    #timer = null;
+    constructor(disk, file, options = {}) {
+        this.file = file;
+        this.disk = disk;
+
+        this._limit = options.limit ?? 10;
+        this._delay = options.delay ?? 5000;
+    }
+
+    get data() {
+        if (this.disk.existsSync(this.file)) {
+            return this.disk.readSync(this.file);
+        } else {
+            this.disk.writeSync(this.file, {});
+            return this.disk.readSync(this.file)
+        }
+    }
+
+    save(force = false) {
+        if (force || ++this.#count >= this._limit) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+            this.#count = 0;
+            return this.disk.write(this.file, this.data);
+        }
+
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => this.save(true), this._delay);
+    }
+}
+
+export class Index {
+    constructor(disk, options = {}) {
+        this.disk = disk;
+
+        if (options?.$class?.File) {
+            const a0 = options.$class.File;
+            if (a0.constructor.name === 'Array') {
+                this.file = new File(disk, 'index.bin', ...a0);
+            } else if (a0.constructor.name === 'Object') {
+                this.file = new File(disk, 'index.bin', a0);
+            } else this.file = a0;
+        }
+
+        if (!this.file) {
+            this.file = new File(disk, 'index.bin', {
+                limit: options?.file?.limit || 10,
+                delay: options.file?.delay || 5000
+            });
+        }
+
+        this.data = this.file.data;
+        if (!this.data.$file) {
+            this.data.$file = 'root.bin';
+            this.save();
+        }
+    }
+
+    get(...args) {
+        return args.reduce((acc, k) => acc?.[k], this.data) ?? false;
+    }
+
+    save() {
+        return this.file.save();
+    }
+}
+
+export class Cluster {
+    constructor(disk, indexMap, options = {}) {
+        this.disk = disk;
+        this.indexMap = indexMap;
+
+        if (options.$class?.Shard) {
+            const a0 = options.$class.Shard;
+            if (a0.constructor.name === 'Array') {
+                this.shard = new Shard(disk, ...a0);
+            } else if (a0.constructor.name === 'Number') {
+                this.shard = new Shard(disk, a0);
+            } else this.shard = a0;
+        }
+
+        if (options?.$class?.File) {
+            const a0 = options.$class.File;
+            if (a0.constructor.name === 'Array') {
+                this.file = new File(disk, this.indexMap.$file, ...a0);
+            } else if (a0.constructor.name === 'Object') {
+                this.file = new File(disk, this.indexMap.$file, a0);
+            } else this.file = a0;
+        }
+
+        if (!this.shard) {
+            this.shard = new Shard(disk, options?.shard?.depth || 2);
+        }
+
+        if (!this.file) {
+            this.file = new File(disk, this.indexMap.$file, {
+                limit: options?.file?.limit || 5,
+                delay: options.file?.delay || 3000
+            });
+        }
+    }
+
+    get data() {
+        return this.file.data;
+    }
+
+    get(key) {
+        const value = this.data[key];
+        if (typeof value === 'string' && value.endsWith('.bin')) {
+            if (!this.indexMap[key]) this.indexMap[key] = { $file: value };
+            return { $file: value }
+        }
+        return value;
+    }
+
+    set(key, value) {
+        if (this.indexMap[key]) {
+            this.shard.purge(this.indexMap[key]);
+            delete this.indexMap[key];
+        }
+
+        let isObject = false;
+        if (value && typeof value === 'object') {
+            const proto = Object.getPrototypeOf(value);
+            isObject = (proto === Object.prototype || proto === null);
+        }
+
+        if (isObject) {
+            let tmpIndex = {}
+            const file = this.shard.forge(tmpIndex, value);
+
+            if (file) {
+                this.indexMap[key] = tmpIndex;
+                this.data[key] = file;
+            } else {
+                return false;
+            }
+        } else {
+            this.data[key] = value;
+        }
+
+        this.file.save();
+    }
+
+    delete(key) {
+        if (this.indexMap[key]) {
+            this.shard.purge(this.indexMap[key]);
+            delete this.indexMap[key];
+        }
+        delete this.data[key];
+        this.file.save();
+    }
+
+    keys() {
+        return Object.keys(this.data);
+    }
+}

package/library/DB.js

@@ -0,0 +1,222 @@
+import { Disk } from "./Disk.js";
+import { Index, Cluster } from "./Cluster.js";
+import { Flow } from "./Flow.js";
+
+/* Uso:
+new HyperDB({
+    depth: 2,
+    folder: './storage/database',
+    memory: 20,
+    index: { threshold: 10, debounce: 5000 },
+    nodes: { threshold: 5, debounce: 3000 }
+})
+*/
+
+export class HyperDB {
+    #options = null;
+    constructor(options = {}) {
+        if (options?.constructor?.name !== 'Object') {
+            throw new Error('Invalid options');
+        }
+
+        this.#options = options;
+
+        // Inyección de dependencias: Disk
+        if (options.$class?.Disk) {
+            const a0 = options.$class.Disk;
+            if (a0.constructor.name == 'Array') {
+                this.disk = new Disk(...a0);
+            } else if (a0.constructor.name == 'Object') {
+                this.disk = new Disk(a0);
+            } else this.disk = a0
+        }
+
+        if (!this.disk) {
+            this.disk = new Disk({
+                memory: { limit: options.memory || 20 },
+                folder: options.folder || './data',
+            });
+        }
+
+        // Inyección de dependencias: Index
+        if (options.$class?.Index) {
+            const a0 = options.$class.Index;
+            if (a0.constructor.name == 'Array') {
+                this.index = new Index(this.disk, ...a0);
+            } else if (a0.constructor.name == 'Object') {
+                this.index = new Index(this.disk, a0);
+            } else this.index = a0
+        }
+
+        if (!this.index) {
+            this.index = new Index(this.disk, {
+                file: {
+                    limit: options.index?.threshold || 10,
+                    delay: options.index?.debounce || 5000
+                }
+            })
+        }
+
+        // Inyección de dependencias: Flow
+        if (options.$class?.Flow) {
+            const a0 = options.$class.Flow;
+            if (a0.constructor.name == 'Array') {
+                this.flow = new Flow(...a0);
+            } else this.flow = a0
+        }
+
+        if (!this.flow) {
+            this.flow = new Flow();
+        }
+
+        /////////////////////////////
+
+        this.proxies = new WeakMap();
+        this.flows = new WeakMap();
+
+        this.data = this.Proxy(this.index.data);
+        this.shared = {}
+    }
+
+    memory() {
+        return this.disk.memory.stats()
+    }
+
+    flush() {
+        return this.disk.flush()
+    }
+
+    open(...path) {
+        const o = this.index.get(...path)
+        const router = this.flow.get(...path)
+        if (o && o.$file) return this.Proxy(o, router)
+        return false
+    }
+
+    Proxy(index, flow) {
+        const DB = this
+        if (!index) index = this.index.data;
+        if (index.$file == 'root.bin') flow = this.flow.tree
+
+        if (flow) this.flows.set(index, flow);
+        if (this.proxies.has(index)) return this.proxies.get(index);
+
+        let root = null;
+
+        // Inyección de dependencias: Cluster
+        if (this.#options?.$class?.Cluster) {
+            const a0 = this.#options.$class.Cluster;
+            if (a0.constructor.name === 'Array') {
+                root = new Cluster(this.disk, index, ...a0);
+            } else if (a0.constructor.name === 'Object') {
+                root = new Cluster(this.disk, index, a0);
+            } else root = a0;
+        }
+
+        if (!root) root = new Cluster(this.disk, index, {
+            shard: { depth: this.#options?.depth || 2 },
+            file: {
+                limit: this.#options?.nodes?.threshold || 5,
+                delay: this.#options?.nodes?.debounce || 3000
+            }
+        });
+
+        ////////////////////////////
+
+        const open = (args, index, flow) => {
+            const Open = (object) => () => args.reduce((acc, k) => acc?.[k], object) ?? false;
+            const $index = Open(index)();
+            const $flow = Open(flow)();
+            if ($index && $index.$file) return this.Proxy($index, $flow)
+        }
+
+        const guard = (method) => (...args) => {
+            if (flow?.$proxy && flow?.$proxy?.[method]) {
+                let control = { end: false, value: null, error: null };
+                const receiver = (method === 'delete') ? null : args[args.length - 1];
+
+                flow.$proxy[method].apply({
+                    resolve: (val) => { control.end = true; control.value = val },
+                    reject: (err) => { control.end = true; control.error = err },
+                    open: (...args) => open(args, index, flow),
+                    data: receiver, index: index, flow: flow,
+                }, args);
+
+                return control
+            }
+        }
+
+        const proxy = new Proxy({}, {
+            get(target, key, receiver) {
+                if (typeof key === 'symbol') return Reflect.get(target, key);
+
+                const flow = DB.flows.get(index);
+
+                // Flow logic
+                if (flow?.$call && flow?.$call?.[key]) {
+                    const fun = flow.$call[key];
+                    if (typeof fun === 'function') {
+                        return (...args) => fun.apply({
+                            data: receiver, index: index, flow: flow,
+                            open: (...args) => open(args, index, flow),
+                            DB: DB
+                        }, args);
+                    }
+                } else if (DB.shared[key]) {
+                    const fun = DB.shared[key];
+                    if (typeof fun === 'function') {
+                        return (...args) => fun.apply({
+                            data: receiver, index: index, flow: flow,
+                            open: (...args) => open(args, index, flow),
+                            DB: DB
+                        }, args);
+                    }
+                }
+
+                const r = guard('get')(target, key, receiver);
+                if (r?.end && r?.error) throw r.error;
+                if (r?.end) return r.value;
+
+                // Index logic
+                const rootGet = root.get(key);
+
+                if (rootGet?.constructor?.name === 'Object' && rootGet.$file) {
+                    return DB.Proxy(index[key], flow?.[key]);
+                } else {
+                    return rootGet;
+                }
+            },
+            set(target, key, value, receiver) {
+                const r = guard('set')(target, key, value, receiver);
+                if (r?.end && r?.error) throw r.error;
+                if (r?.end) return r.value;
+
+                root.set(key, value);
+                DB.index.save();
+                return true;
+            },
+            deleteProperty(target, key) {
+                const r = guard('delete')(target, key);
+                if (r?.end && r?.error) throw r.error;
+                if (r?.end) return r.value;
+
+                root.delete(key);
+                DB.index.save();
+                return true;
+            },
+            ownKeys(target) {
+                return root.keys();
+            },
+            getOwnPropertyDescriptor(_, key) {
+                return {
+                    enumerable: true,
+                    configurable: true,
+                    value: root.get(key)
+                };
+            }
+        })
+
+        this.proxies.set(index, proxy);
+        return proxy;
+    }
+}

package/library/Disk.js

@@ -0,0 +1,178 @@
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import v8 from 'v8';
+
+import { Memory } from './Memory.js';
+
+export class Disk {
+    constructor(options = {}) {
+        if (options.constructor.name !== 'Object')
+            throw new Error('Invalid options');
+
+        if (options?.$class?.Memory) {
+            const a0 = options.$class.Memory;
+            if (a0.constructor.name == 'Array') {
+                this.memory = new Memory(...a0);
+            } else this.memory = a0
+        }
+
+        if (!options.folder) options.folder = './data';
+
+        if (!this.memory) this.memory = new Memory(
+            options.memory?.limit || 20,
+            ['index.bin', 'root.bin']);
+
+        this.onError = options.onError || ((err) =>
+            console.error(`[HyperDB_IO_Error]:`, err));
+
+        this.Pipe = new Map();
+        this.basePath = path.resolve(options.folder);
+        this.dataPath = path.join(this.basePath, 'data');
+        this.files = ['index.bin', 'root.bin']
+
+        if (!fs.existsSync(this.basePath)) fs.mkdirSync(this.basePath, { recursive: true });
+        if (!fs.existsSync(this.dataPath)) fs.mkdirSync(this.dataPath, { recursive: true });
+    }
+
+    #path(filename) {
+        if (!this.files.includes(filename))
+            return path.join(this.dataPath, filename);
+        return path.join(this.basePath, filename);
+    }
+
+    ////////////////////// Sync Methods
+
+    readSync(filename) {
+        const cached = this.memory.get(filename);
+        if (cached) return cached;
+
+        const filePath = this.#path(filename);
+        try {
+            const buffer = fs.readFileSync(filePath);
+            const data = v8.deserialize(buffer);
+            this.memory.set(filename, data);
+            return data;
+        } catch (e) {
+            this.onError(e);
+            return null;
+        }
+    }
+
+    writeSync(filename, data = {}) {
+        const filePath = this.#path(filename);
+        try {
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+            const tempPath = filePath + '.tmp';
+            const buffer = v8.serialize(data);
+            const fd = fs.openSync(tempPath, 'w');
+            fs.writeSync(fd, buffer);
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fs.renameSync(tempPath, filePath);
+            this.memory.set(filename, data);
+            return true;
+        } catch (e) {
+            this.onError(e);
+            return false;
+        }
+    }
+
+    removeSync(filename) {
+        const filePath = this.#path(filename);
+        try {
+            if (fs.existsSync(filePath)) fs.rmSync(filePath, { recursive: true, force: true });
+            this.memory.delete(filename);
+            return true;
+        } catch (e) {
+            this.onError(e);
+            return false;
+        }
+    }
+
+    existsSync(filename) {
+        if (this.memory.has(filename)) return true;
+        return fs.existsSync(this.#path(filename));
+    }
+
+    ////////////////////// Async Methods
+
+    async #pipe(filename, action) {
+        const next = (this.Pipe.get(filename) || Promise.resolve())
+            .then(() => action().catch((e) => this.onError(e))).finally(() =>
+                (this.Pipe.get(filename) === next) ? this.Pipe.delete(filename) : false);
+        return this.Pipe.set(filename, next).get(filename);
+    }
+
+    async read(filename) {
+        const cached = this.memory.get(filename);
+        if (cached) return cached;
+
+        return this.#pipe(filename, async () => {
+            const filePath = this.#path(filename);
+            try {
+                const buffer = await fsp.readFile(filePath);
+                const data = v8.deserialize(buffer);
+                this.memory.set(filename, data);
+                return data;
+            } catch (e) {
+                return null;
+            }
+        });
+    }
+
+    async write(filename, data = {}) {
+        this.memory.set(filename, data);
+        return this.#pipe(filename, async () => {
+            const filePath = this.#path(filename);
+            const dir = path.dirname(filePath);
+            await fsp.mkdir(dir, { recursive: true });
+            const tempPath = filePath + '.tmp';
+            const buffer = v8.serialize(data);
+            const handle = await fsp.open(tempPath, 'w');
+            await handle.write(buffer);
+            await handle.sync();
+            await handle.close();
+            await fsp.rename(tempPath, filePath);
+            return true;
+        });
+    }
+
+    async remove(filename) {
+        this.memory.delete(filename);
+        return this.#pipe(filename, async () => {
+            const filePath = this.#path(filename);
+            await fsp.rm(filePath, { recursive: true, force: true });
+            return true;
+        });
+    }
+
+    async exists(filename) {
+        if (this.memory.has(filename)) return true;
+        try {
+            await fsp.access(this.#path(filename));
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async flush() {
+        await Promise.all(this.Pipe.values());
+        return true;
+    }
+
+    async prune() {
+        return this.#pipe('__maint__', async () => {
+            const scan = async (d) => {
+                const items = await fsp.readdir(d, { withFileTypes: true });
+                for (const i of items) if (i.isDirectory()) await scan(path.join(d, i.name));
+                if (d !== this.dataPath && d !== this.basePath && !(await fsp.readdir(d)).length)
+                    await fsp.rmdir(d).catch(() => null);
+            };
+            if (fs.existsSync(this.dataPath)) await scan(this.dataPath);
+        });
+    }
+}

package/library/Flow.js

@@ -0,0 +1,34 @@
+export class Flow {
+    constructor() {
+        this.tree = {};
+    }
+
+    forge(...args) {
+        const val = args.pop();
+        return args.reduceRight((acc, key) => ({ [key]: acc }), val);
+    }
+
+    get(...args) {
+        return args.reduce((acc, k) => acc?.[k], this.tree) ?? false;
+    }
+
+    set(...args) {
+        const val = args.pop();
+        const target = args.reduce((acc, k) => acc[k] ??= {}, this.tree);
+        const merge = (t, s) => Object.keys(s).forEach(k =>
+            (s[k] instanceof Object && k in t) ? merge(t[k], s[k]) : t[k] = s[k]);
+        merge(target, val);
+    }
+
+    delete(...args) {
+        const del = (obj, [k, ...rest]) => {
+            if (!obj?.[k]) return false;
+            const success = rest.length ? del(obj[k], rest)
+                : (delete obj[k].$proxy, delete obj[k].$call, true);
+            if (success && !Object.keys(obj[k]).length)
+                delete obj[k];
+            return success;
+        };
+        return del(this.tree, args);
+    }
+}

package/library/Memory.js

@@ -0,0 +1,78 @@
+import v8 from 'v8';
+
+export class Memory {
+    constructor(limitMB = 20, pinnedKeys = []) {
+        this.limit = limitMB * 1024 * 1024;
+        this.pinnedKeys = new Set(pinnedKeys);
+        this.pinned = new Map();
+        this.cache = new Map();
+        this.currentSize = 0;
+    }
+
+    #size(data) {
+        try {
+            return v8.serialize(data).length;
+        } catch (e) {
+            return 0;
+        }
+    }
+
+    set(key, data) {
+        if (this.pinnedKeys.has(key)) {
+            this.pinned.set(key, data);
+            return true;
+        }
+
+        if (this.cache.has(key)) this.delete(key);
+        
+        const dataSize = this.#size(data);
+        if (dataSize > this.limit) {
+            console.warn(`[HyperDB:Memory] Object '${key}' exceeds cache limit (${(this.limit / 1024 / 1024).toFixed(2)} MB)`);
+            return false;
+        }
+
+        while (this.currentSize + dataSize > this.limit && this.cache.size > 0) {
+            const oldestKey = this.cache.keys().next().value;
+            this.delete(oldestKey);
+        }
+        
+        this.cache.set(key, { data, size: dataSize });
+        this.currentSize += dataSize;
+        return true;
+    }
+
+    get(key) {
+        if (this.pinned.has(key)) return this.pinned.get(key);
+
+        const item = this.cache.get(key);
+        if (!item) return null;
+        
+        // Refresh LRU
+        const data = item.data;
+        this.cache.delete(key);
+        this.cache.set(key, item);
+        return data;
+    }
+
+    delete(key) {
+        if (this.pinned.has(key)) return this.pinned.delete(key);
+
+        const item = this.cache.get(key);
+        if (!item) return false
+        this.currentSize -= item.size;
+        this.cache.delete(key);
+        return true;
+    }
+
+    stats() {
+        return {
+            used: (this.currentSize / 1024 / 1024).toFixed(2) + " MB",
+            limit: (this.limit / 1024 / 1024).toFixed(2) + " MB",
+            items: this.cache.size
+        };
+    }
+
+    has(key) {
+        return this.pinned.has(key) || this.cache.has(key);
+    }
+}

package/library/Shard.js

@@ -0,0 +1,51 @@
+import crypto from 'crypto';
+
+export const genId = (depth) => {
+    const id = crypto.randomBytes(4).toString('hex').toUpperCase();
+    if (!depth || depth <= 0) return `${id}.bin`
+    const folder = id.substring(0, depth);
+    return `${folder}/${id}.bin`;
+};
+
+function isShardable(val) {
+    if (!val || typeof val !== 'object') return false;
+    const proto = Object.getPrototypeOf(val);
+    return proto === Object.prototype || proto === null;
+}
+
+export class Shard {
+    constructor(disk, depth) {
+        this.disk = disk;
+        this.depth = depth;
+    }
+
+    purge(index) {
+        if (index.$file) this.disk.remove(index.$file);
+        for (const key in index) {
+            if (key === '$file') continue;
+            if (index[key] && typeof index[key] === 'object')
+                this.purge(index[key]);
+        }
+    }
+
+    forge(index, value, file) {
+        try {
+            const Id = file || genId(this.depth);
+            value = structuredClone(value);
+            index.$file = Id;
+
+            for (const key in value) {
+                 if (!isShardable(value[key])) continue;
+                 
+                index[key] = {};
+                value[key] = this.forge(index[key], value[key]);
+            }
+
+            this.disk.write(Id, value);
+            return Id;
+        } catch (e) {
+            this.disk.onError(e.message);
+            return null
+        }
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@syllkom/hyper-db",
+  "version": "1.0.1",
+  "description": "High-performance sharded binary database for Node.js. Zero-dependency, atomic I/O, and transparent Proxy state management.",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "library/**/*"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syllkom/HyperDB.git"
+  },
+  "keywords": [
+    "hyper-db",
+    "database",
+    "sharding",
+    "nosql",
+    "binary-storage",
+    "v8-serialization",
+    "high-performance",
+    "proxy",
+    "atomic-write",
+    "embedded",
+    "zero-dependency"
+  ],
+  "author": "Syllkom",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Syllkom/HyperDB/issues"
+  },
+  "homepage": "https://github.com/Syllkom/HyperDB#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}