metal-orm 1.0.118 → 1.1.0

package/src/orm/orm.ts

@@ -1,25 +1,42 @@
-import type { DomainEvent, OrmDomainEvent } from './runtime-types.js';
-import type { Dialect } from '../core/dialect/abstract.js';
-import type { DbExecutor } from '../core/execution/db-executor.js';
-import type { NamingStrategy } from '../codegen/naming-strategy.js';
-import { InterceptorPipeline } from './interceptor-pipeline.js';
-import { DefaultNamingStrategy } from '../codegen/naming-strategy.js';
-import { OrmSession } from './orm-session.js';
+import type { DomainEvent, OrmDomainEvent } from './runtime-types.js';
+import type { Dialect } from '../core/dialect/abstract.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
+import type { NamingStrategy } from '../codegen/naming-strategy.js';
+import { InterceptorPipeline } from './interceptor-pipeline.js';
+import { DefaultNamingStrategy } from '../codegen/naming-strategy.js';
+import { OrmSession } from './orm-session.js';
+import type { QueryCacheManager } from '../cache/query-cache-manager.js';
+import type { Duration, CacheProvider, CacheStrategy } from '../cache/index.js';
+import { QueryCacheManager as QueryCacheManagerImpl } from '../cache/query-cache-manager.js';
+import { DefaultCacheStrategy } from '../cache/strategies/default-cache-strategy.js';
 
