or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-structures.mdindex.mdpool-lifecycle.mdpool-management.mdpool-monitoring.mdresource-operations.md
tile.json

index.mddocs/

Generic Pool

Generic Pool is a Node.js resource pooling library that provides a Promise-based API for managing and reusing expensive resources such as database connections, network connections, or any costly-to-create objects. It offers comprehensive configuration options including pool sizing, resource validation, priority queueing, idle resource eviction, and automatic resource lifecycle management.

Package Information

  • Package Name: generic-pool
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install generic-pool

Core Imports

const genericPool = require('generic-pool');
const pool = genericPool.createPool(factory, options);

ES Modules:

import * as genericPool from 'generic-pool';
const pool = genericPool.createPool(factory, options);

Destructured imports:

const { createPool, Pool, Deque, PriorityQueue, DefaultEvictor } = require('generic-pool');

Basic Usage

const genericPool = require('generic-pool');

// Define factory for creating/destroying resources
const factory = {
  create: function() {
    // Return a promise that resolves to a resource
    return Promise.resolve(someExpensiveResource());
  },
  destroy: function(resource) {
    // Return a promise that resolves when resource is destroyed
    return Promise.resolve(resource.close());
  }
};

// Create pool with configuration
const pool = genericPool.createPool(factory, {
  max: 10, // maximum pool size
  min: 2   // minimum pool size
});

// Use the pool
async function doWork() {
  const resource = await pool.acquire();
  try {
    // Use the resource
    const result = await resource.doSomething();
    return result;
  } finally {
    // Always return resource to pool
    pool.release(resource);
  }
}

// Graceful shutdown
await pool.drain();
await pool.clear();

Architecture

Generic Pool is built around several key components:

  • Pool Management: Core Pool class that manages resource lifecycle, borrowing, and returning
  • Resource Factory: User-defined factory interface for creating, destroying, and optionally validating resources
  • Queue Management: Priority-based queuing system for pending resource requests using PriorityQueue
  • Resource Tracking: Internal tracking of resource states (available, borrowed, in validation, etc.)
  • Eviction System: Configurable idle resource eviction using DefaultEvictor or custom evictors
  • Event System: EventEmitter-based error handling and lifecycle notifications

Capabilities

Pool Creation and Management

Core functionality for creating and managing resource pools with comprehensive configuration options.

function createPool(factory, options);

interface Factory {
  create(): Promise<any>;
  destroy(resource: any): Promise<void>;
  validate?(resource: any): Promise<boolean>;
}

interface Options {
  max?: number;
  min?: number;
  maxWaitingClients?: number;
  testOnBorrow?: boolean;
  testOnReturn?: boolean;
  acquireTimeoutMillis?: number;
  destroyTimeoutMillis?: number;
  fifo?: boolean;
  priorityRange?: number;
  autostart?: boolean;
  evictionRunIntervalMillis?: number;
  numTestsPerEvictionRun?: number;
  softIdleTimeoutMillis?: number;
  idleTimeoutMillis?: number;
  Promise?: typeof Promise;
}

Pool Management

Resource Operations

Core operations for acquiring, releasing, and destroying pooled resources with optional priority support.

class Pool extends EventEmitter {
  acquire(priority?: number): Promise<any>;
  release(resource: any): Promise<void>;
  destroy(resource: any): Promise<void>;
  use(fn: (resource: any) => Promise<any>, priority?: number): Promise<any>;
  isBorrowedResource(resource: any): boolean;
}

Resource Operations

Pool Lifecycle

Methods for starting, draining, and managing pool lifecycle with graceful shutdown capabilities.

class Pool extends EventEmitter {
  start(): void;
  ready(): Promise<void>;
  drain(): Promise<void>;
  clear(): Promise<void>;
}

Pool Lifecycle

Pool Monitoring

Properties and methods for monitoring pool state, capacity, and resource utilization.

class Pool extends EventEmitter {
  readonly spareResourceCapacity: number;
  readonly size: number;
  readonly available: number;
  readonly borrowed: number;
  readonly pending: number;
  readonly max: number;
  readonly min: number;
}

Pool Monitoring

Data Structures

Utility data structures used internally by the pool, also available for external use.

class Deque {
  constructor();
  shift(): any;
  unshift(element: any): void;
  push(element: any): void;
  pop(): any;
  readonly head: any;
  readonly tail: any;
  readonly length: number;
}

class PriorityQueue {
  constructor(size: number);
  enqueue(obj: any, priority: number): void;
  dequeue(): any;
  readonly length: number;
  readonly head: any;
  readonly tail: any;
}

Data Structures

Types

class Pool extends EventEmitter {
  // Pool implementation
}

interface Factory {
  create(): Promise<any>;
  destroy(resource: any): Promise<void>;
  validate?(resource: any): Promise<boolean>;
}

interface Options {
  max?: number;
  min?: number;
  maxWaitingClients?: number;
  testOnBorrow?: boolean;
  testOnReturn?: boolean;
  acquireTimeoutMillis?: number;
  destroyTimeoutMillis?: number;
  fifo?: boolean;
  priorityRange?: number;
  autostart?: boolean;
  evictionRunIntervalMillis?: number;
  numTestsPerEvictionRun?: number;
  softIdleTimeoutMillis?: number;
  idleTimeoutMillis?: number;
  Promise?: typeof Promise;
}