metal-orm 1.0.118 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.118",
+  "version": "1.1.1",
   "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/scripts/generate-entities/cli.mjs

@@ -200,6 +200,13 @@ Flags:
   --out=<file>          Override the generated file (defaults to generated-entities.ts or the index inside --out-dir)
   --out-dir=<dir>       Emit one file per entity inside this directory plus the shared index
   --help                Show this help
+
+Naming Overrides JSON format:
+  {
+    "irregulars": { "person": "people", "child": "children" },
+    "relationOverrides": { "User": { "orders": "purchases" } },
+    "classNameOverrides": { "users_table": "UserAccount", "order_items": "OrderLineItem" }
+  }
 `
   );
 };

package/scripts/generate-entities/generate.mjs

@@ -18,8 +18,8 @@ const loadNamingOverrides = async (filePath, fsPromises) => {
     throw new Error(`Naming overrides at ${filePath} must be an object`);
   }
 
-  // Support both flat format { "singular": "plural" } and structured { irregulars: {...}, relationOverrides: {...} }
-  const hasStructuredFormat = parsed.irregulars || parsed.relationOverrides;
+  // Support both flat format { "singular": "plural" } and structured { irregulars: {...}, relationOverrides: {...}, classNameOverrides: {...} }
+  const hasStructuredFormat = parsed.irregulars || parsed.relationOverrides || parsed.classNameOverrides;
 
   const irregulars = hasStructuredFormat
     ? (parsed.irregulars && typeof parsed.irregulars === 'object' ? parsed.irregulars : {})
@@ -29,15 +29,19 @@ const loadNamingOverrides = async (filePath, fsPromises) => {
     ? parsed.relationOverrides
     : {};
 
-  return { irregulars, relationOverrides };
+  const classNameOverrides = hasStructuredFormat && parsed.classNameOverrides && typeof parsed.classNameOverrides === 'object'
+    ? parsed.classNameOverrides
+    : {};
+
+  return { irregulars, relationOverrides, classNameOverrides };
 };
 
 export const generateEntities = async (opts, context = {}) => {
   const { fs: fsPromises = fs, logger = console } = context;
-  const { irregulars, relationOverrides } = opts.namingOverrides
+  const { irregulars, relationOverrides, classNameOverrides } = opts.namingOverrides
     ? await loadNamingOverrides(opts.namingOverrides, fsPromises)
-    : { irregulars: undefined, relationOverrides: {} };
-  const naming = createNamingStrategy(opts.locale, irregulars, relationOverrides);
+    : { irregulars: undefined, relationOverrides: {}, classNameOverrides: {} };
+  const naming = createNamingStrategy(opts.locale, irregulars, relationOverrides, classNameOverrides);
 
   const { executor, cleanup } = await loadDriver(opts.dialect, opts.url, opts.dbPath);
   let schema;

package/scripts/inspect-schema.mjs

@@ -0,0 +1,181 @@
+import { Connection, Request } from 'tedious';
+
+const REQUIRED_ENV = ['PGE_DIGITAL_HOST', 'PGE_DIGITAL_USER', 'PGE_DIGITAL_PASSWORD'];
+
+const hasDbEnv = REQUIRED_ENV.every((name) => !!process.env[name]);
+
+if (!hasDbEnv) {
+  console.error('Missing required environment variables:', REQUIRED_ENV.filter(n => !process.env[n]));
+  process.exit(1);
+}
+
+const parseBool = (value, fallback) => {
+  if (value === undefined) return fallback;
+  return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase());
+};
+
+async function queryTableSchema(connection, tableName) {
+  return new Promise((resolve, reject) => {
+    const query = `
+      SELECT 
+        c.COLUMN_NAME,
+        c.DATA_TYPE,
+        c.IS_NULLABLE,
+        c.CHARACTER_MAXIMUM_LENGTH,
+        c.NUMERIC_PRECISION,
+        c.NUMERIC_SCALE,
+        COLUMNPROPERTY(OBJECT_ID(c.TABLE_SCHEMA + '.' + c.TABLE_NAME), c.COLUMN_NAME, 'IsIdentity') as IS_IDENTITY,
+        CASE WHEN pk.COLUMN_NAME IS NOT NULL THEN 1 ELSE 0 END as IS_PRIMARY_KEY
+      FROM INFORMATION_SCHEMA.COLUMNS c
+      LEFT JOIN (
+        SELECT ku.TABLE_CATALOG, ku.TABLE_SCHEMA, ku.TABLE_NAME, ku.COLUMN_NAME
+        FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+        JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE ku ON tc.CONSTRAINT_NAME = ku.CONSTRAINT_NAME
+        WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY'
+      ) pk ON c.TABLE_CATALOG = pk.TABLE_CATALOG 
+        AND c.TABLE_SCHEMA = pk.TABLE_SCHEMA 
+        AND c.TABLE_NAME = pk.TABLE_NAME 
+        AND c.COLUMN_NAME = pk.COLUMN_NAME
+      WHERE c.TABLE_NAME = '${tableName}'
+      ORDER BY c.ORDINAL_POSITION
+    `;
+
+    const request = new Request(query, (err, rowCount) => {
+      if (err) reject(err);
+    });
+
+    const columns = [];
+    request.on('row', (columns_data) => {
+      const col = {};
+      columns_data.forEach((c) => {
+        col[c.metadata.colName] = c.value;
+      });
+      columns.push(col);
+    });
+
+    request.on('requestCompleted', () => {
+      resolve(columns);
+    });
+
+    connection.execSql(request);
+  });
+}
+
+async function queryForeignKeys(connection, tableName) {
+  return new Promise((resolve, reject) => {
+    const query = `
+      SELECT 
+        fk.name AS FK_NAME,
+        tp.name AS PARENT_TABLE,
+        cp.name AS PARENT_COLUMN,
+        tr.name AS REFERENCED_TABLE,
+        cr.name AS REFERENCED_COLUMN
+      FROM sys.foreign_keys fk
+      INNER JOIN sys.tables tp ON fk.parent_object_id = tp.object_id
+      INNER JOIN sys.tables tr ON fk.referenced_object_id = tr.object_id
+      INNER JOIN sys.foreign_key_columns fkc ON fk.object_id = fkc.constraint_object_id
+      INNER JOIN sys.columns cp ON fkc.parent_object_id = cp.object_id AND fkc.parent_column_id = cp.column_id
+      INNER JOIN sys.columns cr ON fkc.referenced_object_id = cr.object_id AND fkc.referenced_column_id = cr.column_id
+      WHERE tp.name = '${tableName}' OR tr.name = '${tableName}'
+    `;
+
+    const request = new Request(query, (err, rowCount) => {
+      if (err) reject(err);
+    });
+
+    const fks = [];
+    request.on('row', (columns) => {
+      const fk = {};
+      columns.forEach((c) => {
+        fk[c.metadata.colName] = c.value;
+      });
+      fks.push(fk);
+    });
+
+    request.on('requestCompleted', () => {
+      resolve(fks);
+    });
+
+    connection.execSql(request);
+  });
+}
+
+async function main() {
+  const { PGE_DIGITAL_HOST, PGE_DIGITAL_USER, PGE_DIGITAL_PASSWORD } = process.env;
+  const database = process.env.PGE_DIGITAL_DATABASE ?? 'PGE_DIGITAL';
+  const encrypt = parseBool(process.env.PGE_DIGITAL_ENCRYPT, true);
+  const trustServerCertificate = parseBool(process.env.PGE_DIGITAL_TRUST_CERT, true);
+  const port = Number(process.env.PGE_DIGITAL_PORT ?? '1433');
+
+  const tablesToInspect = ['carga', 'registro_tramitacao', 'tramitacao', 'usuario', 
+    'processo_administrativo', 'classificacao', 'especializada', 'acervo', 
+    'processo_judicial', 'parte', 'pessoa', 'tipo_polo'];
+
+  const connection = await new Promise((resolve, reject) => {
+    const conn = new Connection({
+      server: PGE_DIGITAL_HOST,
+      authentication: {
+        type: 'default',
+        options: {
+          userName: PGE_DIGITAL_USER,
+          password: PGE_DIGITAL_PASSWORD,
+        },
+      },
+      options: {
+        database,
+        encrypt,
+        trustServerCertificate,
+        port: Number.isFinite(port) ? port : 1433,
+      },
+    });
+
+    conn.on('connect', (err) => (err ? reject(err) : resolve(conn)));
+    conn.connect();
+  });
+
+  console.log(`Connected to ${database} on ${PGE_DIGITAL_HOST}\n`);
+
+  for (const tableName of tablesToInspect) {
+    try {
+      console.log(`\n=== Table: ${tableName} ===`);
+      
+      const columns = await queryTableSchema(connection, tableName);
+      if (columns.length === 0) {
+        console.log('  Table not found or no columns');
+        continue;
+      }
+
+      console.log('Columns:');
+      columns.forEach(col => {
+        const nullable = col.IS_NULLABLE === 'YES' ? 'NULL' : 'NOT NULL';
+        const pk = col.IS_PRIMARY_KEY ? ' [PK]' : '';
+        const identity = col.IS_IDENTITY ? ' [IDENTITY]' : '';
+        let dataType = col.DATA_TYPE;
+        if (col.CHARACTER_MAXIMUM_LENGTH && col.CHARACTER_MAXIMUM_LENGTH > 0) {
+          dataType += `(${col.CHARACTER_MAXIMUM_LENGTH})`;
+        } else if (col.NUMERIC_PRECISION) {
+          dataType += `(${col.NUMERIC_PRECISION},${col.NUMERIC_SCALE || 0})`;
+        }
+        console.log(`  ${col.COLUMN_NAME}: ${dataType} ${nullable}${pk}${identity}`);
+      });
+
+      const fks = await queryForeignKeys(connection, tableName);
+      if (fks.length > 0) {
+        console.log('Foreign Keys:');
+        fks.forEach(fk => {
+          console.log(`  ${fk.PARENT_TABLE}.${fk.PARENT_COLUMN} -> ${fk.REFERENCED_TABLE}.${fk.REFERENCED_COLUMN}`);
+        });
+      }
+    } catch (err) {
+      console.error(`Error inspecting ${tableName}:`, err.message);
+    }
+  }
+
+  connection.close();
+  console.log('\n=== Done ===');
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/scripts/naming-strategy.mjs

@@ -1,11 +1,12 @@
 import { resolveInflector } from './inflection/index.mjs';
 
 export class BaseNamingStrategy {
-  constructor(irregulars = {}, inflector = resolveInflector('en'), relationOverrides = {}) {
+  constructor(irregulars = {}, inflector = resolveInflector('en'), relationOverrides = {}, classNameOverrides = {}) {
     this.irregulars = new Map();
     this.inverseIrregulars = new Map();
     this.inflector = inflector;
     this.relationOverrides = new Map();
+    this.classNameOverrides = new Map();
 
     for (const [singular, plural] of Object.entries(irregulars)) {
       if (!singular || !plural) continue;
@@ -21,6 +22,12 @@ export class BaseNamingStrategy {
       if (!overrides || typeof overrides !== 'object') continue;
       this.relationOverrides.set(className, new Map(Object.entries(overrides)));
     }
+
+    // Build class name overrides map: tableName -> className
+    for (const [tableName, className] of Object.entries(classNameOverrides)) {
+      if (!tableName || !className) continue;
+      this.classNameOverrides.set(tableName, className);
+    }
   }
 
   applyRelationOverride(className, propertyName) {
@@ -80,6 +87,9 @@ export class BaseNamingStrategy {
   }
 
   classNameFromTable(tableName) {
+    if (this.classNameOverrides.has(tableName)) {
+      return this.classNameOverrides.get(tableName);
+    }
     return this.toPascalCase(this.singularize(tableName));
   }
 
@@ -113,20 +123,20 @@ export class BaseNamingStrategy {
 }
 
 export class EnglishNamingStrategy extends BaseNamingStrategy {
-  constructor(irregulars = {}) {
-    super(irregulars, resolveInflector('en'));
+  constructor(irregulars = {}, relationOverrides = {}, classNameOverrides = {}) {
+    super(irregulars, resolveInflector('en'), relationOverrides, classNameOverrides);
   }
 }
 
 export class PortugueseNamingStrategy extends BaseNamingStrategy {
-  constructor(irregulars = {}) {
+  constructor(irregulars = {}, relationOverrides = {}, classNameOverrides = {}) {
     const inflector = resolveInflector('pt-BR');
-    super({ ...inflector.defaultIrregulars, ...irregulars }, inflector);
+    super({ ...inflector.defaultIrregulars, ...irregulars }, inflector, relationOverrides, classNameOverrides);
   }
 }
 
-export const createNamingStrategy = (locale = 'en', irregulars, relationOverrides = {}) => {
+export const createNamingStrategy = (locale = 'en', irregulars, relationOverrides = {}, classNameOverrides = {}) => {
   const inflector = resolveInflector(locale);
   const mergedIrregulars = { ...(inflector.defaultIrregulars || {}), ...(irregulars || {}) };
-  return new BaseNamingStrategy(mergedIrregulars, inflector, relationOverrides);
+  return new BaseNamingStrategy(mergedIrregulars, inflector, relationOverrides, classNameOverrides);
 };

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;
+}