@naturalcycles/js-lib 15.57.0 → 15.58.0

package/dist/error/index.d.ts

@@ -1,5 +1,5 @@
 export * from './assert.js';
-export * from './error.model.js';
+export type * from './error.model.js';
 export * from './error.util.js';
 export * from './errorMode.js';
 export * from './try.js';

package/dist/error/index.js

@@ -1,5 +1,4 @@
 export * from './assert.js';
-export * from './error.model.js';
 export * from './error.util.js';
 export * from './errorMode.js';
 export * from './try.js';

package/dist/promise/index.d.ts

@@ -2,6 +2,7 @@ export * from './abortable.js';
 export * from './pDefer.js';
 export * from './pDelay.js';
 export * from './pFilter.js';
+export * from './pGradualQueue.js';
 export * from './pHang.js';
 export * from './pMap.js';
 export * from './pProps.js';

package/dist/promise/index.js

@@ -2,6 +2,7 @@ export * from './abortable.js';
 export * from './pDefer.js';
 export * from './pDelay.js';
 export * from './pFilter.js';
+export * from './pGradualQueue.js';
 export * from './pHang.js';
 export * from './pMap.js';
 export * from './pProps.js';

package/dist/promise/pGradualQueue.d.ts

@@ -0,0 +1,61 @@
+import { ErrorMode } from '../error/errorMode.js';
+import { type CommonLogger, type CommonLogLevel } from '../log/commonLogger.js';
+import type { AsyncFunction, PositiveInteger } from '../types.js';
+export interface PGradualQueueCfg {
+    concurrency: PositiveInteger;
+    /**
+     * Time in seconds to gradually increase concurrency from 1 to cfg.concurrency.
+     * After this period, the queue operates at full concurrency.
+     *
+     * Set to 0 to disable warmup (behaves like regular PQueue).
+     */
+    warmupSeconds: number;
+    /**
+     * Default: THROW_IMMEDIATELY
+     *
+     * THROW_AGGREGATED is not supported.
+     *
+     * SUPPRESS_ERRORS will still log errors via logger. It will resolve the `.push` promise with void.
+     */
+    errorMode?: ErrorMode;
+    /**
+     * Default to `console`
+     */
+    logger?: CommonLogger;
+    /**
+     * Default is 'log'.
+     */
+    logLevel?: CommonLogLevel;
+}
+/**
+ * A queue similar to PQueue that gradually increases concurrency from 1 to the configured
+ * maximum over a warmup period. Useful for scenarios where you want to avoid overwhelming
+ * a system at startup (e.g., database connections, API rate limits).
+ *
+ * API is @experimental
+ */
+export declare class PGradualQueue {
+    constructor(cfg: PGradualQueueCfg);
+    private readonly cfg;
+    private readonly logger;
+    private readonly warmupMs;
+    private startTime;
+    private warmupComplete;
+    inFlight: number;
+    private queue;
+    /**
+     * Get current allowed concurrency based on warmup progress.
+     * Returns cfg.concurrency if warmup is complete (fast-path).
+     */
+    private getCurrentConcurrency;
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    push<R>(fn_: AsyncFunction<R>): Promise<R>;
+    get queueSize(): number;
+    /**
+     * Current concurrency limit based on warmup progress.
+     */
+    get currentConcurrency(): number;
+}

package/dist/promise/pGradualQueue.js

