metal-orm 1.0.40 → 1.0.42

package/src/core/execution/db-executor.ts

@@ -7,11 +7,20 @@ export type QueryResult = {
 };
 
 export interface DbExecutor {
+  /** Capability flags so the runtime can make correct decisions without relying on optional methods. */
+  readonly capabilities: {
+    /** True if begin/commit/rollback are real and should be used to provide atomicity. */
+    transactions: boolean;
+  };
+
   executeSql(sql: string, params?: unknown[]): Promise<QueryResult[]>;
 
-  beginTransaction?(): Promise<void>;
-  commitTransaction?(): Promise<void>;
-  rollbackTransaction?(): Promise<void>;
+  beginTransaction(): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+
+  /** Release any underlying resources (connections, pool leases, etc). Must be idempotent. */
+  dispose(): Promise<void>;
 }
 
 // --- helpers ---
@@ -39,9 +48,14 @@ export interface SimpleQueryRunner {
     sql: string,
     params?: unknown[]
   ): Promise<Array<Record<string, unknown>>>;
+
+  /** Optional: used to support real transactions. */
   beginTransaction?(): Promise<void>;
   commitTransaction?(): Promise<void>;
   rollbackTransaction?(): Promise<void>;
+
+  /** Optional: release resources (connection close, pool lease release, etc). */
+  dispose?(): Promise<void>;
 }
 
 /**
@@ -50,14 +64,40 @@ export interface SimpleQueryRunner {
 export function createExecutorFromQueryRunner(
   runner: SimpleQueryRunner
 ): DbExecutor {
+  const supportsTransactions =
+    typeof runner.beginTransaction === 'function' &&
+    typeof runner.commitTransaction === 'function' &&
+    typeof runner.rollbackTransaction === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const rows = await runner.query(sql, params);
       const result = rowsToQueryResult(rows);
       return [result];
     },
-    beginTransaction: runner.beginTransaction?.bind(runner),
-    commitTransaction: runner.commitTransaction?.bind(runner),
-    rollbackTransaction: runner.rollbackTransaction?.bind(runner),
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await runner.beginTransaction!.call(runner);
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await runner.commitTransaction!.call(runner);
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await runner.rollbackTransaction!.call(runner);
+    },
+    async dispose() {
+      await runner.dispose?.call(runner);
+    },
   };
 }

package/src/core/execution/executors/mssql-executor.ts

@@ -17,23 +17,40 @@ export interface MssqlClientLike {
 export function createMssqlExecutor(
   client: MssqlClientLike
 ): DbExecutor {
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commit === 'function' &&
+    typeof client.rollback === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const { recordset } = await client.query(sql, params);
       const result = rowsToQueryResult(recordset ?? []);
       return [result];
     },
     async beginTransaction() {
-      if (!client.beginTransaction) return;
-      await client.beginTransaction();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.beginTransaction!();
     },
     async commitTransaction() {
-      if (!client.commit) return;
-      await client.commit();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.commit!();
     },
     async rollbackTransaction() {
-      if (!client.rollback) return;
-      await client.rollback();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollback!();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
     },
   };
 }
@@ -53,7 +70,7 @@ export interface TediousRequest {
 }
 
 export interface TediousRequestCtor {
-  new (sql: string, callback: (err?: Error | null) => void): TediousRequest;
+  new(sql: string, callback: (err?: Error | null) => void): TediousRequest;
 }
 
 export interface TediousTypes {
@@ -140,29 +157,29 @@ export function createTediousMssqlClient(
 
     beginTransaction: connection.beginTransaction
       ? () =>
-          new Promise<void>((resolve, reject) => {
-            connection.beginTransaction!(err =>
-              err ? reject(err) : resolve()
-            );
-          })
+        new Promise<void>((resolve, reject) => {
+          connection.beginTransaction!(err =>
+            err ? reject(err) : resolve()
+          );
+        })
       : undefined,
 
     commit: connection.commitTransaction
       ? () =>
-          new Promise<void>((resolve, reject) => {
-            connection.commitTransaction!(err =>
-              err ? reject(err) : resolve()
-            );
-          })
+        new Promise<void>((resolve, reject) => {
+          connection.commitTransaction!(err =>
+            err ? reject(err) : resolve()
+          );
+        })
       : undefined,
 
     rollback: connection.rollbackTransaction
       ? () =>
-          new Promise<void>((resolve, reject) => {
-            connection.rollbackTransaction!(err =>
-              err ? reject(err) : resolve()
-            );
-          })
+        new Promise<void>((resolve, reject) => {
+          connection.rollbackTransaction!(err =>
+            err ? reject(err) : resolve()
+          );
+        })
       : undefined,
   };
 }

package/src/core/execution/executors/mysql-executor.ts

@@ -17,7 +17,15 @@ export interface MysqlClientLike {
 export function createMysqlExecutor(
   client: MysqlClientLike
 ): DbExecutor {
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commit === 'function' &&
+    typeof client.rollback === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params as any[]);
 
@@ -32,16 +40,25 @@ export function createMysqlExecutor(
       return [result];
     },
     async beginTransaction() {
-      if (!client.beginTransaction) return;
-      await client.beginTransaction();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.beginTransaction!();
     },
     async commitTransaction() {
-      if (!client.commit) return;
-      await client.commit();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.commit!();
     },
     async rollbackTransaction() {
-      if (!client.rollback) return;
-      await client.rollback();
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollback!();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
     },
   };
 }

package/src/core/execution/executors/sqlite-executor.ts

@@ -18,14 +18,40 @@ export interface SqliteClientLike {
 export function createSqliteExecutor(
   client: SqliteClientLike
 ): DbExecutor {
+  const supportsTransactions =
+    typeof client.beginTransaction === 'function' &&
+    typeof client.commitTransaction === 'function' &&
+    typeof client.rollbackTransaction === 'function';
+
   return {
+    capabilities: {
+      transactions: supportsTransactions,
+    },
     async executeSql(sql, params) {
       const rows = await client.all(sql, params);
       const result = rowsToQueryResult(rows);
       return [result];
     },
-    beginTransaction: client.beginTransaction?.bind(client),
-    commitTransaction: client.commitTransaction?.bind(client),
-    rollbackTransaction: client.rollbackTransaction?.bind(client),
+    async beginTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.beginTransaction!();
+    },
+    async commitTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.commitTransaction!();
+    },
+    async rollbackTransaction() {
+      if (!supportsTransactions) {
+        throw new Error('Transactions are not supported by this executor');
+      }
+      await client.rollbackTransaction!();
+    },
+    async dispose() {
+      // Connection lifecycle is owned by the caller/driver. Pool lease executors should implement dispose.
+    },
   };
 }

package/src/core/execution/pooling/pool-types.ts

@@ -0,0 +1,30 @@
+export type PoolOptions = {
+    /** Maximum number of live resources (idle + leased). */
+    max: number;
+    /** Minimum number of idle resources to keep warm (best-effort). */
+    min?: number;
+
+    /** How long an idle resource can sit before being destroyed. */
+    idleTimeoutMillis?: number;
+    /** How often to reap idle resources. Defaults to idleTimeoutMillis / 2 (min 1s). */
+    reapIntervalMillis?: number;
+
+    /** How long callers wait for a resource before acquire() rejects. */
+    acquireTimeoutMillis?: number;
+};
+
+export interface PoolAdapter<TResource> {
+    create(): Promise<TResource>;
+    destroy(resource: TResource): Promise<void>;
+    validate?(resource: TResource): Promise<boolean>;
+}
+
+export interface PoolLease<TResource> {
+    readonly resource: TResource;
+
+    /** Returns the resource to the pool. Idempotent. */
+    release(): Promise<void>;
+    /** Permanently removes the resource from the pool. Idempotent. */
+    destroy(): Promise<void>;
+}
+

