metal-orm 1.0.118 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.118",
+  "version": "1.1.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -43,7 +43,8 @@
     "mysql2": "^3.9.0",
     "pg": "^8.0.0",
     "sqlite3": "^5.1.6",
-    "tedious": "^19.0.0"
+    "tedious": "^19.0.0",
+    "keyv": "^5.6.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {
@@ -57,6 +58,9 @@
     },
     "tedious": {
       "optional": true
+    },
+    "keyv": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -66,6 +70,7 @@
     "@vitest/ui": "^4.0.18",
     "eslint": "^9.39.2",
     "express": "^5.2.1",
+    "keyv": "^5.6.0",
     "mysql-memory-server": "^1.14.0",
     "mysql2": "^3.16.2",
     "pg": "^8.17.2",

package/src/cache/adapters/index.ts

@@ -0,0 +1,2 @@
+export { MemoryCacheAdapter } from './memory-cache-adapter.js';
+export { KeyvCacheAdapter } from './keyv-cache-adapter.js';

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

@@ -0,0 +1,81 @@
+import type { CacheProvider } from '../cache-interfaces.js';
+
+/**
+ * Interface mínima para Keyv
+ * Usa unknown para permitir diferentes versões do Keyv
+ */
+interface KeyvInstance {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<boolean | void>;
+  delete(key: string): Promise<boolean>;
+  iterator?: unknown;
+  disconnect?(): Promise<void>;
+}
+
+/**
+ * Adapter para Keyv (Redis, SQLite, etc.)
+ * Keyv deve ser instalado separadamente:
+ * npm install keyv @keyv/redis
+ */
+export class KeyvCacheAdapter implements CacheProvider {
+  readonly name = 'keyv';
+
+  constructor(private keyv: KeyvInstance) {}
+
+  async get<T>(key: string): Promise<T | undefined> {
+    return this.keyv.get(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.keyv.get(key);
+    return value !== undefined;
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    await this.keyv.set(key, value, ttlMs);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.keyv.delete(key);
+  }
+
+  async invalidate(key: string): Promise<void> {
+    await this.delete(key);
+  }
+
+  async invalidateTags(_tags: string[]): Promise<void> {
+    // Keyv não suporta invalidação por tags nativamente
+    // Para suporte completo, usar RedisTagProvider
+    throw new Error(
+      'Keyv adapter does not support tag invalidation. ' +
+      'Use MemoryCacheAdapter for testing or implement a custom Redis provider.'
+    );
+  }
+
+  async invalidatePrefix(prefix: string): Promise<void> {
+    // Tenta usar iterador se disponível (Redis)
+    if (typeof this.keyv.iterator === 'function') {
+      const keys: string[] = [];
+      for await (const [key] of this.keyv.iterator()) {
+        if (key.startsWith(prefix)) {
+          keys.push(key);
+        }
+      }
+      
+      if (keys.length > 0) {
+        await Promise.all(keys.map(k => this.keyv.delete(k)));
+      }
+      return;
+    }
+
+    // Fallback: não suportado
+    throw new Error(
+      'Keyv adapter does not support prefix invalidation in this store. ' +
+      'Consider using a store with iterator support.'
+    );
+  }
+
+  async dispose(): Promise<void> {
+    await this.keyv.disconnect?.();
+  }
+}

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

@@ -0,0 +1,127 @@
+import type { CacheProvider } from '../cache-interfaces.js';
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt?: number;
+}
+
+/**
+ * Implementação em memória do cache provider
+ * Útil para testes e ambientes de desenvolvimento
+ */
+export class MemoryCacheAdapter implements CacheProvider {
+  readonly name = 'memory';
+  private storage: Map<string, CacheEntry<unknown>> = new Map();
+  private tagIndex: Map<string, Set<string>> = new Map();
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const entry = this.storage.get(key);
+    
+    if (!entry) {
+      return undefined;
+    }
+
+    // Verifica expiração
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      await this.delete(key);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.get(key);
+    return value !== undefined;
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    const entry: CacheEntry<T> = {
+      value,
+      expiresAt: ttlMs ? Date.now() + ttlMs : undefined,
+    };
+
+    this.storage.set(key, entry);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.storage.delete(key);
+    // Remove do índice de tags
+    for (const [tag, keys] of this.tagIndex) {
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagIndex.delete(tag);
+      }
+    }
+  }
+
+  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 keys = this.tagIndex.get(tag);
+      if (keys) {
+        for (const key of keys) {
+          keysToDelete.add(key);
+        }
+        this.tagIndex.delete(tag);
+      }
+    }
+
+    for (const key of keysToDelete) {
+      this.storage.delete(key);
+    }
+  }
+
+  async invalidatePrefix(prefix: string): Promise<void> {
+    const keysToDelete: string[] = [];
+
+    for (const key of this.storage.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+
+    for (const key of keysToDelete) {
+      await this.delete(key);
+    }
+  }
+
+  /**
+   * Registra uma chave com tags (para invalidação)
+   */
+  registerTags(key: string, tags: string[]): void {
+    for (const tag of tags) {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, new Set());
+      }
+      this.tagIndex.get(tag)!.add(key);
+    }
+  }
+
+  /**
+   * Limpa todo o cache
+   */
+  clear(): void {
+    this.storage.clear();
+    this.tagIndex.clear();
+  }
+
+  /**
+   * Retorna estatísticas do cache
+   */
+  getStats(): { size: number; tags: number } {
+    return {
+      size: this.storage.size,
+      tags: this.tagIndex.size,
+    };
+  }
+
+  async dispose(): Promise<void> {
+    this.clear();
+  }
+}

