@venizia/ignis-helpers 0.0.8-10 → 0.0.8-13

package/dist/modules/index.d.ts

@@ -4,6 +4,7 @@ export * from './env';
 export * from './error';
 export * from './logger';
 export * from './network';
+export * from './pool';
 export * from './queue';
 export * from './redis';
 export * from './socket';

package/dist/modules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AAEvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AAEvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,iBAAiB,CAAC"}

package/dist/modules/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./env"), exports);
 __exportStar(require("./error"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./network"), exports);
+__exportStar(require("./pool"), exports);
 __exportStar(require("./queue"), exports);
 __exportStar(require("./redis"), exports);
 __exportStar(require("./socket"), exports);

package/dist/modules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AAEvB,2CAAyB;AACzB,wCAAsB;AACtB,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,4CAA0B;AAC1B,wCAAsB;AACtB,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AAEvB,2CAAyB;AACzB,wCAAsB;AACtB,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,yCAAuB;AACvB,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,4CAA0B;AAC1B,wCAAsB;AACtB,kDAAgC"}

package/dist/modules/pool/helper.d.ts

@@ -0,0 +1,100 @@
+import { ValueOrPromise } from '../../common/types';
+import { BaseHelper } from '../../modules/base';
+import { IPool, IPoolControlOptions, IPoolOptions, IPoolStats } from './types';
+/**
+ * Generic single-borrower object pool — skeleton.
+ *
+ * Holds all pool state and the pairing logic; subclasses supply the resource lifecycle by overriding
+ * {@link create} (required) and, optionally, {@link validateResource} / {@link resetResource} /
+ * {@link onDestroyResource}. {@link BasePoolHelper} is the concrete, callback-configured subclass.
+ *
+ * Every pairing of a resource with a waiting acquirer flows through ONE re-entrancy-guarded
+ * `dispatch()` loop, so `acquire`/`release`/`use`/`discard`/`warmup` stay thin; each loop branch
+ * delegates to a single-purpose helper (`takeIdleResource`, `createAndHand`, `handToWaiter`).
+ *
+ * The waiter queue is a generic O(1) {@link HfQueueHelper}: enqueue pushes, dequeue advances a head index
+ * (skipping cancelled nodes), and a timed-out acquirer is cancelled in O(1) — no Array.shift/splice
+ * on the hot path.
+ */
+export declare abstract class AbstractPoolHelper<T> extends BaseHelper implements IPool<T> {
+    protected readonly size: number;
+    protected readonly acquireTimeoutMs?: number;
+    protected readonly maxWaitingClients?: number;
+    private readonly idle;
+    private readonly borrowed;
+    private readonly waiterQueue;
+    private total;
+    private isDispatching;
+    private isDestroyed;
+    constructor(opts: IPoolControlOptions);
+    /** Create one resource. Required. */
+    protected abstract create(): ValueOrPromise<T>;
+    /** Validate an idle resource just before hand-out; false → destroyed + replaced. Default: always valid. */
+    protected validateResource(_opts: {
+        resource: T;
+    }): ValueOrPromise<boolean>;
+    /** Reset an idle resource before hand-out (e.g. clear state). Throw → resource discarded. Default: no-op. */
+    protected resetResource(_opts: {
+        resource: T;
+    }): ValueOrPromise<void>;
+    /** Tear down a resource being removed from the pool. Default: no-op. */
+    protected onDestroyResource(_opts: {
+        resource: T;
+    }): ValueOrPromise<void>;
+    getStats(): IPoolStats;
+    acquire(): Promise<T>;
+    release(opts: {
+        resource: T;
+    }): void;
+    warmup(): Promise<void>;
+    use<R>(opts: {
+        fn: (resource: T) => ValueOrPromise<R>;
+    }): Promise<R>;
+    discard(opts: {
+        resource: T;
+    }): Promise<void>;
+    destroy(): Promise<void>;
+    private createResource;
+    private destroyResource;
+    /** Fire-and-forget dispatch with logged rejection; shared by all dispatch call sites. */
+    private safeDispatch;
+    /**
+     * Pair servable resources with waiting acquirers, one at a time, until the queue drains or the
+     * pool is exhausted. Re-entrancy-guarded so only one loop runs at a time (others no-op and let this
+     * loop finish). Each branch delegates to a single-purpose helper.
+     */
+    private dispatch;
+    /** Pop an idle resource and validate+reset it; on ANY failure destroy it and return null (caller retries). */
+    private takeIdleResource;
+    /** Create a fresh resource and hand it to the next waiter; on create failure, reject that waiter. */
+    private createAndHand;
+    /**
+     * Give a ready resource to the next live waiter. Returns false when no live waiter remains
+     * (raced — e.g. it timed out during an await): the resource is returned to idle instead.
+     */
+    private handToWaiter;
+    /** Dequeue the next live waiter and disarm its acquire-timeout so it cannot fire after settlement. */
+    private takeNextWaiter;
+    private clearWaiterTimer;
+}
+/**
+ * Concrete object pool configured by callbacks ({@link IPoolOptions}). Implements the
+ * AbstractPoolHelper lifecycle hooks by delegating to `create`/`validate`/`reset`/`destroy`.
+ *
+ * Each borrow is exclusive until released; `use()` is leak-safe (destroys the resource on error).
+ */
+export declare class BasePoolHelper<T> extends AbstractPoolHelper<T> {
+    private readonly factory;
+    constructor(options: IPoolOptions<T>);
+    protected create(): ValueOrPromise<T>;
+    protected validateResource(opts: {
+        resource: T;
+    }): ValueOrPromise<boolean>;
+    protected resetResource(opts: {
+        resource: T;
+    }): ValueOrPromise<void>;
+    protected onDestroyResource(opts: {
+        resource: T;
+    }): ValueOrPromise<void>;
+}
+//# sourceMappingURL=helper.d.ts.map

package/dist/modules/pool/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../src/modules/pool/helper.ts"],"names":[],"mappings":"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"}

package/dist/modules/pool/helper.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasePoolHelper = exports.AbstractPoolHelper = void 0;
+const base_1 = require("../../modules/base");
+const error_1 = require("../../modules/error");
+const hf_1 = require("../../modules/queue/internal/hf");
+/**
+ * Generic single-borrower object pool — skeleton.
+ *
+ * Holds all pool state and the pairing logic; subclasses supply the resource lifecycle by overriding
+ * {@link create} (required) and, optionally, {@link validateResource} / {@link resetResource} /
+ * {@link onDestroyResource}. {@link BasePoolHelper} is the concrete, callback-configured subclass.
+ *
+ * Every pairing of a resource with a waiting acquirer flows through ONE re-entrancy-guarded
+ * `dispatch()` loop, so `acquire`/`release`/`use`/`discard`/`warmup` stay thin; each loop branch
+ * delegates to a single-purpose helper (`takeIdleResource`, `createAndHand`, `handToWaiter`).
+ *
+ * The waiter queue is a generic O(1) {@link HfQueueHelper}: enqueue pushes, dequeue advances a head index
+ * (skipping cancelled nodes), and a timed-out acquirer is cancelled in O(1) — no Array.shift/splice
+ * on the hot path.
+ */
+class AbstractPoolHelper extends base_1.BaseHelper {
+    constructor(opts) {
+        super({ scope: opts.scope ?? 'BasePoolHelper' });
+        this.idle = [];
+        this.borrowed = new Set();
+        this.waiterQueue = new hf_1.HfQueueHelper();
+        this.total = 0; // live or being-created resources
+        this.isDispatching = false;
+        this.isDestroyed = false;
+        this.size = opts.size;
+        this.acquireTimeoutMs = opts.acquireTimeoutMs;
+        this.maxWaitingClients = opts.maxWaitingClients;
+    }
+    /** Validate an idle resource just before hand-out; false → destroyed + replaced. Default: always valid. */
+    validateResource(_opts) {
+        return true;
+    }
+    /** Reset an idle resource before hand-out (e.g. clear state). Throw → resource discarded. Default: no-op. */
+    resetResource(_opts) {
+        return undefined;
+    }
+    /** Tear down a resource being removed from the pool. Default: no-op. */
+    onDestroyResource(_opts) {
+        return undefined;
+    }
+    // ----------------------------------------------------------------------------------------------------------
+    getStats() {
+        return {
+            size: this.size,
+            available: this.idle.length,
+            borrowed: this.borrowed.size,
+            pending: this.waiterQueue.size,
+        };
+    }
+    async acquire() {
+        if (this.isDestroyed) {
+            throw (0, error_1.getError)({ message: '[acquire] Pool has been destroyed.' });
+        }
+        if (this.maxWaitingClients !== undefined && this.maxWaitingClients > 0) {
+            // Only reject when this acquire would actually have to WAIT: no idle resource and the pool is at
+            // capacity. With a free/creatable resource the caller is served, so maxWaitingClients:0 means
+            // "serve if available, never queue" rather than "reject everything".
+            const isWaitRequired = !this.idle.length && this.total >= this.size;
+            if (isWaitRequired && this.waiterQueue.size >= this.maxWaitingClients) {
+                throw (0, error_1.getError)({
+                    message: `[acquire] Too many waiting clients (>= ${this.maxWaitingClients}).`,
+                });
+            }
+        }
+        const promise = new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, timer: null };
+            const node = this.waiterQueue.enqueue({ value: waiter });
+            if (this.acquireTimeoutMs !== undefined && this.acquireTimeoutMs > 0) {
+                waiter.timer = setTimeout(() => {
+                    this.waiterQueue.cancel({ node }); // O(1) — dispatch skips it when reached
+                    reject((0, error_1.getError)({
+                        message: `[acquire] Acquire timed out after ${this.acquireTimeoutMs}ms.`,
+                    }));
+                }, this.acquireTimeoutMs);
+            }
+        });
+        this.safeDispatch({ action: 'acquire' });
+        return promise;
+    }
+    release(opts) {
+        const { resource } = opts;
+        const logger = this.logger.for(this.release.name);
+        if (!this.borrowed.has(resource)) {
+            logger.warn('Called with a foreign/already-released resource; ignoring.');
+            return;
+        }
+        this.borrowed.delete(resource);
+        if (this.isDestroyed) {
+            this.destroyResource({ resource }).catch(error => {
+                logger.warn('destroyResource error on release: %s', error);
+            });
+            return;
+        }
+        this.idle.push(resource);
+        this.safeDispatch({ action: 'release' });
+    }
+    async warmup() {
+        if (this.isDestroyed) {
+            throw (0, error_1.getError)({ message: '[warmup] Pool has been destroyed.' });
+        }
+        // Create sequentially, re-checking the live `total` before each create so the `size` cap holds
+        // under concurrent warmup()/acquire(). createResource() bumps `total` synchronously (before its
+        // await), so a re-check here observes in-flight creations from other callers → no overshoot.
+        while (this.total < this.size) {
+            const resource = await this.createResource();
+            this.idle.push(resource);
+        }
+        this.safeDispatch({ action: 'warmup' });
+    }
+    async use(opts) {
+        const resource = await this.acquire();
+        try {
+            const result = await opts.fn(resource);
+            this.release({ resource });
+            return result;
+        }
+        catch (error) {
+            this.logger
+                .for(this.use.name)
+                .error('fn threw → release skipped, force DISCARD | Error: %s', error);
+            await this.discard({ resource });
+            throw error;
+        }
+    }
+    async discard(opts) {
+        const { resource } = opts;
+        if (!this.borrowed.delete(resource)) {
+            this.logger.for(this.discard.name).warn('Called with a non-borrowed resource; ignoring.');
+            return;
+        }
+        await this.destroyResource({ resource });
+        this.safeDispatch({ action: 'discard' });
+    }
+    async destroy() {
+        this.isDestroyed = true;
+        const error = (0, error_1.getError)({ message: '[destroy] Pool destroyed while awaiting a resource.' });
+        const draineds = this.waiterQueue.drain();
+        for (const waiter of draineds) {
+            this.clearWaiterTimer({ waiter });
+            waiter.reject(error);
+        }
+        const toDestroy = this.idle.splice(0);
+        await Promise.all(toDestroy.map(resource => this.destroyResource({ resource })));
+    }
+    // ----------------------------------------------------------------------------------------------------------
+    async createResource() {
+        this.total += 1; // bump BEFORE await so concurrent dispatch/warmup see the in-flight create (no overshoot)
+        try {
+            const resource = await this.create();
+            return resource;
+        }
+        catch (error) {
+            this.total -= 1;
+            this.logger
+                .for(this.createResource.name)
+                .error('Error creating pool resource | Error: %s', error);
+            throw error;
+        }
+    }
+    async destroyResource(opts) {
+        this.total -= 1;
+        try {
+            await this.onDestroyResource(opts);
+        }
+        catch (error) {
+            this.logger.for(this.destroyResource.name).warn('destroy hook threw: %s', error);
+        }
+    }
+    // ----------------------------------------------------------------------------------------------------------
+    /** Fire-and-forget dispatch with logged rejection; shared by all dispatch call sites. */
+    safeDispatch(opts) {
+        this.dispatch().catch(error => {
+            this.logger
+                .for(this.dispatch.name)
+                .warn('dispatch error | action: %s | Error: %s', opts.action, error);
+        });
+    }
+    /**
+     * Pair servable resources with waiting acquirers, one at a time, until the queue drains or the
+     * pool is exhausted. Re-entrancy-guarded so only one loop runs at a time (others no-op and let this
+     * loop finish). Each branch delegates to a single-purpose helper.
+     */
+    async dispatch() {
+        if (this.isDispatching) {
+            return;
+        }
+        this.isDispatching = true;
+        try {
+            while (this.waiterQueue.size > 0) {
+                // Prefer a warm idle resource (LIFO) over creating a new one.
+                if (this.idle.length > 0) {
+                    const resource = await this.takeIdleResource();
+                    if (resource === null) {
+                        continue; // bad idle resource was discarded → try the next one
+                    }
+                    if (!this.handToWaiter({ resource })) {
+                        return;
+                    }
+                    continue;
+                }
+                // No idle, but room to grow → create one for the next waiter.
+                if (this.total < this.size) {
+                    await this.createAndHand();
+                    continue;
+                }
+                return;
+            }
+        }
+        catch (error) {
+            this.logger
+                .for(this.dispatch.name)
+                .error('[dispatch] Error while dispatching pool element | Error: %s', error);
+        }
+        finally {
+            this.isDispatching = false;
+        }
+    }
+    /** Pop an idle resource and validate+reset it; on ANY failure destroy it and return null (caller retries). */
+    async takeIdleResource() {
+        const resource = this.idle.pop();
+        const logger = this.logger.for(this.takeIdleResource.name);
+        let isValid;
+        try {
+            isValid = await this.validateResource({ resource });
+        }
+        catch (error) {
+            // A throwing validate must NOT leak the popped candidate (would corrupt `total` and can
+            // permanently starve the pool); treat it like an invalid resource: discard + retry.
+            logger.warn('validate hook threw; discarding resource: %s', error);
+            await this.destroyResource({ resource });
+            return null;
+        }
+        if (!isValid) {
+            await this.destroyResource({ resource });
+            return null;
+        }
+        try {
+            await this.resetResource({ resource });
+        }
+        catch (error) {
+            logger.warn('reset hook threw; discarding resource: %s', error);
+            await this.destroyResource({ resource });
+            return null;
+        }
+        return resource;
+    }
+    /** Create a fresh resource and hand it to the next waiter; on create failure, reject that waiter. */
+    async createAndHand() {
+        let resource;
+        try {
+            resource = await this.createResource();
+        }
+        catch (error) {
+            this.takeNextWaiter()?.reject(error);
+            return;
+        }
+        this.handToWaiter({ resource });
+    }
+    /**
+     * Give a ready resource to the next live waiter. Returns false when no live waiter remains
+     * (raced — e.g. it timed out during an await): the resource is returned to idle instead.
+     */
+    handToWaiter(opts) {
+        const waiter = this.takeNextWaiter();
+        if (!waiter) {
+            this.idle.push(opts.resource);
+            return false;
+        }
+        this.borrowed.add(opts.resource);
+        waiter.resolve(opts.resource);
+        return true;
+    }
+    /** Dequeue the next live waiter and disarm its acquire-timeout so it cannot fire after settlement. */
+    takeNextWaiter() {
+        const waiter = this.waiterQueue.dequeue();
+        if (waiter) {
+            this.clearWaiterTimer({ waiter });
+        }
+        return waiter;
+    }
+    clearWaiterTimer(opts) {
+        const { waiter } = opts;
+        if (waiter.timer) {
+            clearTimeout(waiter.timer);
+            waiter.timer = null;
+        }
+    }
+}
+exports.AbstractPoolHelper = AbstractPoolHelper;
+/**
+ * Concrete object pool configured by callbacks ({@link IPoolOptions}). Implements the
+ * AbstractPoolHelper lifecycle hooks by delegating to `create`/`validate`/`reset`/`destroy`.
+ *
+ * Each borrow is exclusive until released; `use()` is leak-safe (destroys the resource on error).
+ */
+class BasePoolHelper extends AbstractPoolHelper {
+    constructor(options) {
+        super({
+            size: options.size,
+            acquireTimeoutMs: options.acquireTimeoutMs,
+            maxWaitingClients: options.maxWaitingClients,
+            scope: options.scope ?? BasePoolHelper.name,
+        });
+        this.factory = options;
+    }
+    create() {
+        return this.factory.create();
+    }
+    validateResource(opts) {
+        return this.factory.validate ? this.factory.validate(opts.resource) : true;
+    }
+    resetResource(opts) {
+        return this.factory.reset?.(opts.resource);
+    }
+    onDestroyResource(opts) {
+        return this.factory.destroy?.(opts.resource);
+    }
+}
+exports.BasePoolHelper = BasePoolHelper;
+//# sourceMappingURL=helper.js.map

