tessl/npm-generic-pool

Generic resource pooling for Node.js applications with Promise-based API for efficient management of expensive resources.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Generic Pool

Name: tessl/npm-generic-pool
Author: tessl

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;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/generic-pool@3.9.x
Publish Source: CLI
Badge