package/src/cache/cache-interfaces.ts

@@ -0,0 +1,70 @@
+/**
+ * Interfaces segregadas para cache (ISP - Interface Segregation Principle)
+ */
+
+/**
+ * Leitura de cache - pode ser implementada por read-replicas
+ */
+export interface CacheReader {
+  get<T>(key: string): Promise<T | undefined>;
+  has(key: string): Promise<boolean>;
+}
+
+/**
+ * Escrita em cache - pode ser implementada por write-nodes
+ */
+export interface CacheWriter {
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Invalidação em massa - separada pois nem todo cache suporta tags
+ */
+export interface CacheInvalidator {
+  invalidate(key: string): Promise<void>;
+  invalidateTags(tags: string[]): Promise<void>;
+  invalidatePrefix(prefix: string): Promise<void>;
+}
+
+/**
+ * Interface completa para implementações full-featured
+ */
+export interface CacheProvider extends CacheReader, CacheWriter, CacheInvalidator {
+  readonly name: string;
+  dispose?(): Promise<void>;
+}
+
+/**
+ * TTL human-readable: '1d', '2h', '30m', '15s', '1w'
+ * Ou número em milissegundos
+ */
+export type Duration = number | `${number}${'s'|'m'|'h'|'d'|'w'}`;
+
+/**
+ * Opções de cache para uma query
+ */
+export interface CacheOptions {
+  key: string;
+  ttl: Duration;
+  tags?: string[];
+  autoInvalidate?: boolean;
+  condition?: (result: unknown) => boolean;
+}
+
+/**
+ * Estratégias de invalidação disponíveis
+ */
+export type InvalidationStrategy = 
+  | 'tags'
+  | 'entity'
+  | 'prefix'
+  | 'key'
+  | 'ttl';
+
+/**
+ * Estado interno do cache no query builder
+ */
+export interface CacheState {
+  options?: CacheOptions;
+}

package/src/cache/duration-utils.ts

@@ -0,0 +1,82 @@
+import type { Duration } from './cache-interfaces.js';
+
+/**
+ * Multiplicadores para converter unidades de tempo em milissegundos
+ */
+const DURATION_MULTIPLIERS = {
+  s: 1000,        // segundos
+  m: 60000,       // minutos
+  h: 3600000,     // horas
+  d: 86400000,    // dias
+  w: 604800000,   // semanas
+} as const;
+
+/**
+ * Parse de duração human-readable para milissegundos
+ * @param duration - Número (ms) ou string no formato '30s', '10m', '2h', '1d', '1w'
+ * @returns Tempo em milissegundos
+ * @throws Error se o formato for inválido
+ * 
+ * @example
+ * parseDuration(60000) // 60000
+ * parseDuration('30s') // 30000
+ * parseDuration('10m') // 600000
+ * parseDuration('2h')  // 7200000
+ * parseDuration('1d')  // 86400000
+ * parseDuration('1w')  // 604800000
+ */
+export function parseDuration(duration: Duration): number {
+  // Se já é número, retorna diretamente
+  if (typeof duration === 'number') {
+    return duration;
+  }
+
+  // Regex para extrair número e unidade
+  const match = duration.match(/^(\d+)([smhdw])$/);
+  
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}". ` +
+      `Use formats like '30s', '10m', '2h', '1d', '1w' or a number in milliseconds.`
+    );
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2] as keyof typeof DURATION_MULTIPLIERS;
+  
+  return value * DURATION_MULTIPLIERS[unit];
+}
+
+/**
+ * Converte milissegundos para formato human-readable
+ * @param ms - Tempo em milissegundos
+ * @returns String no formato mais apropriado
+ * 
+ * @example
+ * formatDuration(30000)  // '30s'
+ * formatDuration(600000) // '10m'
+ * formatDuration(7200000) // '2h'
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
+  if (ms < 3600000) return `${Math.floor(ms / 60000)}m`;
+  if (ms < 86400000) return `${Math.floor(ms / 3600000)}h`;
+  if (ms < 604800000) return `${Math.floor(ms / 86400000)}d`;
+  return `${Math.floor(ms / 604800000)}w`;
+}
+
+/**
+ * Valida se uma string é uma duração válida
+ * @param value - Valor a ser validado
+ * @returns true se for uma duração válida
+ */
+export function isValidDuration(value: unknown): value is Duration {
+  if (typeof value === 'number') {
+    return value >= 0;
+  }
+  if (typeof value === 'string') {
+    return /^\d+[smhdw]$/.test(value);
+  }
+  return false;
+}

