metal-orm 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -44,7 +44,8 @@
     "pg": "^8.0.0",
     "sqlite3": "^5.1.6",
     "tedious": "^19.0.0",
-    "keyv": "^5.6.0"
+    "keyv": "^5.6.0",
+    "ioredis": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {
@@ -61,6 +62,9 @@
     },
     "keyv": {
       "optional": true
+    },
+    "ioredis": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -70,6 +74,8 @@
     "@vitest/ui": "^4.0.18",
     "eslint": "^9.39.2",
     "express": "^5.2.1",
+    "ioredis": "^5.6.1",
+    "ioredis-mock": "^8.9.0",
     "keyv": "^5.6.0",
     "mysql-memory-server": "^1.14.0",
     "mysql2": "^3.16.2",

package/src/cache/adapters/keyv-cache-adapter.ts

@@ -19,6 +19,11 @@ interface KeyvInstance {
  */
 export class KeyvCacheAdapter implements CacheProvider {
   readonly name = 'keyv';
+  readonly capabilities = {
+    tags: false,
+    prefix: true,
+    ttl: true,
+  };
 
   constructor(private keyv: KeyvInstance) {}
 

package/src/cache/adapters/memory-cache-adapter.ts

@@ -11,6 +11,11 @@ interface CacheEntry<T> {
  */
 export class MemoryCacheAdapter implements CacheProvider {
   readonly name = 'memory';
+  readonly capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true,
+  };
   private storage: Map<string, CacheEntry<unknown>> = new Map();
   private tagIndex: Map<string, Set<string>> = new Map();
 

package/src/cache/adapters/redis-cache-adapter.ts

@@ -0,0 +1,233 @@
+import type { CacheProvider } from '../cache-interfaces.js';
+
+// Tipos mínimos para ioredis (para evitar dependência obrigatória)
+interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: (string | number)[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  sadd(key: string, ...members: string[]): Promise<number>;
+  smembers(key: string): Promise<string[]>;
+  srem(key: string, ...members: string[]): Promise<number>;
+  scan(cursor: string | number, ...args: (string | number)[]): Promise<[string, string[]]>;
+  quit(): Promise<string>;
+  disconnect(): void;
+  isReady?: boolean;
+  status?: string;
+}
+
+interface RedisOptions {
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  keyPrefix?: string;
+  lazyConnect?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Adapter para Redis usando ioredis
+ * 
+ * Suporta:
+ * - Tags via Redis Sets (SADD, SMEMBERS, SREM)
+ * - Prefix invalidation via SCAN
+ * - TTL nativo do Redis
+ * 
+ * Instalação:
+ * npm install ioredis
+ * 
+ * Para testes (dev):
+ * npm install --save-dev ioredis-mock
+ */
+export class RedisCacheAdapter implements CacheProvider {
+  readonly name = 'redis';
+  readonly capabilities = {
+    tags: true,
+    prefix: true,
+    ttl: true,
+  };
+
+  private redis: RedisLike;
+  private ownsConnection: boolean;
+  private tagPrefix: string;
+
+  /**
+   * 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: RedisLike | RedisOptions,
+    options?: { tagPrefix?: string }
+  ) {
+    this.tagPrefix = options?.tagPrefix ?? 'tag:';
+    
+    if (this.isRedisInstance(redis)) {
+      // Recebeu uma instância existente
+      this.redis = redis;
+      this.ownsConnection = false;
+    } else {
+      // Recebeu opções, precisa criar a conexão
+      this.redis = this.createRedis(redis);
+      this.ownsConnection = true;
+    }
+  }
+
+  private isRedisInstance(obj: unknown): obj is RedisLike {
+    return (
+      typeof obj === 'object' &&
+      obj !== null &&
+      'get' in obj &&
+      'set' in obj &&
+      'del' in obj &&
+      typeof (obj as RedisLike).get === 'function'
+    );
+  }
+
+  private createRedis(options: RedisOptions): RedisLike {
+    // Dynamic import para evitar dependência obrigatória
+    try {
+      const Redis = require('ioredis');
+      return new Redis(options) as RedisLike;
+    } catch {
+      throw new Error(
+        'ioredis is required for RedisCacheAdapter. ' +
+        'Install it with: npm install ioredis'
+      );
+    }
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const value = await this.redis.get(key);
+    if (value === null) {
+      return undefined;
+    }
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.redis.get(key);
+    return value !== null;
+  }
+
+  async set<T>(
+    key: string,
+    value: T,
+    ttlMs?: number,
+    tags?: string[]
+  ): Promise<void> {
+    const serialized = JSON.stringify(value);
+    
+    if (ttlMs) {
+      // EX = seconds, PX = milliseconds
+      await this.redis.set(key, serialized, 'PX', ttlMs);
+    } else {
+      await this.redis.set(key, serialized);
+    }
+
+    // Registra tags se fornecidas
+    if (tags && tags.length > 0) {
+      await this.registerTags(key, tags);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+
+  async invalidate(key: string): Promise<void> {
+    await this.delete(key);
+  }
+
+  async invalidateTags(tags: string[]): Promise<void> {
+    const keysToDelete = new Set<string>();
+
+    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);
+      }
+      
+      // Deleta o set da tag
+      await this.redis.del(tagKey);
+    }
+
+    // Deleta todas as chaves associadas
+    if (keysToDelete.size > 0) {
+      await this.redis.del(...Array.from(keysToDelete));
+    }
+  }
+
+  async invalidatePrefix(prefix: string): Promise<void> {
+    const keysToDelete: string[] = [];
+    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) {
+      // Deleta em batches de 1000 para evitar bloqueio
+      const batchSize = 1000;
+      for (let i = 0; i < keysToDelete.length; i += batchSize) {
+        const batch = keysToDelete.slice(i, i + batchSize);
+        await this.redis.del(...batch);
+      }
+    }
+  }
+
+  private async registerTags(key: string, tags: string[]): Promise<void> {
+    for (const tag of tags) {
+      const tagKey = `${this.tagPrefix}${tag}`;
+      await this.redis.sadd(tagKey, key);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.ownsConnection) {
+      try {
+        await this.redis.quit();
+      } catch {
+        // Se quit falhar, tenta disconnect
+        this.redis.disconnect?.();
+      }
+    }
+  }
+
+  /**
+   * Retorna a instância Redis subjacente
+   * Útil para operações avançadas ou health checks
+   */
+  getRedis(): RedisLike {
+    return this.redis;
+  }
+}

package/src/cache/cache-interfaces.ts

@@ -27,11 +27,22 @@ export interface CacheInvalidator {
   invalidatePrefix(prefix: string): Promise<void>;
 }
 
+/**
+ * Capabilities de um cache provider
+ * Permite detectar funcionalidades suportadas em runtime
+ */
+export interface CacheCapabilities {
+  tags: boolean;
+  prefix: boolean;
+  ttl: boolean;
+}
+
 /**
  * Interface completa para implementações full-featured
  */
 export interface CacheProvider extends CacheReader, CacheWriter, CacheInvalidator {
   readonly name: string;
+  readonly capabilities: CacheCapabilities;
   dispose?(): Promise<void>;
 }
 

package/src/cache/index.ts

@@ -4,6 +4,7 @@ export type {
   CacheWriter,
   CacheInvalidator,
   CacheProvider,
+  CacheCapabilities,
   Duration,
   CacheOptions,
   InvalidationStrategy,
@@ -20,6 +21,7 @@ export { DefaultCacheStrategy } from './strategies/default-cache-strategy.js';
 // Adapters
 export { MemoryCacheAdapter } from './adapters/memory-cache-adapter.js';
 export { KeyvCacheAdapter } from './adapters/keyv-cache-adapter.js';
+export { RedisCacheAdapter } from './adapters/redis-cache-adapter.js';
 
 // Manager
 export { QueryCacheManager } from './query-cache-manager.js';

package/src/core/ast/expression-builders.ts

@@ -24,10 +24,13 @@ import {
   CollateExpressionNode
 } from './expression-nodes.js';
 
-export type LiteralValue = LiteralNode['value'];
-export type ValueOperandInput = OperandNode | LiteralValue;
-
-export type TypedLike<T> = { tsType?: T } | { __tsType: T };
+export type LiteralValue = LiteralNode['value'];
+export type ValueOperandInput = OperandNode | LiteralValue;
+type ScalarComparable = string | number | boolean | Date | Buffer | null;
+type OrderedComparable = string | number | Date | Buffer;
+type NotArray<T> = T extends readonly unknown[] ? never : T;
+
+export type TypedLike<T> = { tsType?: T } | { __tsType: T };
 
 /**
  * Type guard to check if a value is a literal value
@@ -68,20 +71,27 @@ const columnRefToNode = (col: ColumnRef): ColumnNode => {
  * @param value - Value to convert (OperandNode, ColumnRef, or literal value)
  * @returns OperandNode representing the value
  */
-const toOperandNode = (value: OperandNode | ColumnRef | LiteralValue): OperandNode => {
-  // Already an operand node
-  if (isOperandNode(value)) {
-    return value;
-  }
+const toOperandNode = (value: OperandNode | ColumnRef | LiteralValue): OperandNode => {
+  // Already an operand node
+  if (isOperandNode(value)) {
+    return value;
+  }
 
   // Literal value
-  if (isLiteralValue(value)) {
-    return toLiteralNode(value);
-  }
-
-  // Must be ColumnRef
-  return columnRefToNode(value as ColumnRef);
-};
+  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.'
+    );
+  }
+
+  // Must be ColumnRef
+  return columnRefToNode(value as ColumnRef);
+};
 
 /**
  * Converts a primitive or existing operand into an operand node
@@ -151,12 +161,12 @@ export const aliasRef = (name: string): AliasRefNode => ({
  */
 export const correlateBy = (table: string, column: string): ColumnNode => outerRef({ name: column, table });
 
-const createBinaryExpression = (
-  operator: SqlOperator,
-  left: OperandNode | ColumnRef,
-  right: OperandNode | ColumnRef | string | number | boolean | null,
-  escape?: string
-): BinaryExpressionNode => {
+const createBinaryExpression = (
+  operator: SqlOperator,
+  left: OperandNode | ColumnRef,
+  right: OperandNode | ColumnRef | LiteralValue,
+  escape?: string
+): BinaryExpressionNode => {
   const node: BinaryExpressionNode = {
     type: 'BinaryExpression',
     left: toOperandNode(left),
@@ -187,11 +197,11 @@ const createBinaryExpression = (
  * // With strict typing (typescript will error if types mismatch)
  * eq(users.firstName, 'Ada');
  */
-export function eq<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function eq(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean): BinaryExpressionNode;
-export function eq(left: OperandNode | ColumnRef | TypedLike<unknown>, right: OperandNode | ColumnRef | string | number | boolean | TypedLike<unknown>): BinaryExpressionNode {
-  return createBinaryExpression('=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number | boolean);
-}
+export function eq<T extends ScalarComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function eq<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function eq(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a not equal expression (`left != right`).
@@ -203,14 +213,11 @@ export function eq(left: OperandNode | ColumnRef | TypedLike<unknown>, right: Op
  * @example
  * neq(users.status, 'inactive');
  */
-export function neq<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function neq(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean): BinaryExpressionNode;
-export function neq(
-  left: OperandNode | ColumnRef | TypedLike<unknown>,
-  right: OperandNode | ColumnRef | string | number | boolean | TypedLike<unknown>
-): BinaryExpressionNode {
-  return createBinaryExpression('!=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number | boolean);
-}
+export function neq<T extends ScalarComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function neq<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function neq(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('!=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a greater-than expression (`left > right`).
@@ -222,11 +229,11 @@ export function neq(
  * @example
  * gt(users.age, 18);
  */
-export function gt<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function gt(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
-export function gt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: OperandNode | ColumnRef | string | number | TypedLike<unknown>): BinaryExpressionNode {
-  return createBinaryExpression('>', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number);
-}
+export function gt<T extends OrderedComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function gt<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function gt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('>', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a greater-than-or-equal expression (`left >= right`).
@@ -238,11 +245,11 @@ export function gt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: Op
  * @example
  * gte(users.score, 100);
  */
-export function gte<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function gte(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
-export function gte(left: OperandNode | ColumnRef | TypedLike<unknown>, right: OperandNode | ColumnRef | string | number | TypedLike<unknown>): BinaryExpressionNode {
-  return createBinaryExpression('>=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number);
-}
+export function gte<T extends OrderedComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function gte<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function gte(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('>=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a less-than expression (`left < right`).
@@ -254,11 +261,11 @@ export function gte(left: OperandNode | ColumnRef | TypedLike<unknown>, right: O
  * @example
  * lt(inventory.stock, 5);
  */
-export function lt<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function lt(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
-export function lt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: OperandNode | ColumnRef | string | number | TypedLike<unknown>): BinaryExpressionNode {
-  return createBinaryExpression('<', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number);
-}
+export function lt<T extends OrderedComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function lt<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function lt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('<', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a less-than-or-equal expression (`left <= right`).
@@ -270,11 +277,11 @@ export function lt(left: OperandNode | ColumnRef | TypedLike<unknown>, right: Op
  * @example
  * lte(products.price, 50.00);
  */
-export function lte<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
-export function lte(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
-export function lte(left: OperandNode | ColumnRef | TypedLike<unknown>, right: OperandNode | ColumnRef | string | number | TypedLike<unknown>): BinaryExpressionNode {
-  return createBinaryExpression('<=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | string | number);
-}
+export function lte<T extends OrderedComparable>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+export function lte<T>(left: OperandNode | ColumnRef, right: T & NotArray<T>): BinaryExpressionNode;
+export function lte(left: OperandNode | ColumnRef | TypedLike<unknown>, right: unknown): BinaryExpressionNode {
+  return createBinaryExpression('<=', left as OperandNode | ColumnRef, right as OperandNode | ColumnRef | LiteralValue);
+}
 
 /**
  * Creates a `LIKE` pattern matching expression.