@@ -0,0 +1,115 @@
+import { ErrorMode } from '../error/errorMode.js';
+import { createCommonLoggerAtLevel, } from '../log/commonLogger.js';
+import { pDefer } from './pDefer.js';
+/**
+ * A queue similar to PQueue that gradually increases concurrency from 1 to the configured
+ * maximum over a warmup period. Useful for scenarios where you want to avoid overwhelming
+ * a system at startup (e.g., database connections, API rate limits).
+ *
+ * API is @experimental
+ */
+export class PGradualQueue {
+    constructor(cfg) {
+        this.cfg = {
+            errorMode: ErrorMode.THROW_IMMEDIATELY,
+            ...cfg,
+        };
+        this.logger = createCommonLoggerAtLevel(cfg.logger, cfg.logLevel);
+        this.warmupMs = cfg.warmupSeconds * 1000;
+        // Fast-path: if warmupSeconds is 0 or concurrency is 1, skip warmup entirely
+        this.warmupComplete = cfg.warmupSeconds <= 0 || cfg.concurrency <= 1;
+    }
+    cfg;
+    logger;
+    warmupMs;
+    startTime = 0;
+    warmupComplete;
+    inFlight = 0;
+    queue = [];
+    /**
+     * Get current allowed concurrency based on warmup progress.
+     * Returns cfg.concurrency if warmup is complete (fast-path).
+     */
+    getCurrentConcurrency() {
+        // Fast-path: warmup complete
+        if (this.warmupComplete)
+            return this.cfg.concurrency;
+        const elapsed = Date.now() - this.startTime;
+        if (elapsed >= this.warmupMs) {
+            this.warmupComplete = true;
+            this.logger.debug('warmup complete');
+            return this.cfg.concurrency;
+        }
+        // Linear interpolation from 1 to concurrency
+        const progress = elapsed / this.warmupMs;
+        return Math.max(1, Math.floor(1 + (this.cfg.concurrency - 1) * progress));
+    }
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    async push(fn_) {
+        // Initialize start time on first push
+        if (this.startTime === 0) {
+            this.startTime = Date.now();
+        }
+        const { logger } = this;
+        const fn = fn_;
+        fn.defer ||= pDefer();
+        const concurrency = this.getCurrentConcurrency();
+        if (this.inFlight < concurrency) {
+            this.inFlight++;
+            logger.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
+            runSafe(fn)
+                .then(result => {
+                fn.defer.resolve(result);
+            })
+                .catch((err) => {
+                if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+                    logger.error(err);
+                    fn.defer.resolve(); // resolve with `void`
+                }
+                else {
+                    fn.defer.reject(err);
+                }
+            })
+                .finally(() => {
+                this.inFlight--;
+                const currentConcurrency = this.getCurrentConcurrency();
+                logger.debug(`inFlight-- ${this.inFlight}/${currentConcurrency}, queue ${this.queue.length}`);
+                // Start queued jobs up to the current concurrency limit
+                // Use while loop since concurrency may have increased during warmup
+                while (this.queue.length && this.inFlight < this.getCurrentConcurrency()) {
+                    const nextFn = this.queue.shift();
+                    void this.push(nextFn);
+                }
+            });
+        }
+        else {
+            this.queue.push(fn);
+            logger.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`);
+        }
+        return await fn.defer;
+    }
+    get queueSize() {
+        return this.queue.length;
+    }
+    /**
+     * Current concurrency limit based on warmup progress.
+     */
+    get currentConcurrency() {
+        return this.getCurrentConcurrency();
+    }
+}
+// Here we intentionally want it not async, as we don't want it to throw
+// oxlint-disable-next-line typescript/promise-function-async
+function runSafe(fn) {
+    try {
+        // Here we are intentionally not awaiting
+        return fn();
+    }
+    catch (err) {
+        // Handle synchronous throws
+        return Promise.reject(err);
+    }
+}

package/dist/promise/pQueue.d.ts

@@ -1,7 +1,8 @@
 import { ErrorMode } from '../error/errorMode.js';
-import type { CommonLogger } from '../log/commonLogger.js';
+import { type CommonLogger, type CommonLogLevel } from '../log/commonLogger.js';
+import type { AsyncFunction, PositiveInteger } from '../types.js';
 export interface PQueueCfg {
-    concurrency: number;
+    concurrency: PositiveInteger;
     /**
      * Default: THROW_IMMEDIATELY
      *
@@ -10,17 +11,14 @@ export interface PQueueCfg {
      * SUPPRESS_ERRORS will still log errors via logger. It will resolve the `.push` promise with void.
      */
     errorMode?: ErrorMode;
-    /**
-     * @default true
-     */
     /**
      * Default to `console`
      */
     logger?: CommonLogger;
     /**
-     * If true - will LOG EVERYTHING:)
+     * Default is 'log'.
      */
-    debug?: boolean;
+    logLevel?: CommonLogLevel;
     /**
      * By default .push method resolves when the Promise is done (finished).
      *
@@ -31,7 +29,6 @@ export interface PQueueCfg {
      */
     resolveOn?: 'finish' | 'start';
 }
-export type PromiseReturningFunction<R> = () => Promise<R>;
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
  *
@@ -43,10 +40,16 @@ export type PromiseReturningFunction<R> = () => Promise<R>;
 export declare class PQueue {
     constructor(cfg: PQueueCfg);
     private readonly cfg;
-    private debug;
+    private readonly resolveOnStart;
+    private readonly logger;
     inFlight: number;
     private queue;
     private onIdleListeners;
+    /**
+     * Push PromiseReturningFunction to the Queue.
+     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+     */
+    push<R>(fn_: AsyncFunction<R>): Promise<R>;
     get queueSize(): number;
     /**
      * Returns a Promise that resolves when the queue is Idle (next time, since the call).
@@ -54,9 +57,4 @@ export declare class PQueue {
      * Idle means 0 queue and 0 inFlight.
      */
     onIdle(): Promise<void>;
-    /**
-     * Push PromiseReturningFunction to the Queue.
-     * Returns a Promise that resolves (or rejects) with the return value from the Promise.
-     */
-    push<R>(fn_: PromiseReturningFunction<R>): Promise<R>;
 }

package/dist/promise/pQueue.js

@@ -1,4 +1,5 @@
 import { ErrorMode } from '../error/errorMode.js';
+import { createCommonLoggerAtLevel, } from '../log/commonLogger.js';
 import { pDefer } from './pDefer.js';
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
@@ -11,74 +12,56 @@ import { pDefer } from './pDefer.js';
 export class PQueue {
     constructor(cfg) {
         this.cfg = {
-            // concurrency: Number.MAX_SAFE_INTEGER,
             errorMode: ErrorMode.THROW_IMMEDIATELY,
-            logger: console,
-            debug: false,
-            resolveOn: 'finish',
             ...cfg,
         };
-        if (!cfg.debug) {
-            this.debug = () => { };
-        }
+        this.logger = createCommonLoggerAtLevel(cfg.logger, cfg.logLevel);
+        this.resolveOnStart = this.cfg.resolveOn === 'start';
     }
     cfg;
-    debug(...args) {
-        this.cfg.logger.log(...args);
-    }
+    resolveOnStart;
+    logger;
     inFlight = 0;
     queue = [];
     onIdleListeners = [];
-    get queueSize() {
-        return this.queue.length;
-    }
-    /**
-     * Returns a Promise that resolves when the queue is Idle (next time, since the call).
-     * Resolves immediately in case the queue is Idle.
-     * Idle means 0 queue and 0 inFlight.
-     */
-    async onIdle() {
-        if (this.queue.length === 0 && this.inFlight === 0)
-            return;
-        const listener = pDefer();
-        this.onIdleListeners.push(listener);
-        return await listener;
-    }
     /**
      * Push PromiseReturningFunction to the Queue.
      * Returns a Promise that resolves (or rejects) with the return value from the Promise.
      */
     async push(fn_) {
         const { concurrency } = this.cfg;
-        const resolveOnStart = this.cfg.resolveOn === 'start';
+        const { resolveOnStart, logger } = this;
         const fn = fn_;
         fn.defer ||= pDefer();
         if (this.inFlight < concurrency) {
             // There is room for more jobs. Can start immediately
             this.inFlight++;
-            this.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
+            logger.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
             if (resolveOnStart)
                 fn.defer.resolve();
-            fn()
+            runSafe(fn)
                 .then(result => {
                 if (!resolveOnStart)
                     fn.defer.resolve(result);
             })
                 .catch((err) => {
-                this.cfg.logger.error(err);
-                if (resolveOnStart)
+                if (resolveOnStart) {
+                    logger.error(err);
                     return;
+                }
                 if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+                    logger.error(err);
                     fn.defer.resolve(); // resolve with `void`
                 }
                 else {
                     // Should be handled on the outside, otherwise it'll cause UnhandledRejection
+                    // Not logging, because it's re-thrown upstream
                     fn.defer.reject(err);
                 }
             })
                 .finally(() => {
                 this.inFlight--;
-                this.debug(`inFlight-- ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
+                logger.debug(`inFlight-- ${this.inFlight}/${concurrency}, queue ${this.queue.length}`);
                 // check if there's room to start next job
                 if (this.queue.length && this.inFlight <= concurrency) {
                     const nextFn = this.queue.shift();
@@ -86,7 +69,7 @@ export class PQueue {
                 }
                 else {
                     if (this.inFlight === 0) {
-                        this.debug('onIdle');
+                        logger.debug('onIdle');
                         this.onIdleListeners.forEach(defer => defer.resolve());
                         this.onIdleListeners.length = 0; // empty the array
                     }
@@ -95,8 +78,35 @@ export class PQueue {
         }
         else {
             this.queue.push(fn);
-            this.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`);
+            logger.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`);
         }
         return await fn.defer;
     }
+    get queueSize() {
+        return this.queue.length;
+    }
+    /**
+     * Returns a Promise that resolves when the queue is Idle (next time, since the call).
+     * Resolves immediately in case the queue is Idle.
+     * Idle means 0 queue and 0 inFlight.
+     */
+    async onIdle() {
+        if (this.queue.length === 0 && this.inFlight === 0)
+            return;
+        const listener = pDefer();
+        this.onIdleListeners.push(listener);
+        return await listener;
+    }
+}
+// Here we intentionally want it not async, as we don't want it to throw
+// oxlint-disable-next-line typescript/promise-function-async
+function runSafe(fn) {
+    try {
+        // Here we are intentionally not awaiting
+        return fn();
+    }
+    catch (err) {
+        // Handle synchronous throws - ensure inFlight is decremented
+        return Promise.reject(err);
+    }
 }

package/dist/types.d.ts

@@ -417,4 +417,4 @@ type ReadonlyObjectDeep<ObjectType extends object> = {
  ```
  */
 export type RequiredProp<T, K extends keyof T> = Required<Pick<T, K>> & T;
-export * from './typeFest.js';
+export type * from './typeFest.js';

package/dist/types.js

@@ -58,4 +58,3 @@ export function _typeCast(_v) { }
  * Type-safe Object.assign that checks that part is indeed a Partial<T>
  */
 export const _objectAssign = Object.assign;
-export * from './typeFest.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.57.0",
+  "version": "15.58.0",
   "dependencies": {
     "tslib": "^2",
     "undici": "^7",
@@ -13,7 +13,7 @@
     "@types/semver": "^7",
     "crypto-js": "^4",
     "dayjs": "^1",
-    "@naturalcycles/dev-lib": "20.15.0"
+    "@naturalcycles/dev-lib": "18.4.2"
   },
   "exports": {
     ".": "./dist/index.js",

package/src/error/index.ts

@@ -1,5 +1,5 @@
 export * from './assert.js'
-export * from './error.model.js'
+export type * from './error.model.js'
 export * from './error.util.js'
 export * from './errorMode.js'
 export * from './try.js'

package/src/promise/index.ts

@@ -2,6 +2,7 @@ export * from './abortable.js'
 export * from './pDefer.js'
 export * from './pDelay.js'
 export * from './pFilter.js'
+export * from './pGradualQueue.js'
 export * from './pHang.js'
 export * from './pMap.js'
 export * from './pProps.js'

package/src/promise/pGradualQueue.ts

@@ -0,0 +1,171 @@
+import { ErrorMode } from '../error/errorMode.js'
+import {
+  type CommonLogger,
+  type CommonLogLevel,
+  createCommonLoggerAtLevel,
+} from '../log/commonLogger.js'
+import type { AsyncFunction, PositiveInteger } from '../types.js'
+import type { DeferredPromise } from './pDefer.js'
+import { pDefer } from './pDefer.js'
+
+export interface PGradualQueueCfg {
+  concurrency: PositiveInteger
+
+  /**
+   * Time in seconds to gradually increase concurrency from 1 to cfg.concurrency.
+   * After this period, the queue operates at full concurrency.
+   *
+   * Set to 0 to disable warmup (behaves like regular PQueue).
+   */
+  warmupSeconds: number
+
+  /**
+   * Default: THROW_IMMEDIATELY
+   *
+   * THROW_AGGREGATED is not supported.
+   *
+   * SUPPRESS_ERRORS will still log errors via logger. It will resolve the `.push` promise with void.
+   */
+  errorMode?: ErrorMode
+
+  /**
+   * Default to `console`
+   */
+  logger?: CommonLogger
+
+  /**
+   * Default is 'log'.
+   */
+  logLevel?: CommonLogLevel
+}
+
+/**
+ * A queue similar to PQueue that gradually increases concurrency from 1 to the configured
+ * maximum over a warmup period. Useful for scenarios where you want to avoid overwhelming
+ * a system at startup (e.g., database connections, API rate limits).
+ *
+ * API is @experimental
+ */
+export class PGradualQueue {
+  constructor(cfg: PGradualQueueCfg) {
+    this.cfg = {
+      errorMode: ErrorMode.THROW_IMMEDIATELY,
+      ...cfg,
+    }
+    this.logger = createCommonLoggerAtLevel(cfg.logger, cfg.logLevel)
+    this.warmupMs = cfg.warmupSeconds * 1000
+    // Fast-path: if warmupSeconds is 0 or concurrency is 1, skip warmup entirely
+    this.warmupComplete = cfg.warmupSeconds <= 0 || cfg.concurrency <= 1
+  }
+
+  private readonly cfg: PGradualQueueCfg
+  private readonly logger: CommonLogger
+  private readonly warmupMs: number
+
+  private startTime = 0
+  private warmupComplete: boolean
+
+  inFlight = 0
+  private queue: AsyncFunction[] = []
+
+  /**
+   * Get current allowed concurrency based on warmup progress.
+   * Returns cfg.concurrency if warmup is complete (fast-path).
+   */
+  private getCurrentConcurrency(): number {
+    // Fast-path: warmup complete
+    if (this.warmupComplete) return this.cfg.concurrency
+
+    const elapsed = Date.now() - this.startTime
+    if (elapsed >= this.warmupMs) {
+      this.warmupComplete = true
+      this.logger.debug('warmup complete')
+      return this.cfg.concurrency
+    }
+
+    // Linear interpolation from 1 to concurrency
+    const progress = elapsed / this.warmupMs
+    return Math.max(1, Math.floor(1 + (this.cfg.concurrency - 1) * progress))
+  }
+
+  /**
+   * Push PromiseReturningFunction to the Queue.
+   * Returns a Promise that resolves (or rejects) with the return value from the Promise.
+   */
+  async push<R>(fn_: AsyncFunction<R>): Promise<R> {
+    // Initialize start time on first push
+    if (this.startTime === 0) {
+      this.startTime = Date.now()
+    }
+
+    const { logger } = this
+    const fn = fn_ as AsyncFunctionWithDefer<R>
+    fn.defer ||= pDefer<R>()
+
+    const concurrency = this.getCurrentConcurrency()
+
+    if (this.inFlight < concurrency) {
+      this.inFlight++
+      logger.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
+
+      runSafe(fn)
+        .then(result => {
+          fn.defer.resolve(result)
+        })
+        .catch((err: Error) => {
+          if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+            logger.error(err)
+            fn.defer.resolve() // resolve with `void`
+          } else {
+            fn.defer.reject(err)
+          }
+        })
+        .finally(() => {
+          this.inFlight--
+          const currentConcurrency = this.getCurrentConcurrency()
+          logger.debug(
+            `inFlight-- ${this.inFlight}/${currentConcurrency}, queue ${this.queue.length}`,
+          )
+
+          // Start queued jobs up to the current concurrency limit
+          // Use while loop since concurrency may have increased during warmup
+          while (this.queue.length && this.inFlight < this.getCurrentConcurrency()) {
+            const nextFn = this.queue.shift()!
+            void this.push(nextFn)
+          }
+        })
+    } else {
+      this.queue.push(fn)
+      logger.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`)
+    }
+
+    return await fn.defer
+  }
+
+  get queueSize(): number {
+    return this.queue.length
+  }
+
+  /**
+   * Current concurrency limit based on warmup progress.
+   */
+  get currentConcurrency(): number {
+    return this.getCurrentConcurrency()
+  }
+}
+
+// Here we intentionally want it not async, as we don't want it to throw
+// oxlint-disable-next-line typescript/promise-function-async
+function runSafe<R>(fn: AsyncFunction<R>): Promise<R> {
+  try {
+    // Here we are intentionally not awaiting
+    return fn()
+  } catch (err) {
+    // Handle synchronous throws
+    return Promise.reject(err as Error)
+  }
+}
+
+interface AsyncFunctionWithDefer<R = unknown> extends AsyncFunction<R> {
+  defer: DeferredPromise<R>
+}