package/src/cache/index.ts

@@ -0,0 +1,28 @@
+// Interfaces
+export type {
+  CacheReader,
+  CacheWriter,
+  CacheInvalidator,
+  CacheProvider,
+  Duration,
+  CacheOptions,
+  InvalidationStrategy,
+  CacheState,
+} from './cache-interfaces.js';
+
+// Utils
+export { parseDuration, formatDuration, isValidDuration } from './duration-utils.js';
+
+// Strategies
+export type { CacheStrategy } from './strategies/cache-strategy.js';
+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';
+
+// Manager
+export { QueryCacheManager } from './query-cache-manager.js';
+
+// Tag Index
+export { TagIndex } from './tag-index.js';

package/src/cache/query-cache-manager.ts

@@ -0,0 +1,130 @@
+import type { 
+  CacheProvider, 
+  CacheOptions, 
+  Duration 
+} from './cache-interfaces.js';
+import type { CacheStrategy } from './strategies/cache-strategy.js';
+import { DefaultCacheStrategy } from './strategies/default-cache-strategy.js';
+import { parseDuration } from './duration-utils.js';
+import { MemoryCacheAdapter } from './adapters/memory-cache-adapter.js';
+
+/**
+ * Gerenciador de cache para queries
+ * Responsabilidade única: orquestrar leitura/escrita no cache (SRP)
+ */
+export class QueryCacheManager {
+  constructor(
+    private provider: CacheProvider = new MemoryCacheAdapter(),
+    private strategy: CacheStrategy = new DefaultCacheStrategy(),
+    private defaultTtl: Duration = '1h'
+  ) {}
+
+  /**
+   * Executa com cache - padrão execute-around
+   * @returns Resultado da execução (do cache ou da função)
+   */
+  async getOrExecute<T>(
+    options: CacheOptions,
+    executor: () => Promise<T>,
+    tenantId?: string | number
+  ): Promise<T> {
+    const key = this.strategy.generateKey(options.key, tenantId);
+    const ttlMs = this.parseDuration(options.ttl ?? this.defaultTtl);
+
+    // Tenta obter do cache
+    const cached = await this.provider.get<T>(key);
+    if (cached !== undefined) {
+      return this.strategy.deserialize(cached);
+    }
+
+    // Executa a query
+    const result = await executor();
+
+    // Verifica se deve cachear
+    if (!this.strategy.shouldCache(result, options)) {
+      return result;
+    }
+
+    // Serializa e salva no cache
+    const serialized = this.strategy.serialize(result);
+    await this.provider.set(key, serialized, ttlMs);
+
+    // Registra tags se disponível
+    if (options.tags) {
+      await this.registerTags(key, options.tags);
+    }
+
+    return result;
+  }
+
+  /**
+   * Invalida uma chave específica
+   */
+  async invalidateKey(key: string, tenantId?: string | number): Promise<void> {
+    const fullKey = this.strategy.generateKey(key, tenantId);
+    await this.provider.invalidate(fullKey);
+  }
+
+  /**
+   * Invalida por tags
+   */
+  async invalidateTags(tags: string[]): Promise<void> {
+    await this.provider.invalidateTags(tags);
+  }
+
+  /**
+   * Invalida por prefixo (útil para multi-tenancy)
+   */
+  async invalidatePrefix(prefix: string): Promise<void> {
+    await this.provider.invalidatePrefix(prefix);
+  }
+
+  /**
+   * Limpa todo o cache (cuidado!)
+   */
+  async clear(): Promise<void> {
+    const provider = this.provider as CacheProvider & { clear?: () => void };
+    if (typeof provider.clear === 'function') {
+      provider.clear();
+    } else {
+      throw new Error('Cache provider does not support clear operation');
+    }
+  }
+
+  /**
+   * Retorna estatísticas do cache (se disponível)
+   */
+  getStats(): { size: number; tags: number } | undefined {
+    const provider = this.provider as CacheProvider & { getStats?: () => { size: number; tags: number } };
+    if (typeof provider.getStats === 'function') {
+      return provider.getStats();
+    }
+    return undefined;
+  }
+
+  /**
+   * Libera recursos do cache
+   */
+  async dispose(): Promise<void> {
+    await this.provider.dispose?.();
+  }
+
+  /**
+   * Registra tags para uma chave
+   */
+  private async registerTags(key: string, tags: string[]): Promise<void> {
+    // Se o provider tem suporte nativo a tags
+    const provider = this.provider as CacheProvider & { registerTags?: (key: string, tags: string[]) => void };
+    if (typeof provider.registerTags === 'function') {
+      provider.registerTags(key, tags);
+    }
+    // Caso contrário, as tags são usadas apenas na invalidação
+  }
+
+  /**
+   * Converte duração para milissegundos
+   */
+  private parseDuration(d: Duration): number {
+    return parseDuration(d);
+  }
+}