-/**
- * Options for creating an ORM instance.
- */
-export interface OrmOptions {
-  /** The database dialect */
-  dialect: Dialect;
-  /** The database executor factory */
-  executorFactory: DbExecutorFactory;
-  /** Optional interceptors pipeline */
-  interceptors?: InterceptorPipeline;
-  /** Optional naming strategy */
-  namingStrategy?: NamingStrategy;
-  // model registrations etc.
-}
+/**
+ * Options for creating an ORM instance.
+ */
+export interface OrmOptions {
+  /** The database dialect */
+  dialect: Dialect;
+  /** The database executor factory */
+  executorFactory: DbExecutorFactory;
+  /** Optional interceptors pipeline */
+  interceptors?: InterceptorPipeline;
+  /** Optional naming strategy */
+  namingStrategy?: NamingStrategy;
+  /** Optional cache configuration */
+  cache?: OrmCacheOptions;
+}
+
+/**
+ * Cache configuration options for ORM
+ */
+export interface OrmCacheOptions {
+  /** Cache provider (e.g., MemoryCacheAdapter, KeyvCacheAdapter) */
+  provider: CacheProvider;
+  /** Optional cache strategy (defaults to DefaultCacheStrategy) */
+  strategy?: CacheStrategy;
+  /** Default TTL for cached queries (e.g., '1h', '30m') */
+  defaultTtl?: Duration;
+}
 
 /**
  * Database executor factory interface.
@@ -43,58 +60,78 @@ export interface DbExecutorFactory {
   dispose(): Promise<void>;
 }
 
-/**
- * ORM (Object-Relational Mapping) main class.
- * @template E - The domain event type
- */
-export class Orm<E extends DomainEvent = OrmDomainEvent> {
-  /** The database dialect */
-  readonly dialect: Dialect;
-  /** The interceptors pipeline */
-  readonly interceptors: InterceptorPipeline;
-  /** The naming strategy */
-  readonly namingStrategy: NamingStrategy;
-  private readonly executorFactory: DbExecutorFactory;
+/**
+ * ORM (Object-Relational Mapping) main class.
+ * @template E - The domain event type
+ */
+export class Orm<E extends DomainEvent = OrmDomainEvent> {
+  /** The database dialect */
+  readonly dialect: Dialect;
+  /** The interceptors pipeline */
+  readonly interceptors: InterceptorPipeline;
+  /** The naming strategy */
+  readonly namingStrategy: NamingStrategy;
+  /** The cache manager (if configured) */
+  readonly cacheManager?: QueryCacheManager;
+  private readonly executorFactory: DbExecutorFactory;
+
+  /**
+   * Creates a new ORM instance.
+   * @param opts - ORM options
+   */
+  constructor(opts: OrmOptions) {
+    this.dialect = opts.dialect;
+    this.interceptors = opts.interceptors ?? new InterceptorPipeline();
+    this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
+    this.executorFactory = opts.executorFactory;
+
+    // Initialize cache manager if cache options provided
+    if (opts.cache) {
+      this.cacheManager = new QueryCacheManagerImpl(
+        opts.cache.provider,
+        opts.cache.strategy ?? new DefaultCacheStrategy(),
+        opts.cache.defaultTtl ?? '1h'
+      );
+    }
+  }
 
-  /**
-   * Creates a new ORM instance.
-   * @param opts - ORM options
-   */
-  constructor(opts: OrmOptions) {
-    this.dialect = opts.dialect;
-    this.interceptors = opts.interceptors ?? new InterceptorPipeline();
-    this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
-    this.executorFactory = opts.executorFactory;
-  }
+  /**
+   * Creates a new ORM session.
+   * @param options - Optional session options (e.g., tenantId for multi-tenancy)
+   * @returns The ORM session
+   */
+  createSession(options?: { tenantId?: string | number }): OrmSession<E> {
+    // No implicit transaction binding; callers should use Orm.transaction() for transactional work.
+    const executor = this.executorFactory.createExecutor();
+    return new OrmSession<E>({ 
+      orm: this, 
+      executor,
+      cacheManager: this.cacheManager,
+      tenantId: options?.tenantId
+    });
+  }
 
-  /**
-   * Creates a new ORM session.
-   * @param options - Optional session options
-   * @returns The ORM session
-   */
-  createSession(): OrmSession<E> {
-    // No implicit transaction binding; callers should use Orm.transaction() for transactional work.
-    const executor = this.executorFactory.createExecutor();
-    return new OrmSession<E>({ orm: this, executor });
-  }
-
-  /**
-   * Executes a function within a transaction.
-   * @template T - The return type
-   * @param fn - The function to execute
-   * @returns The result of the function
-   * @throws If the transaction fails
-   */
-  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
-    const executor = this.executorFactory.createTransactionalExecutor();
-    const session = new OrmSession<E>({ orm: this, executor });
-    try {
-      // A real transaction scope: begin before running user code, commit/rollback after.
-      return await session.transaction(() => fn(session));
-    } finally {
-      await session.dispose();
-    }
-  }
+  /**
+   * Executes a function within a transaction.
+   * @template T - The return type
+   * @param fn - The function to execute
+   * @returns The result of the function
+   * @throws If the transaction fails
+   */
+  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
+    const executor = this.executorFactory.createTransactionalExecutor();
+    const session = new OrmSession<E>({ 
+      orm: this, 
+      executor,
+      cacheManager: this.cacheManager
+    });
+    try {
+      // A real transaction scope: begin before running user code, commit/rollback after.
+      return await session.transaction(() => fn(session));
+    } finally {
+      await session.dispose();
+    }
+  }
 
   /**
    * Shuts down the ORM and releases underlying resources (pools, timers).

package/src/orm/unit-of-work.ts

@@ -198,12 +198,13 @@ export class UnitOfWork {
 
     const payload = this.extractColumns(tracked.table, tracked.entity as Record<string, unknown>);
     let builder = new InsertQueryBuilder(tracked.table).values(payload as Record<string, ValueOperandInput>);
-    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 = EntityStatus.Managed;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity as Record<string, unknown>);
@@ -234,7 +235,7 @@ export class UnitOfWork {
       .set(changes)
       .where(eq(pkColumn, tracked.pk));
 
-    if (this.dialect.supportsReturning()) {
+    if (this.dialect.supportsDmlReturningClause()) {
       builder = builder.returning(...this.getReturningColumns(tracked.table));
     }
 
@@ -345,9 +346,8 @@ export class UnitOfWork {
    * @param results - Query results
    */
   private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
-    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++) {
@@ -357,6 +357,24 @@ export class UnitOfWork {
     }
   }
 