package/src/promise/pQueue.ts

@@ -1,10 +1,15 @@
 import { ErrorMode } from '../error/errorMode.js'
-import type { CommonLogger } from '../log/commonLogger.js'
+import {
+  type CommonLogger,
+  type CommonLogLevel,
+  createCommonLoggerAtLevel,
+} from '../log/commonLogger.js'
+import type { AsyncFunction, PositiveInteger } from '../types.js'
 import type { DeferredPromise } from './pDefer.js'
 import { pDefer } from './pDefer.js'
 
 export interface PQueueCfg {
-  concurrency: number
+  concurrency: PositiveInteger
 
   /**
    * Default: THROW_IMMEDIATELY
@@ -15,25 +20,15 @@ export interface PQueueCfg {
    */
   errorMode?: ErrorMode
 
-  /**
-   * @default true
-   */
-  // autoStart?: boolean
-
   /**
    * Default to `console`
    */
   logger?: CommonLogger
 
   /**
-   * If true - will LOG EVERYTHING:)
+   * Default is 'log'.
    */
-  debug?: boolean
-
-  // logStatusChange?: boolean
-  // logSizeChange?: boolean
-
-  // timeout
+  logLevel?: CommonLogLevel
 
   /**
    * By default .push method resolves when the Promise is done (finished).
@@ -46,12 +41,6 @@ export interface PQueueCfg {
   resolveOn?: 'finish' | 'start'
 }
 
-export type PromiseReturningFunction<R> = () => Promise<R>
-
-interface PromiseReturningFunctionWithDefer<R> extends PromiseReturningFunction<R> {
-  defer: DeferredPromise<R>
-}
-
 /**
  * Inspired by: https://github.com/sindresorhus/p-queue
  *
@@ -63,81 +52,60 @@ interface PromiseReturningFunctionWithDefer<R> extends PromiseReturningFunction<
 export class PQueue {
   constructor(cfg: PQueueCfg) {
     this.cfg = {
-      // concurrency: Number.MAX_SAFE_INTEGER,
       errorMode: ErrorMode.THROW_IMMEDIATELY,
-      logger: console,
-      debug: false,
-      resolveOn: 'finish',
       ...cfg,
     }
-
-    if (!cfg.debug) {
-      this.debug = () => {}
-    }
+    this.logger = createCommonLoggerAtLevel(cfg.logger, cfg.logLevel)
+    this.resolveOnStart = this.cfg.resolveOn === 'start'
   }
 
-  private readonly cfg: Required<PQueueCfg>
-
-  private debug(...args: any[]): void {
-    this.cfg.logger.log(...args)
-  }
+  private readonly cfg: PQueueCfg
+  private readonly resolveOnStart: boolean
+  private readonly logger: CommonLogger
 
   inFlight = 0
-  private queue: PromiseReturningFunction<any>[] = []
+  private queue: AsyncFunction[] = []
   private onIdleListeners: DeferredPromise[] = []
 
-  get queueSize(): number {
-    return this.queue.length
-  }
-
-  /**
-   * Returns a Promise that resolves when the queue is Idle (next time, since the call).
-   * Resolves immediately in case the queue is Idle.
-   * Idle means 0 queue and 0 inFlight.
-   */
-  async onIdle(): Promise<void> {
-    if (this.queue.length === 0 && this.inFlight === 0) return
-
-    const listener = pDefer()
-    this.onIdleListeners.push(listener)
-    return await listener
-  }
-
   /**
    * Push PromiseReturningFunction to the Queue.
    * Returns a Promise that resolves (or rejects) with the return value from the Promise.
    */
-  async push<R>(fn_: PromiseReturningFunction<R>): Promise<R> {
+  async push<R>(fn_: AsyncFunction<R>): Promise<R> {
     const { concurrency } = this.cfg
-    const resolveOnStart = this.cfg.resolveOn === 'start'
+    const { resolveOnStart, logger } = this
 
-    const fn = fn_ as PromiseReturningFunctionWithDefer<R>
+    const fn = fn_ as AsyncFunctionWithDefer<R>
     fn.defer ||= pDefer<R>()
 
     if (this.inFlight < concurrency) {
       // There is room for more jobs. Can start immediately
       this.inFlight++
-      this.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
+      logger.debug(`inFlight++ ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
       if (resolveOnStart) fn.defer.resolve()
 
-      fn()
+      runSafe(fn)
         .then(result => {
           if (!resolveOnStart) fn.defer.resolve(result)
         })
         .catch((err: Error) => {
-          this.cfg.logger.error(err)
-          if (resolveOnStart) return
+          if (resolveOnStart) {
+            logger.error(err)
+            return
+          }
 
           if (this.cfg.errorMode === ErrorMode.SUPPRESS) {
+            logger.error(err)
             fn.defer.resolve() // resolve with `void`
           } else {
             // Should be handled on the outside, otherwise it'll cause UnhandledRejection
+            // Not logging, because it's re-thrown upstream
             fn.defer.reject(err)
           }
         })
         .finally(() => {
           this.inFlight--
-          this.debug(`inFlight-- ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
+          logger.debug(`inFlight-- ${this.inFlight}/${concurrency}, queue ${this.queue.length}`)
 
           // check if there's room to start next job
           if (this.queue.length && this.inFlight <= concurrency) {
@@ -145,7 +113,7 @@ export class PQueue {
             void this.push(nextFn)
           } else {
             if (this.inFlight === 0) {
-              this.debug('onIdle')
+              logger.debug('onIdle')
               this.onIdleListeners.forEach(defer => defer.resolve())
               this.onIdleListeners.length = 0 // empty the array
             }
@@ -153,9 +121,42 @@ export class PQueue {
         })
     } else {
       this.queue.push(fn)
-      this.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`)
+      logger.debug(`inFlight ${this.inFlight}/${concurrency}, queue++ ${this.queue.length}`)
     }
 
     return await fn.defer
   }
+
+  get queueSize(): number {
+    return this.queue.length
+  }
+
+  /**
+   * Returns a Promise that resolves when the queue is Idle (next time, since the call).
+   * Resolves immediately in case the queue is Idle.
+   * Idle means 0 queue and 0 inFlight.
+   */
+  async onIdle(): Promise<void> {
+    if (this.queue.length === 0 && this.inFlight === 0) return
+
+    const listener = pDefer()
+    this.onIdleListeners.push(listener)
+    return await listener
+  }
+}
+
+// Here we intentionally want it not async, as we don't want it to throw
+// oxlint-disable-next-line typescript/promise-function-async
+function runSafe<R>(fn: AsyncFunction<R>): Promise<R> {
+  try {
+    // Here we are intentionally not awaiting
+    return fn()
+  } catch (err) {
+    // Handle synchronous throws - ensure inFlight is decremented
+    return Promise.reject(err as Error)
+  }
+}
+
+interface AsyncFunctionWithDefer<R> extends AsyncFunction<R> {
+  defer: DeferredPromise<R>
 }

package/src/types.ts

@@ -526,4 +526,4 @@ type ReadonlyObjectDeep<ObjectType extends object> = {
  */
 export type RequiredProp<T, K extends keyof T> = Required<Pick<T, K>> & T
 
-export * from './typeFest.js'
+export type * from './typeFest.js'