metal-orm 1.1.2 → 1.1.3

package/README.md

@@ -131,7 +131,7 @@ On top of the query builder, MetalORM ships a focused runtime managed by `Orm` a
 - **Lazy, batched relations**: `user.posts.load()`, `user.roles.syncByIds([...])`, etc.
 - **Scoped transactions**: `session.transaction(async s => { ... })` wraps `begin/commit/rollback` on the existing executor; `Orm.transaction` remains available when you want a fresh transactional executor per call.
 - **Identity map**: the same row becomes the same entity instance within a session (see the [Identity map pattern](https://en.wikipedia.org/wiki/Identity_map_pattern)).
-- **Caching**: Flexible caching with `MemoryCacheAdapter` (dev) or `KeyvCacheAdapter` (Redis, etc.). Features human-readable TTL (`'30m'`, `'2h'`), tag-based invalidation, and multi-tenant cache isolation.
+- **Caching**: Flexible caching with `MemoryCacheAdapter` (dev), `KeyvCacheAdapter` (simple production), or `RedisCacheAdapter` (full-featured with tag support). Features human-readable TTL (`'30m'`, `'2h'`), tag-based invalidation, and multi-tenant cache isolation.
 - **Tree Behavior (Nested Set/MPTT)**: hierarchical data with `TreeManager`, `treeQuery()`, and `@Tree` decorators. Efficient O(log n) operations for moves, inserts, and deletes. Supports multi-tree scoping, recovery, and validation.
 - **DTO/OpenAPI helpers**: the `metal-orm/dto` module generates DTOs and OpenAPI schemas, including tree schemas (`TreeNode`, `TreeNodeResult`, threaded trees).
 - **Unit of Work (`OrmSession`)** tracking New/Dirty/Removed entities and relation changes, inspired by the classic [Unit of Work pattern](https://en.wikipedia.org/wiki/wiki/Unit_of_work).
@@ -195,15 +195,24 @@ Pick the matching dialect (`MySqlDialect`, `SQLiteDialect`, `PostgresDialect`, `
 
 > Drivers are declared as optional peer dependencies. Install only the ones you actually use in your project.
 
-**Optional: Caching Backend**
+**Optional: Caching Backends**
 
-For production caching with Redis or other stores:
+For production caching, choose based on your needs:
+
+| Adapter | Tags | Install | Use Case |
+|---------|------|---------|----------|
+| `RedisCacheAdapter` | ✅ Full support | `npm install ioredis` | Production with tag invalidation |
+| `KeyvCacheAdapter` | ❌ Not supported | `npm install keyv @keyv/redis` | Simple production setups |
 
 ```bash
+# For full-featured Redis (recommended)
+npm install ioredis
+
+# For simple Keyv-based caching
 npm install keyv @keyv/redis
 ```
 
-> The `keyv` package is optional. MetalORM includes `MemoryCacheAdapter` for development without external dependencies.
+> Caching packages are optional peer dependencies. MetalORM includes `MemoryCacheAdapter` for development without external dependencies.
 
 ### Playground (optional) 🧪
 

package/dist/index.cjs

@@ -89,6 +89,7 @@ __export(index_exports, {
   PrimaryKey: () => PrimaryKey,
   PrototypeMaterializationStrategy: () => PrototypeMaterializationStrategy,
   QueryCacheManager: () => QueryCacheManager,
+  RedisCacheAdapter: () => RedisCacheAdapter,
   RelationKinds: () => RelationKinds,
   STANDARD_COLUMN_TYPES: () => STANDARD_COLUMN_TYPES,
   SelectQueryBuilder: () => SelectQueryBuilder,
@@ -14009,6 +14010,11 @@ function isValidDuration(value) {
 // src/cache/adapters/memory-cache-adapter.ts
 var MemoryCacheAdapter = class {
   name = "memory";
+  capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true
+  };
   storage = /* @__PURE__ */ new Map();
   tagIndex = /* @__PURE__ */ new Map();
   async get(key) {
@@ -18862,6 +18868,11 @@ var KeyvCacheAdapter = class {
     this.keyv = keyv;
   }
   name = "keyv";
+  capabilities = {
+    tags: false,
+    prefix: true,
+    ttl: true
+  };
   async get(key) {
     return this.keyv.get(key);
   }
@@ -18905,6 +18916,152 @@ var KeyvCacheAdapter = class {
   }
 };
 
+// src/cache/adapters/redis-cache-adapter.ts
+var RedisCacheAdapter = class {
+  name = "redis";
+  capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true
+  };
+  redis;
+  ownsConnection;
+  tagPrefix;
+  /**
+   * Cria um adapter Redis
+   * 
+   * @param redis - Instância do ioredis OU opções de conexão
+   * @param options - Opções adicionais
+   * @param options.tagPrefix - Prefixo para chaves de tag (default: 'tag:')
+   * 
+   * Exemplos:
+   * 
+   * // Com instância existente (recomendado para connection pooling):
+   * const redis = new Redis({ host: 'localhost', port: 6379 });
+   * const adapter = new RedisCacheAdapter(redis);
+   * 
+   * // Com opções (adapter gerencia conexão):
+   * const adapter = new RedisCacheAdapter({ host: 'localhost', port: 6379 });
+   * 
+   * // Para testes com ioredis-mock:
+   * import Redis from 'ioredis-mock';
+   * const adapter = new RedisCacheAdapter(new Redis());
+   */
+  constructor(redis, options) {
+    this.tagPrefix = options?.tagPrefix ?? "tag:";
+    if (this.isRedisInstance(redis)) {
+      this.redis = redis;
+      this.ownsConnection = false;
+    } else {
+      this.redis = this.createRedis(redis);
+      this.ownsConnection = true;
+    }
+  }
+  isRedisInstance(obj) {
+    return typeof obj === "object" && obj !== null && "get" in obj && "set" in obj && "del" in obj && typeof obj.get === "function";
+  }
+  createRedis(options) {
+    try {
+      const Redis = require("ioredis");
+      return new Redis(options);
+    } catch {
+      throw new Error(
+        "ioredis is required for RedisCacheAdapter. Install it with: npm install ioredis"
+      );
+    }
+  }
+  async get(key) {
+    const value = await this.redis.get(key);
+    if (value === null) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+  async has(key) {
+    const value = await this.redis.get(key);
+    return value !== null;
+  }
+  async set(key, value, ttlMs, tags) {
+    const serialized = JSON.stringify(value);
+    if (ttlMs) {
+      await this.redis.set(key, serialized, "PX", ttlMs);
+    } else {
+      await this.redis.set(key, serialized);
+    }
+    if (tags && tags.length > 0) {
+      await this.registerTags(key, tags);
+    }
+  }
+  async delete(key) {
+    await this.redis.del(key);
+  }
+  async invalidate(key) {
+    await this.delete(key);
+  }
+  async invalidateTags(tags) {
+    const keysToDelete = /* @__PURE__ */ new Set();
+    for (const tag of tags) {
+      const tagKey = `${this.tagPrefix}${tag}`;
+      const keys = await this.redis.smembers(tagKey);
+      for (const key of keys) {
+        keysToDelete.add(key);
+      }
+      await this.redis.del(tagKey);
+    }
+    if (keysToDelete.size > 0) {
+      await this.redis.del(...Array.from(keysToDelete));
+    }
+  }
+  async invalidatePrefix(prefix) {
+    const keysToDelete = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.redis.scan(
+        cursor,
+        "MATCH",
+        `${prefix}*`,
+        "COUNT",
+        100
+      );
+      cursor = nextCursor;
+      keysToDelete.push(...keys);
+    } while (cursor !== "0");
+    if (keysToDelete.length > 0) {
+      const batchSize = 1e3;
+      for (let i = 0; i < keysToDelete.length; i += batchSize) {
+        const batch = keysToDelete.slice(i, i + batchSize);
+        await this.redis.del(...batch);
+      }
+    }
+  }
+  async registerTags(key, tags) {
+    for (const tag of tags) {
+      const tagKey = `${this.tagPrefix}${tag}`;
+      await this.redis.sadd(tagKey, key);
+    }
+  }
+  async dispose() {
+    if (this.ownsConnection) {
+      try {
+        await this.redis.quit();
+      } catch {
+        this.redis.disconnect?.();
+      }
+    }
+  }
+  /**
+   * Retorna a instância Redis subjacente
+   * Útil para operações avançadas ou health checks
+   */
+  getRedis() {
+    return this.redis;
+  }
+};
+
 // src/cache/tag-index.ts
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
@@ -19059,6 +19216,7 @@ var TagIndex = class {
   PrimaryKey,
   PrototypeMaterializationStrategy,
   QueryCacheManager,
+  RedisCacheAdapter,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,