1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

/**
 * Interface for objects that can be pooled.
 * Each pooled object must be able to reset itself for reuse.
 */
interface Poolable {
    /**
     * Resets the object to a clean, reusable state.
     * Called when the object is returned to the pool.
     */
    reset(): void;
 
    /**
     * Validates that the object is in a usable state.
     * Called before lending the object to a client.
     * @returns true if the object is valid and usable
     */
    validate(): boolean;
}
 
/**
 * The Object Pool manages a collection of reusable objects.
 * Generic type T must extend Poolable.
 */
interface ObjectPool<T extends Poolable> {
    /**
     * Acquires an object from the pool.
     * Blocks or fails if no objects are available (implementation-dependent).
     * @returns A ready-to-use pooled object
     */
    acquire(): T;
    
    /**
     * Acquires an object with a timeout.
     * @param timeoutMs Maximum time to wait for an available object
     * @returns The object, or null if timeout elapsed
     */
    acquireWithTimeout(timeoutMs: number): T | null;
 
    /**
     * Releases an object back to the pool.
     * The object is reset and made available for future acquisition.
     * @param obj The object to return to the pool
     */
    release(obj: T): void;
 
    /**
     * Returns the current pool statistics.
     */
    getStats(): PoolStats;
 
    /**
     * Closes the pool, destroying all pooled objects.
     * No further operations are permitted after close.
     */
    close(): void;
}
 
interface PoolStats {
    totalSize: number;          // Total objects (available + in use)
    availableCount: number;     // Objects ready to be acquired
    inUseCount: number;         // Objects currently acquired by clients
    createdCount: number;       // Total objects ever created
    destroyedCount: number;     // Total objects destroyed
    waitingCount: number;       // Clients waiting for an object
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

class ObjectPoolImpl<T extends Poolable> implements ObjectPool<T> {
    private available: T[] = [];
    private inUse: Set<T> = new Set();
    private factory: () => T;
    private maxSize: number;
    private waitQueue: Array<(obj: T) => void> = [];
 
    acquire(): T {
        // Try to get an existing object
        while (this.available.length > 0) {
            const obj = this.available.pop()!;
            
            // Validate before returning
            if (obj.validate()) {
                this.inUse.add(obj);
                return obj;
            } else {
                // Object is stale/broken, discard and try next
                this.destroyObject(obj);
            }
        }
 
        // No available objects — can we create one?
        const totalSize = this.inUse.size + this.available.length;
        if (totalSize < this.maxSize) {
            const newObj = this.factory();
            this.inUse.add(newObj);
            return newObj;
        }
 
        // Pool exhausted — must wait for a release
        return this.waitForObject();
    }
 
    private waitForObject(): T {
        return new Promise<T>((resolve) => {
            this.waitQueue.push(resolve);
        }) as unknown as T; // Simplified for illustration
    }
 