+  /**
+   * 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)
+   */
+  private applyInsertedIdIfAbsent(tracked: TrackedEntity, results: QueryResult[]): void {
+    const pkName = findPrimaryKey(tracked.table);
+    const current = (tracked.entity as Record<string, unknown>)[pkName];
+    if (current != null) return;
+
+    const first = results[0];
+    const insertId = first?.meta?.insertId;
+    if (insertId == null) return;
+
+    (tracked.entity as Record<string, unknown>)[pkName] = insertId;
+  }
+
   /**
    * Normalizes a column name by removing quotes and table prefixes.
    * @param column - The column name to normalize

package/src/query-builder/select/cache-facet.ts

@@ -0,0 +1,67 @@
+import type { CacheOptions, CacheState, Duration } from '../../cache/cache-interfaces.js';
+
+/**
+ * Facet para gerenciar estado de cache no SelectQueryBuilder
+ * Segue o padrão de facets existente no projeto
+ */
+export interface CacheFacetContext {
+  state: CacheState;
+}
+
+export class CacheFacet {
+  /**
+   * Configura opções de cache no contexto
+   */
+  cache(
+    context: CacheFacetContext,
+    options: CacheOptions
+  ): CacheFacetContext {
+    return {
+      state: {
+        ...context.state,
+        options,
+      },
+    };
+  }
+
+  /**
+   * Obtém as opções de cache do contexto
+   */
+  getOptions(context: CacheFacetContext): CacheOptions | undefined {
+    return context.state.options;
+  }
+
+  /**
+   * Verifica se há configuração de cache
+   */
+  hasCache(context: CacheFacetContext): boolean {
+    return context.state.options !== undefined;
+  }
+
+  /**
+   * Cria opções de cache a partir de parâmetros variados
+   * API flexível para diferentes casos de uso
+   */
+  static createOptions(
+    key: string,
+    ttl: Duration,
+    tagsOrConfig?: string[] | { tags?: string[]; autoInvalidate?: boolean }
+  ): CacheOptions {
+    let tags: string[] | undefined;
+    let autoInvalidate: boolean | undefined;
+
+    if (Array.isArray(tagsOrConfig)) {
+      tags = tagsOrConfig;
+    } else if (tagsOrConfig) {
+      tags = tagsOrConfig.tags;
+      autoInvalidate = tagsOrConfig.autoInvalidate;
+    }
+
+    return {
+      key,
+      ttl,
+      tags,
+      autoInvalidate,
+    };
+  }
+}

package/src/query-builder/select.ts

@@ -67,9 +67,11 @@ import { SelectProjectionFacet } from './select/projection-facet.js';
 import { SelectPredicateFacet } from './select/predicate-facet.js';
 import { SelectCTEFacet } from './select/cte-facet.js';
 import { SelectSetOpFacet } from './select/setop-facet.js';
-import { SelectRelationFacet } from './select/relation-facet.js';
-
-type ColumnSelectionValue =
+import { SelectRelationFacet } from './select/relation-facet.js';
+import { CacheFacet, CacheFacetContext } from './select/cache-facet.js';
+import type { Duration } from '../cache/cache-interfaces.js';
+
+type ColumnSelectionValue =
   | ColumnDef
   | FunctionNode
   | CaseExpressionNode
@@ -119,26 +121,29 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   private readonly relationFacet: SelectRelationFacet;
   private readonly lazyRelations: Set<string>;
   private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