package/dist/modules/pool/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../../src/modules/pool/helper.ts"],"names":[],"mappings":"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"}

package/dist/modules/pool/index.d.ts

@@ -0,0 +1,3 @@
+export * from './helper';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/pool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/pool/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/modules/pool/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./helper"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/modules/pool/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/pool/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,0CAAwB"}

package/dist/modules/pool/types.d.ts

@@ -0,0 +1,62 @@
+import { TNullable, ValueOrPromise } from '../../common/types';
+export interface IPoolStats {
+    size: number;
+    available: number;
+    borrowed: number;
+    pending: number;
+}
+/** Public contract of an object pool (implemented by AbstractPoolHelper). */
+export interface IPool<T> {
+    /** Borrow a resource (creating/waiting as needed). Single-borrower until released/discarded. */
+    acquire(): Promise<T>;
+    /** Return a borrowed resource to the pool (or destroy it if the pool is being torn down). */
+    release(opts: {
+        resource: T;
+    }): void;
+    /** acquire → run fn → release on success; on ANY error DISCARD (destroy) the resource + rethrow. */
+    use<R>(opts: {
+        fn: (resource: T) => ValueOrPromise<R>;
+    }): Promise<R>;
+    /** Remove a borrowed resource from the pool and destroy it. */
+    discard(opts: {
+        resource: T;
+    }): Promise<void>;
+    /** Pre-create resources up to `size` and place them idle. */
+    warmup(): Promise<void>;
+    /** Drain the pool: reject waiters, destroy idle resources, block new acquires. */
+    destroy(): Promise<void>;
+    getStats(): IPoolStats;
+}
+/** Sizing/timeout knobs shared by every pool (no resource-lifecycle callbacks). */
+export interface IPoolControlOptions {
+    /** Max number of resources the pool will hold/create. */
+    size: number;
+    /** Max ms to wait for a free resource; omitted → wait forever. */
+    acquireTimeoutMs?: number;
+    /** Max queued acquirers; omitted → unlimited. Exceeded → acquire() rejects (load-shed). */
+    maxWaitingClients?: number;
+    /** Logger scope; default 'BasePoolHelper'. */
+    scope?: string;
+}
+/**
+ * Options for the callback-configured {@link BasePoolHelper}: control knobs plus the resource
+ * lifecycle as callbacks. (Subclasses of AbstractPoolHelper may instead override the protected
+ * `create`/`validateResource`/`resetResource`/`onDestroyResource` hooks directly.)
+ */
+export interface IPoolOptions<T> extends IPoolControlOptions {
+    /** Factory to create one resource. */
+    create: () => ValueOrPromise<T>;
+    /** Teardown on destroy()/discard()/validate-fail/reset-fail. */
+    destroy?: (resource: T) => ValueOrPromise<void>;
+    /** Checked when an idle resource is about to be handed out; false → destroyed + replaced. */
+    validate?: (resource: T) => ValueOrPromise<boolean>;
+    /** Run on an idle resource just before hand-out (e.g. clear state). Throw → resource discarded. */
+    reset?: (resource: T) => ValueOrPromise<void>;
+}
+/** One queued acquirer. Cancellation/skip is owned by the FifoQueue; this only carries the settlers. */
+export interface IPoolWaiter<T> {
+    resolve: (resource: T) => void;
+    reject: (error: unknown) => void;
+    timer: TNullable<NodeJS.Timeout>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/pool/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/pool/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,gGAAgG;IAChG,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,6FAA6F;IAC7F,OAAO,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACrC,oGAAoG;IACpG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE;QAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,+DAA+D;IAC/D,OAAO,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,kFAAkF;IAClF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,IAAI,UAAU,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,CAAE,SAAQ,mBAAmB;IAC1D,sCAAsC;IACtC,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,CAAC;IAChC,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;IAChD,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,cAAc,CAAC,OAAO,CAAC,CAAC;IACpD,mGAAmG;IACnG,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,wGAAwG;AACxG,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;CAClC"}

package/dist/modules/pool/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/modules/pool/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/pool/types.ts"],"names":[],"mappings":""}

package/dist/modules/queue/internal/hf/helper.d.ts

@@ -0,0 +1,37 @@
+import { TNullable } from '../../../../common/types';
+import { BaseHelper } from '../../../../modules/base';
+import { IHfQueueNode } from './types';
+/**
+ * High-frequency, single-consumer FIFO queue with O(1) enqueue / dequeue / cancel.
+ *
+ * Backed by an array plus a moving head index (no `Array.shift()`, which is O(n)); cancellation flags
+ * the node so {@link dequeue} skips it instead of splicing. The consumed prefix is compacted only
+ * occasionally to reclaim memory, keeping every operation amortized O(1).
+ *
+ * Not thread-safe — intended for single-threaded (event-loop) use, e.g. a pool's waiter queue.
+ */
+export declare class HfQueueHelper<T> extends BaseHelper {
+    private readonly nodes;
+    private head;
+    private liveCount;
+    private static readonly COMPACT_THRESHOLD;
+    constructor(opts?: {
+        scope?: string;
+    });
+    /** Number of live entries (enqueued, not yet dequeued or cancelled). */
+    get size(): number;
+    /** Append a value and return a node handle usable to cancel it later. O(1). */
+    enqueue(opts: {
+        value: T;
+    }): IHfQueueNode<T>;
+    /** Remove + return the next live value in FIFO order, skipping cancelled nodes. Null when empty. */
+    dequeue(): TNullable<T>;
+    /** Mark a still-queued node cancelled so {@link dequeue} and {@link size} skip it. Idempotent. O(1). */
+    cancel(opts: {
+        node: IHfQueueNode<T>;
+    }): void;
+    /** Remove and return every remaining LIVE value in FIFO order (e.g. on shutdown), emptying the queue. */
+    drain(): T[];
+    private reset;
+}
+//# sourceMappingURL=helper.d.ts.map

package/dist/modules/queue/internal/hf/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../../src/modules/queue/internal/hf/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;GAQG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,SAAQ,UAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAE/C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,SAAS,CAAK;IAGtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAO;gBAEpC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAIrC,wEAAwE;IACxE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,+EAA+E;IAC/E,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,CAAC,CAAA;KAAE,GAAG,YAAY,CAAC,CAAC,CAAC;IAQ5C,oGAAoG;IACpG,OAAO,IAAI,SAAS,CAAC,CAAC,CAAC;IAyBvB,wGAAwG;IACxG,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;KAAE,GAAG,IAAI;IAS7C,yGAAyG;IACzG,KAAK,IAAI,CAAC,EAAE;IAaZ,OAAO,CAAC,KAAK;CAKd"}