    private destroyObject(obj: T): void {
        // Cleanup resources, GC will handle memory
        if ('destroy' in obj && typeof obj.destroy === 'function') {
            (obj as any).destroy();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

release(obj: T): void {
    // Validate this object belongs to us
    if (!this.inUse.has(obj)) {
        throw new Error(
            'Attempted to release object not acquired from this pool'
        );
    }
 
    // Remove from in-use tracking
    this.inUse.delete(obj);
 
    // Reset the object to clean state
    try {
        obj.reset();
    } catch (e) {
        // Reset failed — object is corrupted, destroy it
        this.destroyObject(obj);
        return;
    }
 
    // Check if anyone is waiting
    if (this.waitQueue.length > 0) {
        const waiter = this.waitQueue.shift()!;
        this.inUse.add(obj);
        waiter(obj);
        return;
    }
 
    // No waiters — should we keep this object?
    if (this.shouldShrink()) {
        this.destroyObject(obj);
    } else {
        this.available.push(obj);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

class PooledDatabaseConnection implements Poolable {
    private connection: RawConnection;
    private transactionState: TransactionState = null;
    private sessionVariables: Map<string, string> = new Map();
    private preparedStatements: Map<string, PreparedStatement> = new Map();
    private lastUsedAt: Date;
    private lastError: Error | null = null;
 
    reset(): void {
        // 1. Roll back any pending transaction
        if (this.transactionState === TransactionState.ACTIVE) {
            this.connection.rollback();
        }
        this.transactionState = null;
 
        // 2. Clear session-specific variables
        if (this.sessionVariables.size > 0) {
            this.connection.execute('RESET ALL');
            this.sessionVariables.clear();
        }
 
        // 3. Clear any cached results or cursors
        this.connection.clearResults();
 
        // 4. Clear error state
        this.lastError = null;
 
        // 5. Update timestamps for idle tracking
        this.lastUsedAt = new Date();
 
        // NOTE: We do NOT:
        // - Close the connection (that's the expensive part)
        // - Clear prepared statements (they can be reused)
        // - Reallocate network buffers
    }
 
    validate(): boolean {
        // Check if connection is still alive
        if (!this.connection.isConnected) {
            return false;
        }
 
        // Check for stale connection (idle too long)
        const idleMs = Date.now() - this.lastUsedAt.getTime();
        if (idleMs > 30 * 60 * 1000) { // 30 minutes
            return false;
        }
 
        // Optionally: ping the database
        try {
            this.connection.execute('SELECT 1');
            return true;
        } catch {
            return false;
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

interface PoolConfig<T> {
    /** Creates a new pooled object */
    factory: () => T | Promise<T>;
    /** Resets an object for reuse */
    reset: (obj: T) => void | Promise<void>;
    /** Validates an object is still usable */
    validate?: (obj: T) => boolean | Promise<boolean>;
    /** Destroys an object (cleanup resources) */
    destroy?: (obj: T) => void | Promise<void>;
    /** Minimum objects to keep in pool */
    minSize?: number;
    /** Maximum objects allowed in pool */
    maxSize?: number;
    /** Maximum time (ms) to wait for an object */
    acquireTimeoutMs?: number;
    /** Maximum time (ms) an object can remain idle */
    idleTimeoutMs?: number;
}
 
interface PooledItem<T> {
    object: T;
    createdAt: Date;
    lastUsedAt: Date;
}
 
class GenericObjectPool<T> {
    private available: PooledItem<T>[] = [];
    private inUse: Map<T, PooledItem<T>> = new Map();
    private waitQueue: Array<{
        resolve: (item: PooledItem<T>) => void;
        reject: (error: Error) => void;
        timeoutId: NodeJS.Timeout;
    }> = [];
    
    private config: Required<PoolConfig<T>>;
    private closed: boolean = false;
    private maintenanceInterval: NodeJS.Timer | null = null;
 
    constructor(config: PoolConfig<T>) {
        this.config = {
            factory: config.factory,
            reset: config.reset,
            validate: config.validate ?? (() => true),
            destroy: config.destroy ?? (() => {}),
            minSize: config.minSize ?? 0,
            maxSize: config.maxSize ?? 10,
            acquireTimeoutMs: config.acquireTimeoutMs ?? 30000,
            idleTimeoutMs: config.idleTimeoutMs ?? 300000, // 5 minutes
        };
    }
 
    /**
     * Initializes the pool with minimum number of objects.
     * Call this before using the pool.
     */
    async initialize(): Promise<void> {
        const createPromises: Promise<void>[] = [];
        
        for (let i = 0; i < this.config.minSize; i++) {
            createPromises.push(this.createAndAddObject());
        }
        
        await Promise.all(createPromises);
        
        // Start maintenance routine
        this.maintenanceInterval = setInterval(
            () => this.performMaintenance(),
            60000 // Every minute
        );
    }
 
    private async createAndAddObject(): Promise<void> {
        const obj = await this.config.factory();
        const item: PooledItem<T> = {
            object: obj,
            createdAt: new Date(),
            lastUsedAt: new Date(),
        };
        this.available.push(item);
    }
 
    /**
     * Acquires an object from the pool.
     */
    async acquire(): Promise<T> {
        this.ensureNotClosed();
 
        // Try to get an available object
        while (this.available.length > 0) {
            const item = this.available.pop()!;
            
            if (await this.config.validate(item.object)) {
                this.inUse.set(item.object, item);
                item.lastUsedAt = new Date();
                return item.object;
            } else {
                // Object is stale, destroy it
                await this.destroyItem(item);
            }
        }
 
        // Can we create a new object?
        const totalSize = this.inUse.size + this.available.length;
        if (totalSize < this.config.maxSize) {
            try {
                const obj = await this.config.factory();
                const item: PooledItem<T> = {
                    object: obj,
                    createdAt: new Date(),
                    lastUsedAt: new Date(),
                };
                this.inUse.set(obj, item);
                return obj;
            } catch (error) {
                throw new Error(
                    `Failed to create pooled object: ${error}`
                );
            }
        }
 
        // Pool exhausted — wait for release
        return this.waitForObject();
    }
 
    private waitForObject(): Promise<T> {
        return new Promise((resolve, reject) => {
            const timeoutId = setTimeout(() => {
                // Remove from queue
                const index = this.waitQueue.findIndex(
                    w => w.resolve === resolve
                );
                if (index !== -1) {
                    this.waitQueue.splice(index, 1);
                }
                reject(new Error(
                    `Timeout waiting for pooled object (${this.config.acquireTimeoutMs}ms)`
                ));
            }, this.config.acquireTimeoutMs);
 
            this.waitQueue.push({
                resolve: (item: PooledItem<T>) => {
                    clearTimeout(timeoutId);
                    resolve(item.object);
                },
                reject,
                timeoutId,
            });
        });
    }
 
    /**
     * Releases an object back to the pool.
     */
    async release(obj: T): Promise<void> {
        const item = this.inUse.get(obj);
        
        if (!item) {
            console.warn(
                'Attempted to release object not owned by this pool'
            );
            return;
        }
 
        this.inUse.delete(obj);
 
        // If pool is closed, destroy the object
        if (this.closed) {
            await this.destroyItem(item);
            return;
        }
 
        // Reset the object
        try {
            await this.config.reset(obj);
        } catch (error) {
            // Reset failed — destroy the corrupted object
            await this.destroyItem(item);
            return;
        }
 
        item.lastUsedAt = new Date();
 
        // Check if anyone is waiting
        if (this.waitQueue.length > 0) {
            const waiter = this.waitQueue.shift()!;
            this.inUse.set(obj, item);
            waiter.resolve(item);
            return;
        }
 
        // Return to available pool
        this.available.push(item);
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

    /**
     * Performs periodic maintenance: evict idle objects, 
     * replenish minimum pool size.
     */
    private async performMaintenance(): Promise<void> {
        if (this.closed) return;
 
        const now = Date.now();
 
        // Evict idle objects above minimum size
        const toEvict: PooledItem<T>[] = [];
        
        for (let i = this.available.length - 1; i >= 0; i--) {
            const item = this.available[i];
            const idleTime = now - item.lastUsedAt.getTime();
            
            // Keep minimum objects, evict idle ones above minimum
            const totalSize = this.available.length + this.inUse.size;
            if (
                idleTime > this.config.idleTimeoutMs &&
                totalSize > this.config.minSize
            ) {
                toEvict.push(item);
                this.available.splice(i, 1);
            }
        }
 
        // Destroy evicted objects
        for (const item of toEvict) {
            await this.destroyItem(item);
        }
 
        // Replenish to minimum size
        const totalSize = this.available.length + this.inUse.size;
        const toCreate = Math.max(0, this.config.minSize - totalSize);
        
        for (let i = 0; i < toCreate; i++) {
            try {
                await this.createAndAddObject();
            } catch (error) {
                console.error('Failed to replenish pool:', error);
            }
        }
    }
 
    private async destroyItem(item: PooledItem<T>): Promise<void> {
        try {
            await this.config.destroy(item.object);
        } catch (error) {
            console.error('Error destroying pooled object:', error);
        }
    }
 
    private ensureNotClosed(): void {
        if (this.closed) {
            throw new Error('Pool is closed');
        }
    }
 
    /**
     * Returns pool statistics.
     */
    getStats(): PoolStats {
        return {
            totalSize: this.available.length + this.inUse.size,
            availableCount: this.available.length,
            inUseCount: this.inUse.size,
            waitingCount: this.waitQueue.length,
            createdCount: 0,    // Would track in production
            destroyedCount: 0,  // Would track in production
        };
    }
 
    /**
     * Closes the pool and destroys all objects.
     */
    async close(): Promise<void> {
        this.closed = true;
 
        // Stop maintenance
        if (this.maintenanceInterval) {
            clearInterval(this.maintenanceInterval);
        }
 
        // Reject all waiters
        for (const waiter of this.waitQueue) {
            clearTimeout(waiter.timeoutId);
            waiter.reject(new Error('Pool is closing'));
        }
        this.waitQueue = [];
 
        // Destroy all available objects
        for (const item of this.available) {
            await this.destroyItem(item);
        }
        this.available = [];
 
        // Note: in-use objects will be destroyed when released
    }
}

1
2
3
4
5
6
7
8
9
10
11

// The fundamental pattern: ALWAYS release in finally
async function executeQuery(query: string): Promise<Result> {
    const connection = await connectionPool.acquire();
    
    try {
        return await connection.execute(query);
    } finally {
        // This runs whether execute succeeds OR throws
        await connectionPool.release(connection);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// Define a 'using' helper that guarantees release
async function using<T, R>(
    pool: ObjectPool<T>,
    action: (obj: T) => Promise<R>
): Promise<R> {
    const obj = await pool.acquire();
    try {
        return await action(obj);
    } finally {
        await pool.release(obj);
    }
}
 
// Usage becomes simple and safe
async function getUser(userId: string): Promise<User> {
    return using(connectionPool, async (conn) => {
        const result = await conn.query(
            'SELECT * FROM users WHERE id = $1',
            [userId]
        );
        return result.rows[0];
    });
}
 
// Multiple operations in one acquire
async function transferFunds(
    fromId: string, 
    toId: string, 
    amount: number
): Promise<void> {
    return using(connectionPool, async (conn) => {
        await conn.beginTransaction();
        try {
            await conn.query(
                'UPDATE accounts SET balance = balance - $1 WHERE id = $2',
                [amount, fromId]
            );
            await conn.query(
                'UPDATE accounts SET balance = balance + $1 WHERE id = $2',
                [amount, toId]
            );
            await conn.commit();
        } catch (error) {
            await conn.rollback();
            throw error;
        }
    });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// C# using statement with IDisposable
public async Task<User> GetUserAsync(string userId)
{
    // Connection automatically returns to pool when scope exits
    await using var connection = await connectionPool.GetAsync();
    
    var result = await connection.QueryAsync(
        "SELECT * FROM users WHERE id = @id",
        new { id = userId }
    );
    
    return result.FirstOrDefault();
    
    // Connection.DisposeAsync() called here, which releases to pool
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Java try-with-resources with AutoCloseable
public User getUser(String userId) throws SQLException {
    // Connection automatically closes (returns to pool) 
    // when try block exits
    try (Connection conn = dataSource.getConnection()) {
        PreparedStatement stmt = conn.prepareStatement(
            "SELECT * FROM users WHERE id = ?"
        );
        stmt.setString(1, userId);
        
        ResultSet rs = stmt.executeQuery();
        if (rs.next()) {
            return mapUser(rs);
        }
        return null;
    }
    // conn.close() called here, which returns to pool
}