package/src/cache/strategies/cache-strategy.ts

@@ -0,0 +1,29 @@
+import type { CacheOptions } from '../cache-interfaces.js';
+
+/**
+ * Estratégia de cache - define como chaves são geradas,
+ * dados são serializados/desserializados e se devem ser cacheados
+ */
+export interface CacheStrategy {
+  readonly name: string;
+  
+  /**
+   * Gera chave de cache considerando tenant
+   */
+  generateKey(queryKey: string, tenantId?: string | number): string;
+  
+  /**
+   * Decide se o resultado deve ser cacheado
+   */
+  shouldCache(result: unknown, options: CacheOptions): boolean;
+  
+  /**
+   * Serializa dados para armazenamento
+   */
+  serialize<T>(data: T): unknown;
+  
+  /**
+   * Desserializa dados do cache
+   */
+  deserialize<T>(data: unknown): T;
+}

package/src/cache/strategies/default-cache-strategy.ts

@@ -0,0 +1,96 @@
+import type { CacheStrategy } from './cache-strategy.js';
+import type { CacheOptions } from '../cache-interfaces.js';
+
+/**
+ * Implementação padrão da estratégia de cache
+ * Suporta serialização de Date, BigInt e multi-tenancy
+ */
+export class DefaultCacheStrategy implements CacheStrategy {
+  readonly name = 'default';
+
+  /**
+   * Gera chave de cache com prefixo de tenant se houver
+   */
+  generateKey(queryKey: string, tenantId?: string | number): string {
+    if (tenantId !== undefined) {
+      return `tenant:${tenantId}:${queryKey}`;
+    }
+    return queryKey;
+  }
+
+  /**
+   * Verifica se deve cachear baseado na condição configurada
+   */
+  shouldCache(result: unknown, options: CacheOptions): boolean {
+    if (options.condition) {
+      return options.condition(result);
+    }
+    return true;
+  }
+
+  /**
+   * Serializa com suporte a tipos especiais
+   */
+  serialize<T>(data: T): unknown {
+    return JSON.stringify(data, (key, value) => {
+      // Serializa Date
+      if (value instanceof Date) {
+        return { __type: 'Date', value: value.toISOString() };
+      }
+      
+      // Serializa BigInt
+      if (typeof value === 'bigint') {
+        return { __type: 'BigInt', value: value.toString() };
+      }
+      
+      // Serializa Map
+      if (value instanceof Map) {
+        return { __type: 'Map', value: Array.from(value.entries()) };
+      }
+      
+      // Serializa Set
+      if (value instanceof Set) {
+        return { __type: 'Set', value: Array.from(value) };
+      }
+      
+      return value;
+    });
+  }
+
+  /**
+   * Desserializa restaurando tipos especiais
+   */
+  deserialize<T>(data: unknown): T {
+    if (typeof data !== 'string') {
+      return data as T;
+    }
+
+    return JSON.parse(data, (key, value) => {
+      if (!value || typeof value !== 'object') {
+        return value;
+      }
+
+      // Restaura Date
+      if (value.__type === 'Date') {
+        return new Date(value.value);
+      }
+      
+      // Restaura BigInt
+      if (value.__type === 'BigInt') {
+        return BigInt(value.value);
+      }
+      
+      // Restaura Map
+      if (value.__type === 'Map') {
+        return new Map(value.value);
+      }
+      
+      // Restaura Set
+      if (value.__type === 'Set') {
+        return new Set(value.value);
+      }
+      
+      return value;
+    }) as T;
+  }
+}

package/src/cache/strategies/index.ts

@@ -0,0 +1,2 @@
+export type { CacheStrategy } from './cache-strategy.js';
+export { DefaultCacheStrategy } from './default-cache-strategy.js';