metal-orm 1.0.118 → 1.1.1

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';

package/src/cache/tag-index.ts

@@ -0,0 +1,128 @@
+/**
+ * Indexa chaves por tags para invalidação em massa
+ * Implementação em memória (pode ser persistida no Redis)
+ */
+export class TagIndex {
+  private tagToKeys: Map<string, Set<string>> = new Map();
+  private keyToTags: Map<string, Set<string>> = new Map();
+
+  /**
+   * Registra que uma chave pertence a determinadas tags
+   */
+  register(key: string, tags: string[]): void {
+    // Mapeia tag -> chaves
+    for (const tag of tags) {
+      if (!this.tagToKeys.has(tag)) {
+        this.tagToKeys.set(tag, new Set());
+      }
+      this.tagToKeys.get(tag)!.add(key);
+    }
+
+    // Mapeia chave -> tags (para limpeza futura)
+    const existingTags = this.keyToTags.get(key) ?? new Set();
+    tags.forEach(tag => existingTags.add(tag));
+    this.keyToTags.set(key, existingTags);
+  }
+
+  /**
+   * Remove uma chave do índice
+   */
+  unregister(key: string): void {
+    const tags = this.keyToTags.get(key);
+    if (tags) {
+      for (const tag of tags) {
+        this.tagToKeys.get(tag)?.delete(key);
+        // Limpa tags vazias
+        if (this.tagToKeys.get(tag)?.size === 0) {
+          this.tagToKeys.delete(tag);
+        }
+      }
+      this.keyToTags.delete(key);
+    }
+  }
+
+  /**
+   * Obtém todas as chaves de uma tag
+   */
+  getKeysByTag(tag: string): string[] {
+    return Array.from(this.tagToKeys.get(tag) ?? []);
+  }
+
+  /**
+   * Obtém todas as tags de uma chave
+   */
+  getTagsByKey(key: string): string[] {
+    return Array.from(this.keyToTags.get(key) ?? []);
+  }
+
+  /**
+   * Invalida todas as chaves de um conjunto de tags
+   * Retorna as chaves afetadas
+   */
+  invalidateTags(tags: string[]): string[] {
+    const keysToInvalidate = new Set<string>();
+    
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (keys) {
+        for (const key of keys) {
+          keysToInvalidate.add(key);
+          this.unregister(key); // Remove do índice
+        }
+        // Remove a tag completamente
+        this.tagToKeys.delete(tag);
+      }
+    }
+
+    return Array.from(keysToInvalidate);
+  }
+
+  /**
+   * Invalida por prefixo (útil para multi-tenancy)
+   * Retorna as chaves afetadas
+   */
+  invalidatePrefix(prefix: string): string[] {
+    const keysToInvalidate: string[] = [];
+    
+    for (const key of this.keyToTags.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToInvalidate.push(key);
+        this.unregister(key);
+      }
+    }
+
+    return keysToInvalidate;
+  }
+
+  /**
+   * Retorna todas as tags registradas
+   */
+  getAllTags(): string[] {
+    return Array.from(this.tagToKeys.keys());
+  }
+
+  /**
+   * Retorna todas as chaves registradas
+   */
+  getAllKeys(): string[] {
+    return Array.from(this.keyToTags.keys());
+  }
+
+  /**
+   * Limpa todo o índice
+   */
+  clear(): void {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+  }
+
+  /**
+   * Retorna estatísticas do índice
+   */
+  getStats(): { tags: number; keys: number } {
+    return {
+      tags: this.tagToKeys.size,
+      keys: this.keyToTags.size,
+    };
+  }
+}