-  private readonly entityConstructor?: EntityConstructor;
-  private readonly includeTree: NormalizedRelationIncludeTree;
-
-  /**
-   * Creates a new SelectQueryBuilder instance
+  private readonly entityConstructor?: EntityConstructor;
+  private readonly includeTree: NormalizedRelationIncludeTree;
+  private readonly cacheFacet: CacheFacet;
+  private readonly cacheContext: CacheFacetContext;
+
+  /**
+   * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
    * @param state - Optional initial query state
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(
-    table: TTable,
-    state?: SelectQueryState,
-    hydration?: HydrationManager,
-    dependencies?: Partial<SelectQueryBuilderDependencies>,
-    lazyRelations?: Set<string>,
-    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
-    entityConstructor?: EntityConstructor,
-    includeTree?: NormalizedRelationIncludeTree
-  ) {
+  constructor(
+    table: TTable,
+    state?: SelectQueryState,
+    hydration?: HydrationManager,
+    dependencies?: Partial<SelectQueryBuilderDependencies>,
+    lazyRelations?: Set<string>,
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
+    entityConstructor?: EntityConstructor,
+    includeTree?: NormalizedRelationIncludeTree,
+    cacheContext?: CacheFacetContext
+  ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState: SelectQueryState) => deps.createQueryAstService(table, nextState);
@@ -150,9 +155,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     };
     this.lazyRelations = new Set(lazyRelations ?? []);
     this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
-    this.entityConstructor = entityConstructor;
-    this.includeTree = includeTree ?? {};
-    this.columnSelector = deps.createColumnSelector(this.env);
+    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);
     this.joinFacet = new SelectJoinFacet(this.env, createAstService);
@@ -169,23 +176,25 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  private clone<TNext = T>(
-    context: SelectQueryBuilderContext = this.context,
-    lazyRelations = new Set(this.lazyRelations),
-    lazyRelationOptions = new Map(this.lazyRelationOptions),
-    includeTree = this.includeTree
-  ): SelectQueryBuilder<TNext, TTable> {
-    return new SelectQueryBuilder(
-      this.env.table as TTable,
-      context.state,
-      context.hydration,
-      this.env.deps,
-      lazyRelations,
-      lazyRelationOptions,
-      this.entityConstructor,
-      includeTree
-    ) as SelectQueryBuilder<TNext, TTable>;
-  }
+  private clone<TNext = T>(
+    context: SelectQueryBuilderContext = this.context,
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions),
+    includeTree = this.includeTree,
+    cacheContext = this.cacheContext
+  ): SelectQueryBuilder<TNext, TTable> {
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions,
+      this.entityConstructor,
+      includeTree,
+      cacheContext
+    ) as SelectQueryBuilder<TNext, TTable>;
+  }
 
   /**
    * Applies an alias to the root FROM table.
@@ -741,25 +750,84 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     return this;
   }
 
-  /**
-   * 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.
-   *
-   * @param ctx - ORM session context
-   * @returns Promise of entity instances (or objects if generic T is not an entity)
-   * @example
-   * const users = await selectFromEntity(User).execute(session);
-   * // users is User[]
-   * users[0] instanceof User; // true
-   */
-  async execute(ctx: OrmSession): Promise<T[]> {
-    if (this.entityConstructor) {
-      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
-    }
-    const builder = this.ensureDefaultSelection();
-    return executeHydrated(ctx, builder) as unknown as T[];
-  }
+  /**
+   * 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: string,
+    ttl: Duration,
+    tagsOrConfig?: string[] | { tags?: string[]; autoInvalidate?: boolean }
+  ): SelectQueryBuilder<T, TTable> {
+    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)
+   * @example
+   * const users = await selectFromEntity(User).execute(session);
+   * // users is User[]
+   * users[0] instanceof User; // true
+   */
+  async execute(ctx: OrmSession): Promise<T[]> {
+    const cacheOptions = this.cacheFacet.getOptions(this.cacheContext);
+    
+    // Se não tem cache configurado ou não há cache manager, executa normalmente
+    if (!cacheOptions || !ctx.cacheManager) {
+      return this.executeWithoutCache(ctx);
+    }
+
+    // Executa com cache
+    return ctx.cacheManager.getOrExecute(
+      cacheOptions,
+      () => this.executeWithoutCache(ctx),
+      ctx.tenantId
+    );
+  }
+
+  /**
+   * Executa a query sem cache (método interno)
+   */
+  private async executeWithoutCache(ctx: OrmSession): Promise<T[]> {
+    if (this.entityConstructor) {
+      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
+    }
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder) as unknown as T[];
+  }
 
   /**
    * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.