metal-orm 1.1.1 → 1.1.3

package/README.md

@@ -110,8 +110,10 @@ Full docs live in the `docs/` folder:
 - **Table-valued functions**: use the new `tvf(key, …)` helper when you want portable intents such as `ARRAY_UNNEST`, letting the dialects’ `TableFunctionStrategy` renderers emit dialect-specific syntax (`LATERAL`/`WITH ORDINALITY`, alias validation, quoting, etc.). `fnTable()` remains available as the raw escape hatch when you need to emit a specific SQL function directly.
 - **String helpers**: `lower`, `upper`, `trim`, `ltrim/rtrim`, `concat/concatWs`, `substr/left/right`, `position/instr/locate`, `replace`, `repeat`, `lpad/rpad`, `space`, and more with dialect-aware rendering.
 - **Set operations**: `union`, `unionAll`, `intersect`, `except` across all dialects (ORDER/LIMIT apply to the combined result; hydration is disabled for compound queries so rows are returned as-is without collapsing duplicates).
-- **Expression builders**: `eq`, `and`, `or`, `between`, `inList`, `exists`, `jsonPath`, `caseWhen`, window functions like `rowNumber`, `rank`, `lag`, `lead`, etc., all backed by typed AST nodes.
-- **Relation-aware hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.) using a hydration plan derived from the AST metadata.
+- **Expression builders**: `eq`, `and`, `or`, `between`, `inList`, `exists`, `jsonPath`, `caseWhen`, window functions like `rowNumber`, `rank`, `lag`, `lead`, etc., all backed by typed AST nodes.
+- **Operator safety**: scalar operators (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`) are for single values; for arrays, use `inList`/`notInList`.
+  - Migration example: `where(eq(tipoAcao.columns.codigo, codigos))` -> `where(inList(tipoAcao.columns.codigo, codigos))`.
+- **Relation-aware hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.) using a hydration plan derived from the AST metadata.
 - **Multi-dialect**: compile once, run on MySQL/MariaDB, PostgreSQL, SQLite, or SQL Server via pluggable dialects.
 - **DML**: type-safe INSERT / UPDATE / DELETE with `RETURNING` where supported.
 
@@ -129,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).
@@ -193,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,
@@ -202,6 +203,7 @@ __export(index_exports, {
   eq: () => eq,
   esel: () => esel,
   exclude: () => exclude,
+  executeFilteredPaged: () => executeFilteredPaged,
   executeHydrated: () => executeHydrated,
   executeHydratedPlain: () => executeHydratedPlain,
   executeHydratedPlainWithContexts: () => executeHydratedPlainWithContexts,
@@ -802,6 +804,11 @@ var toOperandNode = (value) => {
   if (isLiteralValue(value)) {
     return toLiteralNode(value);
   }
+  if (Array.isArray(value)) {
+    throw new Error(
+      "Array operands are not supported in scalar comparisons. Use inList/notInList for array matching."
+    );
+  }
   return columnRefToNode(value);
 };
 var valueToOperand = (value) => {
@@ -14003,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) {
@@ -16208,6 +16220,129 @@ function computePaginationMetadata(totalItems, page, pageSize) {
   };
 }
 
+// src/dto/execute-filtered-paged.ts
+var normalizeSortBy = (sortBy) => {
+  if (!sortBy) {
+    return void 0;
+  }
+  const normalized = sortBy.trim();
+  return normalized.length > 0 ? normalized : void 0;
+};
+var detectPrimaryKeyName = (table) => {
+  const pk = Object.values(table.columns).find((column) => column.primary);
+  return pk?.name;
+};
+var toColumnNode = (table, name) => ({
+  type: "Column",
+  table: table.name,
+  name
+});
+var getColumnByName = (table, name) => {
+  return Object.values(table.columns).find((column) => column.name === name);
+};
+var resolveSortTermFromAllowed = (sortBy, allowedSortColumns) => {
+  if (!allowedSortColumns) {
+    throw new Error("allowedSortColumns is required when sortBy/defaultSortBy is provided.");
+  }
+  const term = allowedSortColumns[sortBy];
+  if (term) {
+    return term;
+  }
+  const allowedKeys = Object.keys(allowedSortColumns);
+  throw new Error(
+    `Invalid sortBy "${sortBy}". Allowed values: ${allowedKeys.length > 0 ? allowedKeys.join(", ") : "(none)"}.`
+  );
+};
+var resolvePrimarySort = (table, sortBy, sortDirection, allowedSortColumns, defaultSortBy, defaultSortDirection) => {
+  const requestedSortBy = normalizeSortBy(sortBy);
+  if (requestedSortBy) {
+    return {
+      term: resolveSortTermFromAllowed(requestedSortBy, allowedSortColumns),
+      direction: sortDirection ?? ORDER_DIRECTIONS.ASC
+    };
+  }
+  const configuredDefaultSortBy = normalizeSortBy(defaultSortBy);
+  if (configuredDefaultSortBy) {
+    return {
+      term: resolveSortTermFromAllowed(configuredDefaultSortBy, allowedSortColumns),
+      direction: defaultSortDirection ?? ORDER_DIRECTIONS.ASC
+    };
+  }
+  const detectedPkName = detectPrimaryKeyName(table);
+  if (detectedPkName) {
+    const detectedPkColumn = getColumnByName(table, detectedPkName);
+    if (detectedPkColumn) {
+      return {
+        term: detectedPkColumn,
+        direction: ORDER_DIRECTIONS.ASC
+      };
+    }
+  }
+  const idColumn = getColumnByName(table, "id");
+  return {
+    term: idColumn ?? toColumnNode(table, "id"),
+    direction: ORDER_DIRECTIONS.ASC
+  };
+};
+var resolveTieBreaker = (table, tieBreakerColumn) => {
+  const configuredName = normalizeSortBy(tieBreakerColumn);
+  if (configuredName) {
+    const configuredColumn = getColumnByName(table, configuredName);
+    if (!configuredColumn) {
+      throw new Error(
+        `Invalid tieBreakerColumn "${configuredName}" for table "${table.name}".`
+      );
+    }
+    return configuredColumn;
+  }
+  const idColumn = getColumnByName(table, "id");
+  if (idColumn) {
+    return idColumn;
+  }
+  const detectedPkName = detectPrimaryKeyName(table);
+  if (detectedPkName) {
+    const detectedPkColumn = getColumnByName(table, detectedPkName);
+    if (detectedPkColumn) {
+      return detectedPkColumn;
+    }
+  }
+  return toColumnNode(table, "id");
+};
+var extractSortColumnName = (term) => {
+  if (typeof term === "object" && term !== null && "name" in term && typeof term.name === "string") {
+    return term.name;
+  }
+  return void 0;
+};
+var executeFilteredPaged = async (options) => {
+  const table = options.qb.getTable();
+  const primarySort = resolvePrimarySort(
+    table,
+    options.sortBy,
+    options.sortDirection,
+    options.allowedSortColumns,
+    options.defaultSortBy,
+    options.defaultSortDirection
+  );
+  const tieBreaker = resolveTieBreaker(table, options.tieBreakerColumn);
+  let qb = applyFilter(
+    options.qb,
+    options.tableOrEntity,
+    options.filters
+  );
+  qb = qb.orderBy(primarySort.term, primarySort.direction);
+  const primarySortColumnName = extractSortColumnName(primarySort.term);
+  const tieBreakerColumnName = extractSortColumnName(tieBreaker);
+  if (primarySortColumnName !== tieBreakerColumnName) {
+    qb = qb.orderBy(tieBreaker, ORDER_DIRECTIONS.ASC);
+  }
+  const result = await qb.executePaged(options.session, {
+    page: options.page,
+    pageSize: options.pageSize
+  });
+  return toPagedResponse(result);
+};
+
 // src/dto/openapi/type-mappings.ts
 var IntegerTypeStrategy = class {
   types = ["INT", "INTEGER"];
@@ -18733,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);
   }
@@ -18776,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();
@@ -18930,6 +19216,7 @@ var TagIndex = class {
   PrimaryKey,
   PrototypeMaterializationStrategy,
   QueryCacheManager,
+  RedisCacheAdapter,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
@@ -19043,6 +19330,7 @@ var TagIndex = class {
   eq,
   esel,
   exclude,
+  executeFilteredPaged,
   executeHydrated,
   executeHydratedPlain,
   executeHydratedPlainWithContexts,