package/src/core/execution/pooling/pool.ts

@@ -0,0 +1,268 @@
+import type { PoolAdapter, PoolLease, PoolOptions } from './pool-types.js';
+
+type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (err: unknown) => void;
+};
+
+const deferred = <T>(): Deferred<T> => {
+    let resolve!: (value: T) => void;
+    let reject!: (err: unknown) => void;
+    const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+};
+
+type IdleEntry<T> = {
+    resource: T;
+    lastUsedAt: number;
+};
+
+export class Pool<TResource> {
+    private readonly adapter: PoolAdapter<TResource>;
+    private readonly options: Required<Pick<PoolOptions, 'max'>> & PoolOptions;
+
+    private destroyed = false;
+    private creating = 0;
+    private leased = 0;
+    private readonly idle: IdleEntry<TResource>[] = [];
+    private readonly waiters: Array<Deferred<PoolLease<TResource>>> = [];
+    private reapTimer: ReturnType<typeof setInterval> | null = null;
+
+    constructor(adapter: PoolAdapter<TResource>, options: PoolOptions) {
+        if (!Number.isFinite(options.max) || options.max <= 0) {
+            throw new Error('Pool options.max must be a positive number');
+        }
+
+        this.adapter = adapter;
+        this.options = { max: options.max, ...options };
+
+        const idleTimeout = this.options.idleTimeoutMillis;
+        if (idleTimeout && idleTimeout > 0) {
+            const interval =
+                this.options.reapIntervalMillis ?? Math.max(1_000, Math.floor(idleTimeout / 2));
+            this.reapTimer = setInterval(() => {
+                void this.reapIdle();
+            }, interval);
+
+            // Best-effort: avoid keeping the event loop alive.
+            (this.reapTimer as any).unref?.();
+        }
+
+        // Best-effort warmup.
+        const min = this.options.min ?? 0;
+        if (min > 0) {
+            void this.warm(min);
+        }
+    }
+
+    /**
+     * Acquire a resource lease.
+     * The returned lease MUST be released or destroyed.
+     */
+    async acquire(): Promise<PoolLease<TResource>> {
+        if (this.destroyed) {
+            throw new Error('Pool is destroyed');
+        }
+
+        // 1) Prefer idle.
+        const idle = await this.takeIdleValidated();
+        if (idle) {
+            this.leased++;
+            return this.makeLease(idle);
+        }
+
+        // 2) Create if capacity allows.
+        if (this.totalLive() < this.options.max) {
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.leased++;
+                return this.makeLease(created);
+            } finally {
+                this.creating--;
+            }
+        }
+
+        // 3) Wait.
+        const waiter = deferred<PoolLease<TResource>>();
+        this.waiters.push(waiter);
+
+        const timeout = this.options.acquireTimeoutMillis;
+        let timer: ReturnType<typeof setTimeout> | null = null;
+        if (timeout && timeout > 0) {
+            timer = setTimeout(() => {
+                // Remove from queue if still waiting.
+                const idx = this.waiters.indexOf(waiter);
+                if (idx >= 0) this.waiters.splice(idx, 1);
+                waiter.reject(new Error('Pool acquire timeout'));
+            }, timeout);
+            (timer as any).unref?.();
+        }
+
+        try {
+            return await waiter.promise;
+        } finally {
+            if (timer) clearTimeout(timer);
+        }
+    }
+
+    /** Destroy pool and all idle resources; waits for in-flight creations to settle. */
+    async destroy(): Promise<void> {
+        if (this.destroyed) return;
+        this.destroyed = true;
+
+        if (this.reapTimer) {
+            clearInterval(this.reapTimer);
+            this.reapTimer = null;
+        }
+
+        // Reject all waiters.
+        while (this.waiters.length) {
+            this.waiters.shift()!.reject(new Error('Pool destroyed'));
+        }
+
+        // Destroy idle resources.
+        while (this.idle.length) {
+            const entry = this.idle.shift()!;
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+
+    private totalLive(): number {
+        return this.idle.length + this.leased + this.creating;
+    }
+
+    private makeLease(resource: TResource): PoolLease<TResource> {
+        let done = false;
+        return {
+            resource,
+            release: async () => {
+                if (done) return;
+                done = true;
+                await this.releaseResource(resource);
+            },
+            destroy: async () => {
+                if (done) return;
+                done = true;
+                await this.destroyResource(resource);
+            },
+        };
+    }
+
+    private async releaseResource(resource: TResource): Promise<void> {
+        this.leased = Math.max(0, this.leased - 1);
+        if (this.destroyed) {
+            await this.adapter.destroy(resource);
+            return;
+        }
+
+        // Prefer handing directly to waiters.
+        const next = this.waiters.shift();
+        if (next) {
+            this.leased++;
+            next.resolve(this.makeLease(resource));
+            return;
+        }
+
+        this.idle.push({ resource, lastUsedAt: Date.now() });
+        await this.trimToMinMax();
+    }
+
+    private async destroyResource(resource: TResource): Promise<void> {
+        this.leased = Math.max(0, this.leased - 1);
+        await this.adapter.destroy(resource);
+
+        // If there are waiters and we have capacity, create a replacement.
+        if (!this.destroyed && this.waiters.length && this.totalLive() < this.options.max) {
+            const waiter = this.waiters.shift()!;
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.leased++;
+                waiter.resolve(this.makeLease(created));
+            } catch (err) {
+                waiter.reject(err);
+            } finally {
+                this.creating--;
+            }
+        }
+    }
+
+    private async takeIdleValidated(): Promise<TResource | null> {
+        while (this.idle.length) {
+            const entry = this.idle.pop()!;
+            if (!this.adapter.validate) {
+                return entry.resource;
+            }
+            const ok = await this.adapter.validate(entry.resource);
+            if (ok) {
+                return entry.resource;
+            }
+            await this.adapter.destroy(entry.resource);
+        }
+        return null;
+    }
+
+    private async reapIdle(): Promise<void> {
+        if (this.destroyed) return;
+        const idleTimeout = this.options.idleTimeoutMillis;
+        if (!idleTimeout || idleTimeout <= 0) return;
+
+        const now = Date.now();
+        const min = this.options.min ?? 0;
+
+        // Remove expired resources beyond min.
+        const keep: IdleEntry<TResource>[] = [];
+        const kill: IdleEntry<TResource>[] = [];
+        for (const entry of this.idle) {
+            const expired = now - entry.lastUsedAt >= idleTimeout;
+            if (expired) kill.push(entry);
+            else keep.push(entry);
+        }
+
+        // Keep at least `min`.
+        while (keep.length < min && kill.length) {
+            keep.push(kill.pop()!);
+        }
+
+        this.idle.length = 0;
+        this.idle.push(...keep);
+
+        for (const entry of kill) {
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+
+    private async warm(targetMin: number): Promise<void> {
+        const min = Math.max(0, targetMin);
+        while (!this.destroyed && this.idle.length < min && this.totalLive() < this.options.max) {
+            this.creating++;
+            try {
+                const created = await this.adapter.create();
+                this.idle.push({ resource: created, lastUsedAt: Date.now() });
+            } catch {
+                // If warmup fails, stop trying.
+                break;
+            } finally {
+                this.creating--;
+            }
+        }
+    }
+
+    private async trimToMinMax(): Promise<void> {
+        const max = this.options.max;
+        const min = this.options.min ?? 0;
+
+        // Ensure we don't exceed max in idle (best-effort; leased/creating already counted elsewhere).
+        while (this.totalLive() > max && this.idle.length > min) {
+            const entry = this.idle.shift();
+            if (!entry) break;
+            await this.adapter.destroy(entry.resource);
+        }
+    }
+}
+

package/src/decorators/bootstrap.ts

@@ -31,22 +31,22 @@ const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget
 
 const resolveTableTarget = (
   target: EntityOrTableTargetResolver,
-  tableMap: Map<EntityConstructor, TableDef>
+  tableMap: Map<EntityConstructor<any>, TableDef>
 ): TableDef => {
   const resolved = unwrapTarget(target);
   if (isTableDef(resolved)) {
     return resolved;
   }
-  const table = tableMap.get(resolved as EntityConstructor);
+  const table = tableMap.get(resolved as EntityConstructor<any>);
   if (!table) {
-    throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
+    throw new Error(`Entity '${(resolved as EntityConstructor<any>).name}' is not registered with decorators`);
   }
   return table;
 };
 
 const buildRelationDefinitions = (
   meta: { relations: Record<string, RelationMetadata> },
-  tableMap: Map<EntityConstructor, TableDef>
+  tableMap: Map<EntityConstructor<any>, TableDef>
 ): Record<string, RelationDef> => {
   const relations: Record<string, RelationDef> = {};
 
@@ -103,7 +103,7 @@ const buildRelationDefinitions = (
 
 export const bootstrapEntities = (): TableDef[] => {
   const metas = getAllEntityMetadata();
-  const tableMap = new Map<EntityConstructor, TableDef>();
+  const tableMap = new Map<EntityConstructor<any>, TableDef>();
 
   for (const meta of metas) {
     const table = buildTableDef(meta);
@@ -119,7 +119,7 @@ export const bootstrapEntities = (): TableDef[] => {
   return metas.map(meta => meta.table!) as TableDef[];
 };
 
-export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor): TTable | undefined => {
+export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>): TTable | undefined => {
   const meta = getEntityMetadata(ctor);
   if (!meta) return undefined;
   if (!meta.table) {
@@ -129,7 +129,7 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
 };
 
 export const selectFromEntity = <TTable extends TableDef = TableDef>(
-  ctor: EntityConstructor
+  ctor: EntityConstructor<any>
 ): SelectQueryBuilder<any, TTable> => {
   const table = getTableDefFromEntity(ctor);
   if (!table) {

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './query-builder/insert.js';
 export * from './query-builder/update.js';
 export * from './query-builder/delete.js';
 export * from './core/ast/expression.js';
+export * from './core/ast/window-functions.js';
 export * from './core/hydration/types.js';
 export * from './core/dialect/mysql/index.js';
 export * from './core/dialect/mssql/index.js';
@@ -42,7 +43,12 @@ export * from './decorators/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';
+export * from './core/execution/pooling/pool-types.js';
+export * from './core/execution/pooling/pool.js';
 export * from './core/execution/executors/postgres-executor.js';
 export * from './core/execution/executors/mysql-executor.js';
 export * from './core/execution/executors/sqlite-executor.js';
 export * from './core/execution/executors/mssql-executor.js';
+
+// NEW: first-class pooling integration
+export * from './orm/pooled-executor-factory.js';