@crawlee/core 4.0.0-beta.11 → 4.0.0-beta.111

package/crawlers/statistics.d.ts

@@ -1,5 +1,4 @@
-import type { Log } from '@apify/log';
-import { Configuration } from '../configuration.js';
+import type { CrawleeLogger } from '../log.js';
 import { KeyValueStore } from '../storages/key_value_store.js';
 import { ErrorTracker } from './error_tracker.js';
 /**
@@ -12,30 +11,90 @@ export interface PersistenceOptions {
      */
     enable?: boolean;
 }
+/**
+ * The statistics surface a crawler depends on: recording per-request outcomes, tracking errors, and driving the
+ * capture lifecycle for a run. Injected via the crawler's `statistics` option, so a custom implementation (or a
+ * {@link Statistics} subclass tracking extra fields) can be plugged in without subclassing the crawler.
+ *
+ * The owned-only mutators the crawler uses to *own* a default it built - `reset()`/`resetStore()` - are deliberately
+ * absent: an injected instance is borrowed, and the crawler never wipes it. Those live on the concrete
+ * {@link Statistics} only.
+ *
+ * @category Crawlers
+ */
+export interface IStatistics {
+    /** Tracker for errors on the final retry of a request. */
+    readonly errorTracker: ErrorTracker;
+    /** Tracker for errors on retries prior to the final one. */
+    readonly errorTrackerRetry: ErrorTracker;
+    /** The live statistics state the crawler reads for status messages and the final summary. */
+    readonly state: StatisticState;
+    /** Retries histogram - index `i` holds the number of requests that finished after `i` retries. */
+    readonly requestRetryHistogram: number[];
+    /** Marks a request as started, so its duration can be measured on finish/fail. */
+    startJob(id: number | string): void;
+    /** Marks a started request as finished, updating the finished counters and durations. */
+    finishJob(id: number | string, retryCount: number): void;
+    /** Marks a started request as failed, updating the failed counters and durations. */
+    failJob(id: number | string, retryCount: number): void;
+    /** Drops a started request without counting it as finished or failed (e.g. skipped by robots.txt). */
+    discardJob(id: number | string): void;
+    /** Increments the counter for the given HTTP status code. */
+    registerStatusCode(code: number): void;
+    /** Computes the derived aggregates (averages, per-minute rates, totals) from the current state. */
+    calculate(): CalculatedStatistics;
+    /** Begins a capture window: loads any persisted state, subscribes to persistence events, starts periodic logging. */
+    startCapturing(): Promise<void>;
+    /** Ends the capture window: stops logging, unsubscribes, and persists the final state. */
+    stopCapturing(): Promise<void>;
+    /**
+     * Persists the current state to the key-value store. Optional - the crawler calls it on migration, but a backend
+     * with no persistence of its own can omit it.
+     */
+    persistState?(options?: PersistenceOptions): Promise<void>;
+}
+/** The derived aggregates computed by {@link IStatistics.calculate} from the current {@link StatisticState}. */
+export interface CalculatedStatistics {
+    /** Mean duration of a failed request, in milliseconds; `Infinity` when nothing has failed. */
+    requestAvgFailedDurationMillis: number;
+    /** Mean duration of a finished request, in milliseconds; `Infinity` when nothing has finished. */
+    requestAvgFinishedDurationMillis: number;
+    /** Requests finished per minute over the run so far. */
+    requestsFinishedPerMinute: number;
+    /** Requests failed per minute over the run so far. */
+    requestsFailedPerMinute: number;
+    /** Combined duration of all finished and failed requests, in milliseconds. */
+    requestTotalDurationMillis: number;
+    /** Total number of settled requests (finished plus failed). */
+    requestsTotal: number;
+    /** Wall-clock runtime since capturing started, in milliseconds. */
+    crawlerRuntimeMillis: number;
+}
 /**
  * The statistics class provides an interface to collecting and logging run
  * statistics for requests.
  *
  * All statistic information is saved on key value store
- * under the key `SDK_CRAWLER_STATISTICS_*`, persists between
+ * under the key `CRAWLEE_CRAWLER_STATISTICS_*`, persists between
  * migrations and abort/resurrect
  *
  * @category Crawlers
  */
