metal-orm 1.0.117 → 1.1.0

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   DateTimeTypeStrategy: () => DateTimeTypeStrategy,
   DecimalTypeStrategy: () => DecimalTypeStrategy,
   DefaultBelongsToReference: () => DefaultBelongsToReference,
+  DefaultCacheStrategy: () => DefaultCacheStrategy,
   DefaultEntityMaterializer: () => DefaultEntityMaterializer,
   DefaultHasManyCollection: () => DefaultHasManyCollection,
   DefaultManyToManyCollection: () => DefaultManyToManyCollection,
@@ -74,8 +75,10 @@ __export(index_exports, {
   InsertQueryBuilder: () => InsertQueryBuilder,
   IntegerTypeStrategy: () => IntegerTypeStrategy,
   InterceptorPipeline: () => InterceptorPipeline,
+  KeyvCacheAdapter: () => KeyvCacheAdapter,
   Length: () => Length,
   Lower: () => Lower,
+  MemoryCacheAdapter: () => MemoryCacheAdapter,
   MySqlDialect: () => MySqlDialect,
   NestedSetStrategy: () => NestedSetStrategy,
   Orm: () => Orm,
@@ -85,12 +88,14 @@ __export(index_exports, {
   PostgresDialect: () => PostgresDialect,
   PrimaryKey: () => PrimaryKey,
   PrototypeMaterializationStrategy: () => PrototypeMaterializationStrategy,
+  QueryCacheManager: () => QueryCacheManager,
   RelationKinds: () => RelationKinds,
   STANDARD_COLUMN_TYPES: () => STANDARD_COLUMN_TYPES,
   SelectQueryBuilder: () => SelectQueryBuilder,
   SqlServerDialect: () => SqlServerDialect,
   SqliteDialect: () => SqliteDialect,
   StringTypeStrategy: () => StringTypeStrategy,
+  TagIndex: () => TagIndex,
   Title: () => Title,
   Tree: () => Tree,
   TreeChildren: () => TreeChildren,
@@ -210,6 +215,7 @@ __export(index_exports, {
   extractScopeValues: () => extractScopeValues,
   firstValue: () => firstValue,
   floor: () => floor,
+  formatDuration: () => formatDuration,
   formatTreeList: () => formatTreeList,
   fromUnixTime: () => fromUnixTime,
   generateComponentSchemas: () => generateComponentSchemas,
@@ -265,6 +271,7 @@ __export(index_exports, {
   isOperandNode: () => isOperandNode,
   isTableDef: () => isTableDef2,
   isTreeConfig: () => isTreeConfig,
+  isValidDuration: () => isValidDuration,
   isValueOperandInput: () => isValueOperandInput,
   isWindowFunctionNode: () => isWindowFunctionNode,
   jsonArrayAgg: () => jsonArrayAgg,
@@ -325,6 +332,7 @@ __export(index_exports, {
   pagedResponseToOpenApiSchema: () => pagedResponseToOpenApiSchema,
   paginationParamsSchema: () => paginationParamsSchema,
   parameterToRef: () => parameterToRef,
+  parseDuration: () => parseDuration,
   pi: () => pi,
   pick: () => pick,
   position: () => position,
@@ -1659,7 +1667,7 @@ var Dialect = class _Dialect {
       params: [...ctx.params]
     };
   }
-  supportsReturning() {
+  supportsDmlReturningClause() {
     return false;
   }
   /**
@@ -2684,7 +2692,7 @@ var PostgresDialect = class extends SqlDialectBase {
     const columns = this.formatReturningColumns(returning);
     return ` RETURNING ${columns}`;
   }
-  supportsReturning() {
+  supportsDmlReturningClause() {
     return true;
   }
   /**
@@ -2999,7 +3007,7 @@ var SqliteDialect = class extends SqlDialectBase {
       return `${this.quoteIdentifier(column.name)}${alias}`;
     }).join(", ");
   }
-  supportsReturning() {
+  supportsDmlReturningClause() {
     return true;
   }
 };
@@ -3190,8 +3198,21 @@ var SqlServerDialect = class extends SqlDialectBase {
       this.compileExpression.bind(this)
     );
     const whereClause = this.compileWhere(ast.where, ctx);
-    const returning = this.compileReturning(ast.returning, ctx);
-    return `DELETE ${this.quoteIdentifier(alias)} FROM ${target}${joins}${whereClause}${returning}`;
+    const returning = this.compileOutputClause(ast.returning, "deleted");
+    return `DELETE ${this.quoteIdentifier(alias)}${returning} FROM ${target}${joins}${whereClause}`;
+  }
+  compileUpdateAst(ast, ctx) {
+    const target = this.compileTableReference(ast.table);
+    const assignments = this.compileUpdateAssignments(ast.set, ast.table, ctx);
+    const output = this.compileReturning(ast.returning, ctx);
+    const fromClause = ast.from ? ` FROM ${this.compileFrom(ast.from, ctx)}` : "";
+    const joins = ast.joins ? ast.joins.map((j) => {
+      const table = this.compileFrom(j.table, ctx);
+      const cond = this.compileExpression(j.condition, ctx);
+      return ` ${j.kind} JOIN ${table} ON ${cond}`;
+    }).join("") : "";
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `UPDATE ${target} SET ${assignments}${output}${fromClause}${joins}${whereClause}`;
   }
   compileSelectCoreForMssql(ast, ctx) {
     const columns = ast.columns.map((c) => {
@@ -3242,6 +3263,44 @@ var SqlServerDialect = class extends SqlDialectBase {
     }
     return pagination;
   }
+  supportsDmlReturningClause() {
+    return true;
+  }
+  compileReturning(returning, _ctx) {
+    void _ctx;
+    return this.compileOutputClause(returning, "inserted");
+  }
+  compileOutputClause(returning, prefix) {
+    if (!returning || returning.length === 0) return "";
+    const columns = returning.map((column) => {
+      const colName = this.quoteIdentifier(column.name);
+      const alias = column.alias ? ` AS ${this.quoteIdentifier(column.alias)}` : "";
+      return `${prefix}.${colName}${alias}`;
+    }).join(", ");
+    return ` OUTPUT ${columns}`;
+  }
+  compileInsertAst(ast, ctx) {
+    if (!ast.columns.length) {
+      throw new Error("INSERT queries must specify columns.");
+    }
+    const table = this.compileTableName(ast.into);
+    const columnList = ast.columns.map((column) => this.quoteIdentifier(column.name)).join(", ");
+    const output = this.compileReturning(ast.returning, ctx);
+    const source = this.compileInsertValues(ast, ctx);
+    return `INSERT INTO ${table} (${columnList})${output} ${source}`;
+  }
+  compileInsertValues(ast, ctx) {
+    const source = ast.source;
+    if (source.type === "InsertValues") {
+      if (!source.rows.length) {
+        throw new Error("INSERT ... VALUES requires at least one row.");
+      }
+      const values = source.rows.map((row) => `(${row.map((value) => this.compileOperand(value, ctx)).join(", ")})`).join(", ");
+      return `VALUES ${values}`;
+    }
+    const normalized = this.normalizeSelectAst(source.query);
+    return this.compileSelectAst(normalized, ctx).trim();
+  }
   compileCtes(ast, ctx) {
     if (!ast.ctes || ast.ctes.length === 0) return "";
     const defs = ast.ctes.map((cte) => {
@@ -6915,10 +6974,28 @@ var setLazyOptionsIfEmpty = (entity, relationName, options) => {
   if (!meta || meta.lazyRelationOptions.has(relationName)) return;
   meta.lazyRelationOptions.set(relationName, options);
 };
+var batchByTable = (pending) => {
+  if (pending.length <= 1) return pending;
+  const byTable = /* @__PURE__ */ new Map();
+  let ungroupedIndex = 0;
+  for (const { entities, include } of pending) {
+    const meta = entities.length ? getEntityMeta(entities[0]) : void 0;
+    const tableKey2 = meta?.table?.name ?? `__ungrouped_${ungroupedIndex++}`;
+    const existing = byTable.get(tableKey2);
+    if (existing) {
+      existing.entities.push(...entities);
+      existing.include = mergeRelationIncludeTrees(existing.include, include);
+    } else {
+      byTable.set(tableKey2, { entities: [...entities], include: { ...include } });
+    }
+  }
+  return Array.from(byTable.values());
+};
 var preloadRelationIncludes = async (entities, includeTree, depth = 0) => {
   if (!entities.length) return;
   const entries = Object.entries(includeTree);
   if (!entries.length) return;
+  const pending = [];
   for (const [relationName, node] of entries) {
     const shouldLoad = depth > 0 || Boolean(node.include);
     if (!shouldLoad) continue;
@@ -6930,9 +7007,13 @@ var preloadRelationIncludes = async (entities, includeTree, depth = 0) => {
     );
     const relatedEntities = loaded.flat();
     if (node.include && relatedEntities.length) {
-      await preloadRelationIncludes(relatedEntities, node.include, depth + 1);
+      pending.push({ entities: relatedEntities, include: node.include });
     }
   }
+  const batched = batchByTable(pending);
+  for (const { entities: batchEntities, include } of batched) {
+    await preloadRelationIncludes(batchEntities, include, depth + 1);
+  }
 };
 
 // src/orm/execute.ts
@@ -7635,6 +7716,53 @@ var SelectRelationFacet = class {
   }
 };
 
+// src/query-builder/select/cache-facet.ts
+var CacheFacet = class {
+  /**
+   * Configura opções de cache no contexto
+   */
+  cache(context, options) {
+    return {
+      state: {
+        ...context.state,
+        options
+      }
+    };
+  }
+  /**
+   * Obtém as opções de cache do contexto
+   */
+  getOptions(context) {
+    return context.state.options;
+  }
+  /**
+   * Verifica se há configuração de cache
+   */
+  hasCache(context) {
+    return context.state.options !== void 0;
+  }
+  /**
+   * Cria opções de cache a partir de parâmetros variados
+   * API flexível para diferentes casos de uso
+   */
+  static createOptions(key, ttl, tagsOrConfig) {
+    let tags;
+    let autoInvalidate;
+    if (Array.isArray(tagsOrConfig)) {
+      tags = tagsOrConfig;
+    } else if (tagsOrConfig) {
+      tags = tagsOrConfig.tags;
+      autoInvalidate = tagsOrConfig.autoInvalidate;
+    }
+    return {
+      key,
+      ttl,
+      tags,
+      autoInvalidate
+    };
+  }
+};
+
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
   env;
@@ -7651,6 +7779,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   lazyRelationOptions;
   entityConstructor;
   includeTree;
+  cacheFacet;
+  cacheContext;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -7658,7 +7788,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor, includeTree) {
+  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor, includeTree, cacheContext) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState) => deps.createQueryAstService(table, nextState);
@@ -7672,6 +7802,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
     this.entityConstructor = entityConstructor;
     this.includeTree = includeTree ?? {};
+    this.cacheFacet = new CacheFacet();
+    this.cacheContext = cacheContext ?? { state: {} };
     this.columnSelector = deps.createColumnSelector(this.env);
     const relationManager = deps.createRelationManager(this.env);
     this.fromFacet = new SelectFromFacet(this.env, createAstService);
@@ -7688,7 +7820,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  clone(context = this.context, lazyRelations = new Set(this.lazyRelations), lazyRelationOptions = new Map(this.lazyRelationOptions), includeTree = this.includeTree) {
+  clone(context = this.context, lazyRelations = new Set(this.lazyRelations), lazyRelationOptions = new Map(this.lazyRelationOptions), includeTree = this.includeTree, cacheContext = this.cacheContext) {
     return new _SelectQueryBuilder(
       this.env.table,
       context.state,
@@ -7697,7 +7829,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       lazyRelations,
       lazyRelationOptions,
       this.entityConstructor,
-      includeTree
+      includeTree,
+      cacheContext
     );
   }
   /**
@@ -8119,10 +8252,43 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     }
     return this;
   }
+  /**
+   * Configures caching for this query.
+   * @param key - Unique cache key
+   * @param ttl - Time-to-live (e.g., '1h', '30m', '1d') or milliseconds
+   * @param tagsOrConfig - Optional tags for invalidation or configuration object
+   * @returns New query builder instance with cache configuration
+   * @example
+   * // Simple cache with TTL
+   * await selectFrom(User).cache('active_users', '1h').execute(session);
+   * 
+   * // Cache with tags for invalidation
+   * await selectFrom(User)
+   *   .cache('users_list', '30m', ['users', 'dashboard'])
+   *   .execute(session);
+   * 
+   * // Cache with auto-invalidation
+   * await selectFrom(User)
+   *   .cache('users_list', '1h', { autoInvalidate: true })
+   *   .execute(session);
+   */
+  cache(key, ttl, tagsOrConfig) {
+    const options = CacheFacet.createOptions(key, ttl, tagsOrConfig);
+    const nextCacheContext = this.cacheFacet.cache(this.cacheContext, options);
+    const builder = this.clone(
+      this.context,
+      new Set(this.lazyRelations),
+      new Map(this.lazyRelationOptions),
+      this.includeTree,
+      nextCacheContext
+    );
+    return builder;
+  }
   /**
    * Executes the query and returns hydrated results.
    * If the builder was created with an entity constructor (e.g. via selectFromEntity),
    * this will automatically return fully materialized entity instances.
+   * If caching is configured, results will be cached/retrieved from cache.
    *
    * @param ctx - ORM session context
    * @returns Promise of entity instances (or objects if generic T is not an entity)
@@ -8132,6 +8298,20 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * users[0] instanceof User; // true
    */
   async execute(ctx) {
+    const cacheOptions = this.cacheFacet.getOptions(this.cacheContext);
+    if (!cacheOptions || !ctx.cacheManager) {
+      return this.executeWithoutCache(ctx);
+    }
+    return ctx.cacheManager.getOrExecute(
+      cacheOptions,
+      () => this.executeWithoutCache(ctx),
+      ctx.tenantId
+    );
+  }
+  /**
+   * Executa a query sem cache (método interno)
+   */
+  async executeWithoutCache(ctx) {
     if (this.entityConstructor) {
       return this.executeAs(this.entityConstructor, ctx);
     }
@@ -12453,12 +12633,13 @@ var UnitOfWork = class {
     await this.runHook(tracked.table.hooks?.beforeInsert, tracked);
     const payload = this.extractColumns(tracked.table, tracked.entity);
     let builder = new InsertQueryBuilder(tracked.table).values(payload);
-    if (this.dialect.supportsReturning()) {
+    if (this.dialect.supportsDmlReturningClause()) {
       builder = builder.returning(...this.getReturningColumns(tracked.table));
     }
     const compiled = builder.compile(this.dialect);
     const results = await this.executeCompiled(compiled);
     this.applyReturningResults(tracked, results);
+    this.applyInsertedIdIfAbsent(tracked, results);
     tracked.status = "managed" /* Managed */;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity);
     tracked.pk = this.getPrimaryKeyValue(tracked);
@@ -12480,7 +12661,7 @@ var UnitOfWork = class {
     const pkColumn = tracked.table.columns[findPrimaryKey(tracked.table)];
     if (!pkColumn) return;
     let builder = new UpdateQueryBuilder(tracked.table).set(changes).where(eq(pkColumn, tracked.pk));
-    if (this.dialect.supportsReturning()) {
+    if (this.dialect.supportsDmlReturningClause()) {
       builder = builder.returning(...this.getReturningColumns(tracked.table));
     }
     const compiled = builder.compile(this.dialect);
@@ -12574,9 +12755,8 @@ var UnitOfWork = class {
    * @param results - Query results
    */
   applyReturningResults(tracked, results) {
-    if (!this.dialect.supportsReturning()) return;
     const first = results[0];
-    if (!first || first.values.length === 0) return;
+    if (!first || first.columns.length === 0 || first.values.length === 0) return;
     const row = first.values[0];
     for (let i = 0; i < first.columns.length; i++) {
       const columnName = this.normalizeColumnName(first.columns[i]);
@@ -12584,6 +12764,21 @@ var UnitOfWork = class {
       tracked.entity[columnName] = row[i];
     }
   }
+  /**
+   * Applies the driver-provided insertId when no RETURNING clause was used.
+   * Only sets the PK if it is currently absent on the entity.
+   * @param tracked - The tracked entity
+   * @param results - Query results (may contain meta.insertId)
+   */
+  applyInsertedIdIfAbsent(tracked, results) {
+    const pkName = findPrimaryKey(tracked.table);
+    const current = tracked.entity[pkName];
+    if (current != null) return;
+    const first = results[0];
+    const insertId = first?.meta?.insertId;
+    if (insertId == null) return;
+    tracked.entity[pkName] = insertId;
+  }
   /**
    * Normalizes a column name by removing quotes and table prefixes.
    * @param column - The column name to normalize
@@ -13221,6 +13416,10 @@ var OrmSession = class {
   domainEvents;
   /** The relation change processor */
   relationChanges;
+  /** The cache manager for query caching */
+  cacheManager;
+  /** The tenant ID for multi-tenancy support */
+  tenantId;
   interceptors;
   saveGraphDefaults;
   /**
@@ -13235,6 +13434,8 @@ var OrmSession = class {
     this.unitOfWork = new UnitOfWork(this.orm.dialect, this.executor, this.identityMap, () => this);
     this.relationChanges = new RelationChangeProcessor(this.unitOfWork, this.orm.dialect, this.executor);
     this.domainEvents = new DomainEventBus(opts.domainEventHandlers);
+    this.cacheManager = opts.cacheManager;
+    this.tenantId = opts.tenantId;
   }
   /**
    * Releases resources associated with this session (executor/pool leases) and resets tracking.
@@ -13609,6 +13810,45 @@ var OrmSession = class {
       entityContext: this
     };
   }
+  /**
+   * Invalidates cache by specific tags.
+   * @param tags - Tags to invalidate
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCacheTags(['users', 'dashboard']);
+   */
+  async invalidateCacheTags(tags) {
+    if (!this.cacheManager) {
+      throw new Error("No cache manager configured. Please provide cacheManager when creating the session.");
+    }
+    await this.cacheManager.invalidateTags(tags);
+  }
+  /**
+   * Invalidates cache by key prefix (useful for multi-tenancy).
+   * @param prefix - Prefix to match cache keys
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCachePrefix('tenant:123:');
+   */
+  async invalidateCachePrefix(prefix) {
+    if (!this.cacheManager) {
+      throw new Error("No cache manager configured. Please provide cacheManager when creating the session.");
+    }
+    await this.cacheManager.invalidatePrefix(prefix);
+  }
+  /**
+   * Invalidates a specific cache key.
+   * @param key - Cache key to invalidate
+   * @throws Error if no cache manager is configured
+   * @example
+   * await session.invalidateCacheKey('active_users');
+   */
+  async invalidateCacheKey(key) {
+    if (!this.cacheManager) {
+      throw new Error("No cache manager configured. Please provide cacheManager when creating the session.");
+    }
+    await this.cacheManager.invalidateKey(key, this.tenantId);
+  }
   /**
    * Merges session defaults with per-call saveGraph options.
    * @param options - Per-call saveGraph options
@@ -13646,6 +13886,309 @@ var InterceptorPipeline = class {
   }
 };
 
+// src/cache/strategies/default-cache-strategy.ts
+var DefaultCacheStrategy = class {
+  name = "default";
+  /**
+   * Gera chave de cache com prefixo de tenant se houver
+   */
+  generateKey(queryKey, tenantId) {
+    if (tenantId !== void 0) {
+      return `tenant:${tenantId}:${queryKey}`;
+    }
+    return queryKey;
+  }
+  /**
+   * Verifica se deve cachear baseado na condição configurada
+   */
+  shouldCache(result, options) {
+    if (options.condition) {
+      return options.condition(result);
+    }
+    return true;
+  }
+  /**
+   * Serializa com suporte a tipos especiais
+   */
+  serialize(data) {
+    return JSON.stringify(data, (key, value) => {
+      if (value instanceof Date) {
+        return { __type: "Date", value: value.toISOString() };
+      }
+      if (typeof value === "bigint") {
+        return { __type: "BigInt", value: value.toString() };
+      }
+      if (value instanceof Map) {
+        return { __type: "Map", value: Array.from(value.entries()) };
+      }
+      if (value instanceof Set) {
+        return { __type: "Set", value: Array.from(value) };
+      }
+      return value;
+    });
+  }
+  /**
+   * Desserializa restaurando tipos especiais
+   */
+  deserialize(data) {
+    if (typeof data !== "string") {
+      return data;
+    }
+    return JSON.parse(data, (key, value) => {
+      if (!value || typeof value !== "object") {
+        return value;
+      }
+      if (value.__type === "Date") {
+        return new Date(value.value);
+      }
+      if (value.__type === "BigInt") {
+        return BigInt(value.value);
+      }
+      if (value.__type === "Map") {
+        return new Map(value.value);
+      }
+      if (value.__type === "Set") {
+        return new Set(value.value);
+      }
+      return value;
+    });
+  }
+};
+
+// src/cache/duration-utils.ts
+var DURATION_MULTIPLIERS = {
+  s: 1e3,
+  // segundos
+  m: 6e4,
+  // minutos
+  h: 36e5,
+  // horas
+  d: 864e5,
+  // dias
+  w: 6048e5
+  // semanas
+};
+function parseDuration(duration) {
+  if (typeof duration === "number") {
+    return duration;
+  }
+  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];
+  return value * DURATION_MULTIPLIERS[unit];
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  if (ms < 6e4) return `${Math.floor(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.floor(ms / 6e4)}m`;
+  if (ms < 864e5) return `${Math.floor(ms / 36e5)}h`;
+  if (ms < 6048e5) return `${Math.floor(ms / 864e5)}d`;
+  return `${Math.floor(ms / 6048e5)}w`;
+}
+function isValidDuration(value) {
+  if (typeof value === "number") {
+    return value >= 0;
+  }
+  if (typeof value === "string") {
+    return /^\d+[smhdw]$/.test(value);
+  }
+  return false;
+}
+
+// src/cache/adapters/memory-cache-adapter.ts
+var MemoryCacheAdapter = class {
+  name = "memory";
+  storage = /* @__PURE__ */ new Map();
+  tagIndex = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.storage.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      await this.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async has(key) {
+    const value = await this.get(key);
+    return value !== void 0;
+  }
+  async set(key, value, ttlMs) {
+    const entry = {
+      value,
+      expiresAt: ttlMs ? Date.now() + ttlMs : void 0
+    };
+    this.storage.set(key, entry);
+  }
+  async delete(key) {
+    this.storage.delete(key);
+    for (const [tag, keys] of this.tagIndex) {
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagIndex.delete(tag);
+      }
+    }
+  }
+  async invalidate(key) {
+    await this.delete(key);
+  }
+  async invalidateTags(tags) {
+    const keysToDelete = /* @__PURE__ */ new Set();
+    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) {
+    const keysToDelete = [];
+    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, tags) {
+    for (const tag of tags) {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, /* @__PURE__ */ new Set());
+      }
+      this.tagIndex.get(tag).add(key);
+    }
+  }
+  /**
+   * Limpa todo o cache
+   */
+  clear() {
+    this.storage.clear();
+    this.tagIndex.clear();
+  }
+  /**
+   * Retorna estatísticas do cache
+   */
+  getStats() {
+    return {
+      size: this.storage.size,
+      tags: this.tagIndex.size
+    };
+  }
+  async dispose() {
+    this.clear();
+  }
+};
+
+// src/cache/query-cache-manager.ts
+var QueryCacheManager = class {
+  constructor(provider = new MemoryCacheAdapter(), strategy = new DefaultCacheStrategy(), defaultTtl = "1h") {
+    this.provider = provider;
+    this.strategy = strategy;
+    this.defaultTtl = defaultTtl;
+  }
+  /**
+   * Executa com cache - padrão execute-around
+   * @returns Resultado da execução (do cache ou da função)
+   */
+  async getOrExecute(options, executor, tenantId) {
+    const key = this.strategy.generateKey(options.key, tenantId);
+    const ttlMs = this.parseDuration(options.ttl ?? this.defaultTtl);
+    const cached = await this.provider.get(key);
+    if (cached !== void 0) {
+      return this.strategy.deserialize(cached);
+    }
+    const result = await executor();
+    if (!this.strategy.shouldCache(result, options)) {
+      return result;
+    }
+    const serialized = this.strategy.serialize(result);
+    await this.provider.set(key, serialized, ttlMs);
+    if (options.tags) {
+      await this.registerTags(key, options.tags);
+    }
+    return result;
+  }
+  /**
+   * Invalida uma chave específica
+   */
+  async invalidateKey(key, tenantId) {
+    const fullKey = this.strategy.generateKey(key, tenantId);
+    await this.provider.invalidate(fullKey);
+  }
+  /**
+   * Invalida por tags
+   */
+  async invalidateTags(tags) {
+    await this.provider.invalidateTags(tags);
+  }
+  /**
+   * Invalida por prefixo (útil para multi-tenancy)
+   */
+  async invalidatePrefix(prefix) {
+    await this.provider.invalidatePrefix(prefix);
+  }
+  /**
+   * Limpa todo o cache (cuidado!)
+   */
+  async clear() {
+    const provider = this.provider;
+    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() {
+    const provider = this.provider;
+    if (typeof provider.getStats === "function") {
+      return provider.getStats();
+    }
+    return void 0;
+  }
+  /**
+   * Libera recursos do cache
+   */
+  async dispose() {
+    await this.provider.dispose?.();
+  }
+  /**
+   * Registra tags para uma chave
+   */
+  async registerTags(key, tags) {
+    const provider = this.provider;
+    if (typeof provider.registerTags === "function") {
+      provider.registerTags(key, tags);
+    }
+  }
+  /**
+   * Converte duração para milissegundos
+   */
+  parseDuration(d) {
+    return parseDuration(d);
+  }
+};
+
 // src/orm/orm.ts
 var Orm = class {
   /** The database dialect */
@@ -13654,6 +14197,8 @@ var Orm = class {
   interceptors;
   /** The naming strategy */
   namingStrategy;
+  /** The cache manager (if configured) */
+  cacheManager;
   executorFactory;
   /**
    * Creates a new ORM instance.
@@ -13664,15 +14209,27 @@ var Orm = class {
     this.interceptors = opts.interceptors ?? new InterceptorPipeline();
     this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
     this.executorFactory = opts.executorFactory;
+    if (opts.cache) {
+      this.cacheManager = new QueryCacheManager(
+        opts.cache.provider,
+        opts.cache.strategy ?? new DefaultCacheStrategy(),
+        opts.cache.defaultTtl ?? "1h"
+      );
+    }
   }
   /**
    * Creates a new ORM session.
-   * @param options - Optional session options
+   * @param options - Optional session options (e.g., tenantId for multi-tenancy)
    * @returns The ORM session
    */
-  createSession() {
+  createSession(options) {
     const executor = this.executorFactory.createExecutor();
-    return new OrmSession({ orm: this, executor });
+    return new OrmSession({
+      orm: this,
+      executor,
+      cacheManager: this.cacheManager,
+      tenantId: options?.tenantId
+    });
   }
   /**
    * Executes a function within a transaction.
@@ -13683,7 +14240,11 @@ var Orm = class {
    */
   async transaction(fn8) {
     const executor = this.executorFactory.createTransactionalExecutor();
-    const session = new OrmSession({ orm: this, executor });
+    const session = new OrmSession({
+      orm: this,
+      executor,
+      cacheManager: this.cacheManager
+    });
     try {
       return await session.transaction(() => fn8(session));
     } finally {
@@ -14848,7 +15409,15 @@ function createMysqlExecutor(client) {
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params);
       if (!Array.isArray(rows)) {
-        return [{ columns: [], values: [] }];
+        const header = rows;
+        return [{
+          columns: [],
+          values: [],
+          meta: {
+            insertId: header.insertId,
+            rowsAffected: header.affectedRows
+          }
+        }];
       }
       const result = rowsToQueryResult(
         rows
@@ -18157,6 +18726,162 @@ function queryResultsToRows(results) {
   }
   return rows;
 }
+
+// src/cache/adapters/keyv-cache-adapter.ts
+var KeyvCacheAdapter = class {
+  constructor(keyv) {
+    this.keyv = keyv;
+  }
+  name = "keyv";
+  async get(key) {
+    return this.keyv.get(key);
+  }
+  async has(key) {
+    const value = await this.keyv.get(key);
+    return value !== void 0;
+  }
+  async set(key, value, ttlMs) {
+    await this.keyv.set(key, value, ttlMs);
+  }
+  async delete(key) {
+    await this.keyv.delete(key);
+  }
+  async invalidate(key) {
+    await this.delete(key);
+  }
+  async invalidateTags(_tags) {
+    throw new Error(
+      "Keyv adapter does not support tag invalidation. Use MemoryCacheAdapter for testing or implement a custom Redis provider."
+    );
+  }
+  async invalidatePrefix(prefix) {
+    if (typeof this.keyv.iterator === "function") {
+      const keys = [];
+      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;
+    }
+    throw new Error(
+      "Keyv adapter does not support prefix invalidation in this store. Consider using a store with iterator support."
+    );
+  }
+  async dispose() {
+    await this.keyv.disconnect?.();
+  }
+};
+
+// src/cache/tag-index.ts
+var TagIndex = class {
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  /**
+   * Registra que uma chave pertence a determinadas tags
+   */
+  register(key, tags) {
+    for (const tag of tags) {
+      if (!this.tagToKeys.has(tag)) {
+        this.tagToKeys.set(tag, /* @__PURE__ */ new Set());
+      }
+      this.tagToKeys.get(tag).add(key);
+    }
+    const existingTags = this.keyToTags.get(key) ?? /* @__PURE__ */ new Set();
+    tags.forEach((tag) => existingTags.add(tag));
+    this.keyToTags.set(key, existingTags);
+  }
+  /**
+   * Remove uma chave do índice
+   */
+  unregister(key) {
+    const tags = this.keyToTags.get(key);
+    if (tags) {
+      for (const tag of tags) {
+        this.tagToKeys.get(tag)?.delete(key);
+        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) {
+    return Array.from(this.tagToKeys.get(tag) ?? []);
+  }
+  /**
+   * Obtém todas as tags de uma chave
+   */
+  getTagsByKey(key) {
+    return Array.from(this.keyToTags.get(key) ?? []);
+  }
+  /**
+   * Invalida todas as chaves de um conjunto de tags
+   * Retorna as chaves afetadas
+   */
+  invalidateTags(tags) {
+    const keysToInvalidate = /* @__PURE__ */ new Set();
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (keys) {
+        for (const key of keys) {
+          keysToInvalidate.add(key);
+          this.unregister(key);
+        }
+        this.tagToKeys.delete(tag);
+      }
+    }
+    return Array.from(keysToInvalidate);
+  }
+  /**
+   * Invalida por prefixo (útil para multi-tenancy)
+   * Retorna as chaves afetadas
+   */
+  invalidatePrefix(prefix) {
+    const keysToInvalidate = [];
+    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() {
+    return Array.from(this.tagToKeys.keys());
+  }
+  /**
+   * Retorna todas as chaves registradas
+   */
+  getAllKeys() {
+    return Array.from(this.keyToTags.keys());
+  }
+  /**
+   * Limpa todo o índice
+   */
+  clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+  }
+  /**
+   * Retorna estatísticas do índice
+   */
+  getStats() {
+    return {
+      tags: this.tagToKeys.size,
+      keys: this.keyToTags.size
+    };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Alphanumeric,
@@ -18176,6 +18901,7 @@ function queryResultsToRows(results) {
   DateTimeTypeStrategy,
   DecimalTypeStrategy,
   DefaultBelongsToReference,
+  DefaultCacheStrategy,
   DefaultEntityMaterializer,
   DefaultHasManyCollection,
   DefaultManyToManyCollection,
@@ -18190,8 +18916,10 @@ function queryResultsToRows(results) {
   InsertQueryBuilder,
   IntegerTypeStrategy,
   InterceptorPipeline,
+  KeyvCacheAdapter,
   Length,
   Lower,
+  MemoryCacheAdapter,
   MySqlDialect,
   NestedSetStrategy,
   Orm,
@@ -18201,12 +18929,14 @@ function queryResultsToRows(results) {
   PostgresDialect,
   PrimaryKey,
   PrototypeMaterializationStrategy,
+  QueryCacheManager,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
   SqlServerDialect,
   SqliteDialect,
   StringTypeStrategy,
+  TagIndex,
   Title,
   Tree,
   TreeChildren,
@@ -18326,6 +19056,7 @@ function queryResultsToRows(results) {
   extractScopeValues,
   firstValue,
   floor,
+  formatDuration,
   formatTreeList,
   fromUnixTime,
   generateComponentSchemas,
@@ -18381,6 +19112,7 @@ function queryResultsToRows(results) {
   isOperandNode,
   isTableDef,
   isTreeConfig,
+  isValidDuration,
   isValueOperandInput,
   isWindowFunctionNode,
   jsonArrayAgg,
@@ -18441,6 +19173,7 @@ function queryResultsToRows(results) {
   pagedResponseToOpenApiSchema,
   paginationParamsSchema,
   parameterToRef,
+  parseDuration,
   pi,
   pick,
   position,