# coopernurse/node-pool architecture

> Architecture diagram of the GitHub repository coopernurse/node-pool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coopernurse/node-pool
- Repository: https://github.com/coopernurse/node-pool

## Overview

##### Project Type and Core Purpose
This is an open-source utility library that manages reusable resources (like database connections) with a Promise-based API. The main purpose is to provide efficient resource pooling with features like priority queuing and idle resource eviction.

##### Main Components

A. Core Pool Management Layer:
- Pool (central component)
- PooledResource (wrapper for actual resources)
- ResourceLoan (tracks borrowed resources)
- ResourceRequest (handles resource acquisition requests)

B. Queue Management Layer:
- PriorityQueue
- Queue
- Deque
- DoublyLinkedList (underlying data structure)

C. Resource Lifecycle Management:
- DefaultEvictor (handles idle resource cleanup)
- PoolDefaults (configuration)
- Factory Interface (create/destroy/validate)

**Rectangle: Core components**
**Hexagon: Interfaces**
**Diamond: Decision points**

**Blue: Core pool management**
**Green: Queue/Data structures**
**Orange: Resource lifecycle**
**Gray: External resources/clients**

##### Component Relationships

**Client Application**
- ↓
- Pool
- ↙ ↓ ↘
**Factory  PriorityQueue  Evictor**
- ↓         ↓            ↓
**Resources  Queue/Deque  Cleanup**

##### Key Flows to Illustrate

a. Resource Acquisition Flow:
- Client → Pool → PriorityQueue → Factory.create → PooledResource

b. Resource Release Flow:
- Client → Pool → Resource Validation → Queue/Destroy

c. Eviction Flow:
- Evictor → Pool → Idle Resources → Factory.destroy

##### Important Details

- Configuration options (max, min, timeout settings)
- Event emission points
- Priority queue levels
- Resource states (available, borrowed, pending)
- Validation checkpoints

##### Implementation Notes

- Promise-based asynchronous operations
- FIFO/LIFO configuration options
- Priority queueing system (0 to priorityRange-1)
- Resource lifecycle management
- Error handling paths

##### Specific Recommendations

- Top: Client interaction layer
- Middle: Pool management layer
- Bottom: Resource management layer

- Resource borrowing/returning
- Event propagation
- State transitions

- Resource states
- Priority levels
- Configuration options
- Event types

d. Notes for important behaviors:
- Drain/Clear operations
- Timeout handling
- Error propagation
- Resource validation

Remember to include the factory interface as a key integration point, as this is how users will implement their specific resource types.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Application Layer"]
        CL[Client Application]
    end

    subgraph Core["Core Pool Management"]
        Pool["Pool Manager"]:::core
        PRes["PooledResource"]:::core
        ResLoan["ResourceLoan"]:::core
        ResReq["ResourceRequest"]:::core
        PoolOpt["Pool Options"]:::config
        PoolDef["Pool Defaults"]:::config
    end

    subgraph Queue["Queue Management System"]
        PQ["PriorityQueue"]:::queue
        Q["Queue"]:::queue
        DQ["Deque"]:::queue
        DLL["DoublyLinkedList"]:::queue
    end

    subgraph Resource["Resource Lifecycle"]
        FV["Factory Validator"]:::lifecycle
        DE["DefaultEvictor"]:::lifecycle
        RSM["Resource State Manager"]:::lifecycle
        EH["Error Handler"]:::lifecycle
    end

    %% Main Entry Point
    EP["index.js"]:::entry

    %% Relationships
    CL --> EP
    EP --> Pool
    Pool --> PRes
    Pool --> ResLoan
    Pool --> ResReq
    Pool --> PoolOpt
    Pool --> PoolDef
    
    PQ --> Q
    Q --> DQ
    DQ --> DLL
    
    Pool --> PQ
    Pool --> FV
    Pool --> DE
    Pool --> RSM
    Pool --> EH

    %% Click Events
    click Pool "https://github.com/coopernurse/node-pool/blob/master/lib/Pool.js"
    click PRes "https://github.com/coopernurse/node-pool/blob/master/lib/PooledResource.js"
    click ResLoan "https://github.com/coopernurse/node-pool/blob/master/lib/ResourceLoan.js"
    click ResReq "https://github.com/coopernurse/node-pool/blob/master/lib/ResourceRequest.js"
    click PQ "https://github.com/coopernurse/node-pool/blob/master/lib/PriorityQueue.js"
    click Q "https://github.com/coopernurse/node-pool/blob/master/lib/Queue.js"
    click DQ "https://github.com/coopernurse/node-pool/blob/master/lib/Deque.js"
    click DLL "https://github.com/coopernurse/node-pool/blob/master/lib/DoublyLinkedList.js"
    click DE "https://github.com/coopernurse/node-pool/blob/master/lib/DefaultEvictor.js"
    click PoolDef "https://github.com/coopernurse/node-pool/blob/master/lib/PoolDefaults.js"
    click FV "https://github.com/coopernurse/node-pool/blob/master/lib/factoryValidator.js"
    click RSM "https://github.com/coopernurse/node-pool/blob/master/lib/PooledResourceStateEnum.js"
    click PoolOpt "https://github.com/coopernurse/node-pool/blob/master/lib/PoolOptions.js"
    click EH "https://github.com/coopernurse/node-pool/blob/master/lib/errors.js"
    click EP "https://github.com/coopernurse/node-pool/blob/master/index.js"

    %% Styles
    classDef core fill:#2374ab,stroke:#2374ab,color:#fff
    classDef queue fill:#57a773,stroke:#57a773,color:#fff
    classDef lifecycle fill:#ff8552,stroke:#ff8552,color:#fff
    classDef config fill:#797270,stroke:#797270,color:#fff
    classDef entry fill:#2b50aa,stroke:#2b50aa,color:#fff

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Queue System"]:::queue
        L3["Lifecycle Management"]:::lifecycle
        L4["Configuration"]:::config
        L5["Entry Point"]:::entry
    end
```