-export declare class Statistics {
+export declare class Statistics implements IStatistics {
+    #private;
     private static id;
     /**
      * An error tracker for final retry errors.
      */
-    errorTracker: ErrorTracker;
+    readonly errorTracker: ErrorTracker;
     /**
      * An error tracker for retry errors prior to the final retry.
      */
-    errorTrackerRetry: ErrorTracker;
+    readonly errorTrackerRetry: ErrorTracker;
     /**
      * Statistic instance id.
      */
-    readonly id: number;
+    readonly id: string;
     /**
      * Current statistic state used for doing calculations on {@link Statistics.calculate} calls
      */
@@ -44,23 +103,13 @@ export declare class Statistics {
      * Contains the current retries histogram. Index 0 means 0 retries, index 2, 2 retries, and so on
      */
     readonly requestRetryHistogram: number[];
-    /**
-     * Contains the associated Configuration instance
-     */
-    private readonly config;
     protected keyValueStore?: KeyValueStore;
-    protected persistStateKey: string;
-    private logIntervalMillis;
-    private logMessage;
-    private listener;
-    private requestsInProgress;
+    protected readonly persistStateKey: string;
     private readonly log;
-    private instanceStart;
-    private logInterval;
-    private events;
-    private persistenceOptions;
+    private get events();
     /**
-     * @internal
+     * Construct a statistics instance to pass to a crawler via its `statistics` option, e.g. to preconfigure
+     * persistence or error snapshots, share it across sequential runs, or subclass it to track extra fields.
      */
     constructor(options?: StatisticsOptions);
     /**
@@ -90,18 +139,16 @@ export declare class Statistics {
      * @ignore
      */
     failJob(id: number | string, retryCount: number): void;
+    /**
+     * Discards a started job without affecting the finished/failed counters, e.g. when a request
+     * turns out to be skipped (robots.txt, enqueue strategy) after `startJob` was already called for it.
+     * @ignore
+     */
+    discardJob(id: number | string): void;
     /**
      * Calculate the current statistics
      */
-    calculate(): {
-        requestAvgFailedDurationMillis: number;
-        requestAvgFinishedDurationMillis: number;
-        requestsFinishedPerMinute: number;
-        requestsFailedPerMinute: number;
-        requestTotalDurationMillis: number;
-        requestsTotal: number;
-        crawlerRuntimeMillis: number;
-    };
+    calculate(): CalculatedStatistics;
     /**
      * Initializes the key value store for persisting the statistics,
      * displaying the current state in predefined intervals
@@ -111,7 +158,7 @@ export declare class Statistics {
      * Stops logging and remove event listeners, then persist
      */
     stopCapturing(): Promise<void>;
-    protected _saveRetryCountForJob(retryCount: number): void;
+    private saveRetryCountForJob;
     /**
      * Persist internal state to the key value store
      * @param options - Override the persistence options provided in the constructor
@@ -120,8 +167,8 @@ export declare class Statistics {
     /**
      * Loads the current statistic from the key value store if any
      */
-    protected _maybeLoadStatistics(): Promise<void>;
-    protected _teardown(): void;
+    protected maybeLoadStatistics(): Promise<void>;
+    private teardown;
     /**
      * Make this class serializable when called with `JSON.stringify(statsInstance)` directly
      * or through `keyValueStore.setValue('KEY', statsInstance)`
@@ -146,17 +193,12 @@ export interface StatisticsOptions {
      * Parent logger instance, the statistics will create a child logger from this.
      * @default crawler.log
      */
-    log?: Log;
+    log?: CrawleeLogger;
     /**
      * Key value store instance to persist the statistics.
      * If not provided, the default one will be used when capturing starts
      */
     keyValueStore?: KeyValueStore;
-    /**
-     * Configuration instance to use
-     * @default Configuration.getGlobalConfig()
-     */
-    config?: Configuration;
     /**
      * Control how and when to persist the statistics.
      */
@@ -166,13 +208,22 @@ export interface StatisticsOptions {
      * @default false
      */
     saveErrorSnapshots?: boolean;
+    /**
+     * A unique identifier for this statistics instance. This ID is used for persistence
+     * to the key value store, ensuring the same statistics can be loaded after script restarts.
+     *
+     * If not provided, an auto-incremented ID will be used for backward compatibility.
+     * This means statistics may not persist correctly across script restarts
+     * if crawler creation order changes.
+     */
+    id?: string;
 }
 /**
  * Format of the persisted stats
  */
 export interface StatisticPersistedState extends Omit<StatisticState, 'statsPersistedAt'> {
     requestRetryHistogram: number[];
-    statsId: number;
+    statsId: string;
     requestAvgFailedDurationMillis: number;
     requestAvgFinishedDurationMillis: number;
     requestTotalDurationMillis: number;
@@ -201,4 +252,3 @@ export interface StatisticState {
     retryErrors: Record<string, unknown>;
     requestsWithStatusCode: Record<string, number>;
 }
-//# sourceMappingURL=statistics.d.ts.map

package/crawlers/statistics.js

@@ -1,20 +1,19 @@
 import ow from 'ow';
-import { Configuration } from '../configuration.js';
-import { log as defaultLog } from '../log.js';
+import { serviceLocator } from '../service_locator.js';
 import { KeyValueStore } from '../storages/key_value_store.js';
 import { ErrorTracker } from './error_tracker.js';
 /**
  * @ignore
  */
 class Job {
-    lastRunAt = null;
-    durationMillis;
+    #lastRunAt = null;
+    #durationMillis;
     run() {
-        this.lastRunAt = Date.now();
+        this.#lastRunAt = Date.now();
     }
     finish() {
-        this.durationMillis = Date.now() - this.lastRunAt;
-        return this.durationMillis;
+        this.#durationMillis = Date.now() - this.#lastRunAt;
+        return this.#durationMillis;
     }
 }
 const errorTrackerConfig = {
@@ -30,12 +29,13 @@ const errorTrackerConfig = {
  * statistics for requests.
  *
  * All statistic information is saved on key value store
- * under the key `SDK_CRAWLER_STATISTICS_*`, persists between
+ * under the key `CRAWLEE_CRAWLER_STATISTICS_*`, persists between
  * migrations and abort/resurrect
  *
  * @category Crawlers
  */
 export class Statistics {
+    // kept as TS-private: statistics tests read the static counter directly
     static id = 0;
     /**
      * An error tracker for final retry errors.
@@ -48,7 +48,7 @@ export class Statistics {
     /**
      * Statistic instance id.
      */
-    id = Statistics.id++; // assign an id while incrementing so it can be saved/restored from KV
+    id;
     /**
      * Current statistic state used for doing calculations on {@link Statistics.calculate} calls
      */
@@ -57,23 +57,26 @@ export class Statistics {
      * Contains the current retries histogram. Index 0 means 0 retries, index 2, 2 retries, and so on
      */
     requestRetryHistogram = [];
-    /**
-     * Contains the associated Configuration instance
-     */
-    config;
     keyValueStore = undefined;
-    persistStateKey = `SDK_CRAWLER_STATISTICS_${this.id}`;
-    logIntervalMillis;
-    logMessage;
-    listener;
-    requestsInProgress = new Map();
+    persistStateKey;
+    #logIntervalMillis;
+    #logMessage;
+    #listener;
+    #requestsInProgress = new Map();
     log;
-    instanceStart;
-    logInterval;
-    events;
-    persistenceOptions;
+    #instanceStart;
+    #logInterval;
+    #events;
+    #persistenceOptions;
+    get events() {
+        if (!this.#events) {
+            this.#events = serviceLocator.getEventManager();
+        }
+        return this.#events;
+    }
     /**
-     * @internal
+     * Construct a statistics instance to pass to a crawler via its `statistics` option, e.g. to preconfigure
+     * persistence or error snapshots, share it across sequential runs, or subclass it to track extra fields.
      */
     constructor(options = {}) {
         ow(options, ow.object.exactShape({
@@ -81,23 +84,23 @@ export class Statistics {
             logMessage: ow.optional.string,
             log: ow.optional.object,
             keyValueStore: ow.optional.object,
-            config: ow.optional.object,
             persistenceOptions: ow.optional.object,
             saveErrorSnapshots: ow.optional.boolean,
+            id: ow.optional.any(ow.number, ow.string),
         }));
-        const { logIntervalSecs = 60, logMessage = 'Statistics', keyValueStore, config = Configuration.getGlobalConfig(), persistenceOptions = {
+        const { logIntervalSecs = 60, logMessage = 'Statistics', keyValueStore, persistenceOptions = {
             enable: true,
-        }, saveErrorSnapshots = false, } = options;
-        this.log = (options.log ?? defaultLog).child({ prefix: 'Statistics' });
+        }, saveErrorSnapshots = false, id, } = options;
+        this.id = id ?? String(Statistics.id++);
+        this.persistStateKey = `CRAWLEE_CRAWLER_STATISTICS_${this.id}`;
+        this.log = (options.log ?? serviceLocator.getLogger()).child({ prefix: 'Statistics' });
         this.errorTracker = new ErrorTracker({ ...errorTrackerConfig, saveErrorSnapshots });
         this.errorTrackerRetry = new ErrorTracker({ ...errorTrackerConfig, saveErrorSnapshots });
-        this.logIntervalMillis = logIntervalSecs * 1000;
-        this.logMessage = logMessage;
+        this.#logIntervalMillis = logIntervalSecs * 1000;
+        this.#logMessage = logMessage;
         this.keyValueStore = keyValueStore;
-        this.listener = this.persistState.bind(this);
-        this.events = config.getEventManager();
-        this.config = config;
-        this.persistenceOptions = persistenceOptions;
+        this.#listener = this.persistState.bind(this);
+        this.#persistenceOptions = persistenceOptions;
         // initialize by "resetting"
         this.reset();
     }
@@ -126,15 +129,15 @@ export class Statistics {
             retryErrors: this.errorTrackerRetry.result,
         };
         this.requestRetryHistogram.length = 0;
-        this.requestsInProgress.clear();
-        this.instanceStart = Date.now();
-        this._teardown();
+        this.#requestsInProgress.clear();
+        this.#instanceStart = Date.now();
+        this.teardown();
     }
     /**
      * @param options - Override the persistence options provided in the constructor
      */
     async resetStore(options) {
-        if (!this.persistenceOptions.enable && !options?.enable) {
+        if (!this.#persistenceOptions.enable && !options?.enable) {
             return;
         }
         if (!this.keyValueStore) {
@@ -157,49 +160,57 @@ export class Statistics {
      * @ignore
      */
     startJob(id) {
-        let job = this.requestsInProgress.get(id);
+        let job = this.#requestsInProgress.get(id);
         if (!job)
             job = new Job();
         job.run();
-        this.requestsInProgress.set(id, job);
+        this.#requestsInProgress.set(id, job);
     }
     /**
      * Mark job as finished and sets the state
      * @ignore
      */
     finishJob(id, retryCount) {
-        const job = this.requestsInProgress.get(id);
+        const job = this.#requestsInProgress.get(id);
         if (!job)
             return;
         const jobDurationMillis = job.finish();
         this.state.requestsFinished++;
         this.state.requestTotalFinishedDurationMillis += jobDurationMillis;
-        this._saveRetryCountForJob(retryCount);
+        this.saveRetryCountForJob(retryCount);
         if (jobDurationMillis < this.state.requestMinDurationMillis)
             this.state.requestMinDurationMillis = jobDurationMillis;
         if (jobDurationMillis > this.state.requestMaxDurationMillis)
             this.state.requestMaxDurationMillis = jobDurationMillis;
-        this.requestsInProgress.delete(id);
+        this.#requestsInProgress.delete(id);
     }
     /**
      * Mark job as failed and sets the state
      * @ignore
      */
     failJob(id, retryCount) {
-        const job = this.requestsInProgress.get(id);
+        const job = this.#requestsInProgress.get(id);
         if (!job)
             return;
         this.state.requestTotalFailedDurationMillis += job.finish();
         this.state.requestsFailed++;
-        this._saveRetryCountForJob(retryCount);
-        this.requestsInProgress.delete(id);
+        this.saveRetryCountForJob(retryCount);
+        this.#requestsInProgress.delete(id);
+    }
+    /**
+     * Discards a started job without affecting the finished/failed counters, e.g. when a request
+     * turns out to be skipped (robots.txt, enqueue strategy) after `startJob` was already called for it.
+     * @ignore
+     */
+    discardJob(id) {
+        this.#requestsInProgress.delete(id);
     }
     /**
      * Calculate the current statistics
      */
     calculate() {
         const { requestsFailed, requestsFinished, requestTotalFailedDurationMillis, requestTotalFinishedDurationMillis, } = this.state;
-        const totalMillis = Date.now() - this.instanceStart;
+        const totalMillis = Date.now() - this.#instanceStart;
         const totalMinutes = totalMillis / 1000 / 60;
         return {
             requestAvgFailedDurationMillis: Math.round(requestTotalFailedDurationMillis / requestsFailed) || Infinity,
@@ -216,30 +227,35 @@ export class Statistics {
      * displaying the current state in predefined intervals
      */
     async startCapturing() {
-        this.keyValueStore ??= await KeyValueStore.open(null, { config: this.config });
+        // A single instance drives one logging interval and one PERSIST_STATE listener, so a second concurrent
+        // capture (e.g. sharing one instance across crawlers running at once) would orphan the first. Fail loudly.
+        if (this.#logInterval) {
+            throw new Error('Statistics.startCapturing() was already called - this instance is already capturing.');
+        }
+        this.keyValueStore ??= await KeyValueStore.open(null, { configuration: serviceLocator.getConfiguration() });
         if (this.state.crawlerStartedAt === null) {
             this.state.crawlerStartedAt = new Date();
         }
-        if (this.persistenceOptions.enable) {
-            await this._maybeLoadStatistics();
-            this.events.on("persistState" /* EventType.PERSIST_STATE */, this.listener);
+        if (this.#persistenceOptions.enable) {
+            await this.maybeLoadStatistics();
+            this.events.on("persistState" /* EventType.PERSIST_STATE */, this.#listener);
         }
-        this.logInterval = setInterval(() => {
-            this.log.info(this.logMessage, {
+        this.#logInterval = setInterval(() => {
+            this.log.info(this.#logMessage, {
                 ...this.calculate(),
                 retryHistogram: this.requestRetryHistogram,
             });
-        }, this.logIntervalMillis);
+        }, this.#logIntervalMillis);
     }
     /**
      * Stops logging and remove event listeners, then persist
      */
     async stopCapturing() {
-        this._teardown();
+        this.teardown();
         this.state.crawlerFinishedAt = new Date();
         await this.persistState();
     }
-    _saveRetryCountForJob(retryCount) {
+    saveRetryCountForJob(retryCount) {
         if (retryCount > 0)
             this.state.requestsRetries++;
         this.requestRetryHistogram[retryCount] ??= 0;
@@ -250,7 +266,7 @@ export class Statistics {
      * @param options - Override the persistence options provided in the constructor
      */
     async persistState(options) {
-        if (!this.persistenceOptions.enable && !options?.enable) {
+        if (!this.#persistenceOptions.enable && !options?.enable) {
             return;
         }
         // this might be called before startCapturing was called without using await, should not crash
@@ -258,20 +274,14 @@ export class Statistics {
             return;
         }
         this.log.debug('Persisting state', { persistStateKey: this.persistStateKey });
-        // use half the interval of `persistState` to avoid race conditions
-        const persistStateIntervalMillis = this.config.get('persistStateIntervalMillis');
-        const timeoutSecs = persistStateIntervalMillis / 2_000;
         await this.keyValueStore
-            .setValue(this.persistStateKey, this.toJSON(), {
-            timeoutSecs,
-            doNotRetryTimeouts: true,
-        })
+            .setValue(this.persistStateKey, this.toJSON())
             .catch((error) => this.log.warning(`Failed to persist the statistics to ${this.persistStateKey}`, { error }));
     }
     /**
      * Loads the current statistic from the key value store if any
      */
-    async _maybeLoadStatistics() {
+    async maybeLoadStatistics() {
         // this might be called before startCapturing was called without using await, should not crash
         if (!this.keyValueStore) {
             return;
@@ -303,15 +313,17 @@ export class Statistics {
         this.state.crawlerStartedAt = savedState.crawlerStartedAt ? new Date(savedState.crawlerStartedAt) : null;
         this.state.statsPersistedAt = savedState.statsPersistedAt ? new Date(savedState.statsPersistedAt) : null;
         this.state.crawlerRuntimeMillis = savedState.crawlerRuntimeMillis;
-        this.instanceStart = Date.now() - (+this.state.statsPersistedAt - savedState.crawlerLastStartTimestamp);
+        this.#instanceStart = Date.now() - (+this.state.statsPersistedAt - savedState.crawlerLastStartTimestamp);
         this.log.debug('Loaded from KeyValueStore');
     }
-    _teardown() {
+    teardown() {
         // this can be called before a call to startCapturing happens (or in a 'finally' block)
-        this.events.off("persistState" /* EventType.PERSIST_STATE */, this.listener);
-        if (this.logInterval) {
-            clearInterval(this.logInterval);
-            this.logInterval = null;
+        // Only unsubscribe if event manager was already resolved — avoid eagerly resolving it
+        // (e.g. during the constructor's reset() call, which would capture the wrong context)
+        this.#events?.off("persistState" /* EventType.PERSIST_STATE */, this.#listener);
+        if (this.#logInterval) {
+            clearInterval(this.#logInterval);
+            this.#logInterval = null;
         }
     }
     /**
@@ -324,7 +336,7 @@ export class Statistics {
         // omit duplicated information
         const result = {
             ...this.state,
-            crawlerLastStartTimestamp: this.instanceStart,
+            crawlerLastStartTimestamp: this.#instanceStart,
             crawlerFinishedAt: this.state.crawlerFinishedAt
                 ? new Date(this.state.crawlerFinishedAt).toISOString()
                 : null,
@@ -343,4 +355,3 @@ export class Statistics {
         return result;
     }
 }
-//# sourceMappingURL=statistics.js.map

package/debug.d.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage } from 'node:http';
+import type { Dictionary } from '@crawlee/types';
+import type { Request } from './request.js';
+interface BrowserResponseLike {
+    status(): number;
+}
+/**
+ * Creates a standardized debug info from request and response. This info is usually added to dataset under the hidden `#debug` field.
+ *
+ * @param request [Request](https://sdk.apify.com/docs/api/request) object.
+ * @param [response]
+ *   Puppeteer [`Response`](https://pptr.dev/#?product=Puppeteer&version=v1.11.0&show=api-class-response)
+ *   or NodeJS [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_serverresponse).
+ * @param [additionalFields] Object containing additional fields to be added.
+ *
+ * @internal
+ */
+export declare function createRequestDebugInfo(request: Request, response?: IncomingMessage | Partial<BrowserResponseLike>, additionalFields?: Dictionary): Dictionary;
+/**
+ * Returns a human-readable label for an unknown value,
+ * suitable for embedding in error messages and log output.
+ *
+ * Returns `constructor.name` when available (e.g. `"Configuration"`, `"Number"`),
+ * otherwise falls back to `util.inspect` (e.g. for `null`, `undefined`).
+ *
+ * @internal
+ */
+export declare function inspectValue(value: unknown): string;
+/**
+ * Returns the type of a value as a lowercase string, with `Date`, `Buffer` and `RegExp` reported
+ * by their constructor name. Used for building validation error messages.
+ *
+ * @internal
+ */
+export declare function getObjectType(value: unknown): string;
+export {};

package/debug.js

@@ -0,0 +1,70 @@
+import { inspect } from 'node:util';
+import ow from 'ow';
+/**
+ * Creates a standardized debug info from request and response. This info is usually added to dataset under the hidden `#debug` field.
+ *
+ * @param request [Request](https://sdk.apify.com/docs/api/request) object.
+ * @param [response]
+ *   Puppeteer [`Response`](https://pptr.dev/#?product=Puppeteer&version=v1.11.0&show=api-class-response)
+ *   or NodeJS [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_serverresponse).
+ * @param [additionalFields] Object containing additional fields to be added.
+ *
+ * @internal
+ */
+export function createRequestDebugInfo(request, response = {}, additionalFields = {}) {
+    ow(request, ow.object);
+    ow(response, ow.object);
+    ow(additionalFields, ow.object);
+    return {
+        requestId: request.id,
+        url: request.url,
+        loadedUrl: request.loadedUrl,
+        method: request.method,
+        retryCount: request.retryCount,
+        errorMessages: request.errorMessages,
+        // Puppeteer response has .status() function and NodeJS response, statusCode property.
+        statusCode: 'status' in response && response.status instanceof Function
+            ? response.status()
+            : response.statusCode,
+        ...additionalFields,
+    };
+}
+/**
+ * Returns a human-readable label for an unknown value,
+ * suitable for embedding in error messages and log output.
+ *
+ * Returns `constructor.name` when available (e.g. `"Configuration"`, `"Number"`),
+ * otherwise falls back to `util.inspect` (e.g. for `null`, `undefined`).
+ *
+ * @internal
+ */
+export function inspectValue(value) {
+    if (typeof value === 'object' && value !== null && value.constructor?.name) {
+        return value.constructor.name;
+    }
+    return inspect(value, {
+        depth: 0,
+        compact: true,
+        maxStringLength: 64,
+        breakLength: Infinity,
+        colors: false,
+    });
+}
+/**
+ * Returns the type of a value as a lowercase string, with `Date`, `Buffer` and `RegExp` reported
+ * by their constructor name. Used for building validation error messages.
+ *
+ * @internal
+ */
+export function getObjectType(value) {
+    const simple = typeof value;
+    if (['string', 'number', 'boolean', 'bigint'].includes(simple)) {
+        return simple;
+    }
+    const objectType = Object.prototype.toString.call(value);
+    const type = /\[object (\w+)]/.exec(objectType)[1];
+    if (type === 'Uint8Array') {
+        return 'Buffer';
+    }
+    return ['Date', 'Buffer', 'RegExp'].includes(type) ? type : type.toLowerCase();
+}