@crawlee/core 4.0.0-beta.87 → 4.0.0-beta.89

package/autoscaling/cpu_load_signal.d.ts

@@ -1,7 +1,9 @@
-import type { Configuration } from '../configuration.js';
-import type { LoadSnapshot } from './load_signal.js';
-import { SnapshotStore } from './load_signal.js';
+import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
 import type { SystemInfo } from './system_status.js';
+/**
+ * A snapshot produced by the built-in CPU signal.
+ * @internal
+ */
 export interface CpuSnapshot extends LoadSnapshot {
     usedRatio: number;
     ticks?: {
@@ -9,20 +11,34 @@ export interface CpuSnapshot extends LoadSnapshot {
         total: number;
     };
 }
+/**
+ * Tuning for the built-in **CPU** load signal, as accepted both by {@link CpuLoadSignal} and by the
+ * {@link LoadSignalsOptions.cpu|`cpu`} shorthand on {@link LoadSignalsOptions}.
+ */
 export interface CpuLoadSignalOptions {
+    /**
+     * Maximum ratio of overloaded snapshots in a sample before the CPU counts as overloaded.
+     * @default 0.4
+     */
     overloadedRatio?: number;
-    snapshotHistoryMillis?: number;
-    configuration: Configuration;
 }
 /**
- * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when
- * the platform or local OS metrics indicate the CPU is overloaded.
+ * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when the platform or local OS metrics indicate the
+ * CPU is overloaded.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * @category Scaling
  */
-// @ts-ignore optional peer dependency or compatibility with es2022
-export declare function createCpuLoadSignal(options: CpuLoadSignalOptions): Omit<import("./load_signal.js").LoadSignal, "getSample"> & {
-    store: SnapshotStore<CpuSnapshot>;
-    handle: (payload: SystemInfo) => void;
-    getSample(sampleDurationMillis?: number): CpuSnapshot[];
-};
-/** @internal Return type for backward compat in Snapshotter facade */
-export type CpuLoadSignal = ReturnType<typeof createCpuLoadSignal>;
+export declare class CpuLoadSignal implements LoadSignal {
+    readonly name = "cpuInfo";
+    readonly overloadedRatio: number;
+    private readonly store;
+    private events?;
+    constructor(options?: CpuLoadSignalOptions);
+    start(context: LoadSignalStartContext): Promise<void>;
+    stop(): Promise<void>;
+    getSample(sampleDurationMillis?: number): LoadSnapshot[];
+    /** @internal Records a snapshot from a `SYSTEM_INFO` payload. Exposed for tests. */
+    handle(systemInfo: SystemInfo): void;
+}

package/autoscaling/cpu_load_signal.js

@@ -1,24 +1,46 @@
 import { serviceLocator } from '../service_locator.js';
 import { SnapshotStore } from './load_signal.js';
 /**
- * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when
- * the platform or local OS metrics indicate the CPU is overloaded.
+ * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when the platform or local OS metrics indicate the
+ * CPU is overloaded.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * @category Scaling
  */
-export function createCpuLoadSignal(options) {
-    return SnapshotStore.fromEvent({
-        name: 'cpuInfo',
-        overloadedRatio: options.overloadedRatio ?? 0.4,
-        events: serviceLocator.getEventManager(),
-        event: "systemInfo" /* EventType.SYSTEM_INFO */,
-        snapshotHistoryMillis: options.snapshotHistoryMillis,
-        handler(store, systemInfo) {
-            const { cpuCurrentUsage, isCpuOverloaded } = systemInfo;
-            const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
-            store.push({
-                createdAt,
-                isOverloaded: isCpuOverloaded,
-                usedRatio: Math.ceil(cpuCurrentUsage / 100),
-            }, createdAt);
-        },
-    });
+export class CpuLoadSignal {
+    name = 'cpuInfo';
+    overloadedRatio;
+    store = new SnapshotStore();
+    events;
+    constructor(options = {}) {
+        this.overloadedRatio = options.overloadedRatio ?? 0.4;
+        this.handle = this.handle.bind(this);
+    }
+    async start(context) {
+        this.store.useSampleWindow(context.maxSampleWindowMillis);
+        // A new session starts from a clean slate, so it is not judged on measurements from before the downtime.
+        this.store.clear();
+        // Resolved here rather than in the constructor, so an instance built ahead of time (to be wrapped, or shared
+        // between systems) cannot capture whichever event manager happened to be registered at that moment.
+        this.events = serviceLocator.getEventManager();
+        this.events.on("systemInfo" /* EventType.SYSTEM_INFO */, this.handle);
+    }
+    async stop() {
+        this.events?.off("systemInfo" /* EventType.SYSTEM_INFO */, this.handle);
+        this.events = undefined;
+    }
+    getSample(sampleDurationMillis) {
+        return this.store.getSample(sampleDurationMillis);
+    }
+    /** @internal Records a snapshot from a `SYSTEM_INFO` payload. Exposed for tests. */
+    handle(systemInfo) {
+        const { cpuCurrentUsage, isCpuOverloaded } = systemInfo;
+        const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
+        this.store.push({
+            createdAt,
+            isOverloaded: isCpuOverloaded,
+            usedRatio: Math.ceil(cpuCurrentUsage / 100),
+        }, createdAt);
+    }
 }

package/autoscaling/event_loop_load_signal.d.ts

@@ -1,23 +1,54 @@
-import type { LoadSnapshot } from './load_signal.js';
-import { SnapshotStore } from './load_signal.js';
+import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
+/**
+ * A snapshot produced by the built-in event loop signal.
+ * @internal
+ */
 export interface EventLoopSnapshot extends LoadSnapshot {
     exceededMillis: number;
 }
+/**
+ * Tuning for the built-in **event loop** load signal, as accepted both by {@link EventLoopLoadSignal} and by the
+ * {@link LoadSignalsOptions.eventLoop|`eventLoop`} shorthand on {@link LoadSignalsOptions}.
+ */
 export interface EventLoopLoadSignalOptions {
-    eventLoopSnapshotIntervalSecs?: number;
+    /**
+     * Defines the interval of measuring the event loop response time, in seconds.
+     * @default 0.5
+     */
+    snapshotIntervalSecs?: number;
+    /**
+     * Maximum allowed delay of the event loop in milliseconds.
+     * Exceeding this limit overloads the event loop.
+     * @default 50
+     */
     maxBlockedMillis?: number;
+    /**
+     * Maximum ratio of overloaded snapshots in a sample before the event loop counts as overloaded.
+     * @default 0.6
+     */
     overloadedRatio?: number;
-    snapshotHistoryMillis?: number;
 }
 /**
- * Periodically measures event loop delay and reports overload when the
- * delay exceeds a configured threshold.
+ * Periodically measures event loop delay and reports overload when the delay exceeds a configured threshold.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * @category Scaling
  */
-// @ts-ignore optional peer dependency or compatibility with es2022
-export declare function createEventLoopLoadSignal(options?: EventLoopLoadSignalOptions): Omit<import("./load_signal.js").LoadSignal, "getSample"> & {
-    store: SnapshotStore<EventLoopSnapshot>;
-    handle: (cb: () => unknown) => void;
-    getSample(sampleDurationMillis?: number): EventLoopSnapshot[];
-};
-/** @internal Return type for backward compat in Snapshotter facade */
-export type EventLoopLoadSignal = ReturnType<typeof createEventLoopLoadSignal>;
+export declare class EventLoopLoadSignal implements LoadSignal {
+    readonly name = "eventLoopInfo";
+    readonly overloadedRatio: number;
+    private readonly store;
+    private readonly intervalMillis;
+    private readonly maxBlockedMillis;
+    private interval?;
+    constructor(options?: EventLoopLoadSignalOptions);
+    start(context: LoadSignalStartContext): Promise<void>;
+    stop(): Promise<void>;
+    getSample(sampleDurationMillis?: number): LoadSnapshot[];
+    /**
+     * Records one snapshot: how much later than scheduled this tick ran is how long the loop was blocked.
+     * @internal Also lets tests drive the measurement without waiting on a timer.
+     */
+    handle(intervalCallback: () => unknown): void;
+}

package/autoscaling/event_loop_load_signal.js

@@ -1,35 +1,60 @@
+import { betterClearInterval, betterSetInterval } from '@apify/utilities';
 import { SnapshotStore } from './load_signal.js';
 /**
- * Periodically measures event loop delay and reports overload when the
- * delay exceeds a configured threshold.
+ * Periodically measures event loop delay and reports overload when the delay exceeds a configured threshold.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * @category Scaling
  */
-export function createEventLoopLoadSignal(options = {}) {
-    const intervalMillis = (options.eventLoopSnapshotIntervalSecs ?? 0.5) * 1000;
-    const maxBlockedMillis = options.maxBlockedMillis ?? 50;
-    const signal = SnapshotStore.fromInterval({
-        name: 'eventLoopInfo',
-        overloadedRatio: options.overloadedRatio ?? 0.6,
-        intervalMillis,
-        snapshotHistoryMillis: options.snapshotHistoryMillis,
-        handler(store, intervalCallback) {
-            const now = new Date();
-            const snapshot = {
-                createdAt: now,
-                isOverloaded: false,
-                exceededMillis: 0,
-            };
-            const all = store.getAll();
-            const previousSnapshot = all[all.length - 1];
-            if (previousSnapshot) {
-                const { createdAt } = previousSnapshot;
-                const delta = now.getTime() - +createdAt - intervalMillis;
-                if (delta > maxBlockedMillis)
-                    snapshot.isOverloaded = true;
-                snapshot.exceededMillis = Math.max(delta - maxBlockedMillis, 0);
-            }
-            store.push(snapshot, now);
-            intervalCallback();
-        },
-    });
-    return signal;
+export class EventLoopLoadSignal {
+    name = 'eventLoopInfo';
+    overloadedRatio;
+    store = new SnapshotStore();
+    intervalMillis;
+    maxBlockedMillis;
+    interval;
+    constructor(options = {}) {
+        this.overloadedRatio = options.overloadedRatio ?? 0.6;
+        this.intervalMillis = (options.snapshotIntervalSecs ?? 0.5) * 1000;
+        this.maxBlockedMillis = options.maxBlockedMillis ?? 50;
+        this.handle = this.handle.bind(this);
+    }
+    async start(context) {
+        this.store.useSampleWindow(context.maxSampleWindowMillis);
+        // A new session starts from a clean slate, or the downtime gets charged to the event loop: `handle()` measures
+        // the gap since the previous snapshot, which across a restart is however long the system was stopped.
+        this.store.clear();
+        this.interval = betterSetInterval(this.handle, this.intervalMillis);
+    }
+    async stop() {
+        if (this.interval)
+            betterClearInterval(this.interval);
+        this.interval = undefined;
+    }
+    getSample(sampleDurationMillis) {
+        return this.store.getSample(sampleDurationMillis);
+    }
+    /**
+     * Records one snapshot: how much later than scheduled this tick ran is how long the loop was blocked.
+     * @internal Also lets tests drive the measurement without waiting on a timer.
+     */
+    handle(intervalCallback) {
+        const now = new Date();
+        const snapshot = {
+            createdAt: now,
+            isOverloaded: false,
+            exceededMillis: 0,
+        };
+        const all = this.store.getAll();
+        const previousSnapshot = all[all.length - 1];
+        if (previousSnapshot) {
+            const delta = now.getTime() - +previousSnapshot.createdAt - this.intervalMillis;
+            if (delta > this.maxBlockedMillis)
+                snapshot.isOverloaded = true;
+            snapshot.exceededMillis = Math.max(delta - this.maxBlockedMillis, 0);
+        }
+        this.store.push(snapshot, now);
+        intervalCallback();
+    }
 }

package/autoscaling/index.d.ts

@@ -1,4 +1,5 @@
 export * from './autoscaled_pool.js';
+export * from './concurrency_system.js';
 export * from './client_load_signal.js';
 export * from './cpu_load_signal.js';
 export * from './event_loop_load_signal.js';

package/autoscaling/index.js

@@ -1,4 +1,5 @@
 export * from './autoscaled_pool.js';
+export * from './concurrency_system.js';
 export * from './client_load_signal.js';
 export * from './cpu_load_signal.js';
 export * from './event_loop_load_signal.js';

package/autoscaling/load_signal.d.ts

@@ -1,4 +1,3 @@
-import type { EventManager, EventTypeName } from '../events/event_manager.js';
 import type { ClientInfo } from './system_status.js';
 /**
  * A snapshot of a resource's overload state at a point in time.
@@ -8,15 +7,34 @@ export interface LoadSnapshot {
     isOverloaded: boolean;
 }
 /**
- * A signal that reports whether a particular resource is overloaded.
+ * Handed to a {@link LoadSignal} when it starts, so it can size its snapshot retention to what it will actually
+ * be asked for — without having to know how the {@link ConcurrencySystem} that drives it is configured.
+ */
+export interface LoadSignalStartContext {
+    /**
+     * The longest sample window the signal will be queried with (the wider of the task-gating and autoscaling
+     * windows). Keeping less history than this contributes a narrower view of the resource than the other signals;
+     * keeping more is wasted memory, as the extra snapshots are never sampled.
+     */
+    maxSampleWindowMillis: number;
+}
+/**
+ * A signal that reports whether a particular resource is overloaded. The {@link ConcurrencySystem} aggregates
+ * several of them — if any one reports overload, the system is overloaded.
  *
- * `SystemStatus` aggregates multiple `LoadSignal` instances to determine
- * overall system health. The built-in signals cover memory, CPU, event loop,
- * and API client rate limits. You can implement this interface to add
- * custom overload signals (e.g. navigation timeouts, proxy health).
+ * The built-in signals cover memory, CPU, event loop and storage-client rate limits. Implement this interface to add
+ * your own (navigation timeouts, proxy health, …) and pass them via
+ * {@link LoadSignalsOptions.custom|`loadSignals.custom`}; {@link SnapshotStore} does the time-windowed
+ * bookkeeping if you want it. Each built-in is also a public class, so one can be *wrapped* rather than reimplemented
+ * — construct it yourself and switch the default off with {@link LoadSignalsOptions.cpu|`cpu: false`} or friends.
  */
 export interface LoadSignal {
-    /** Human-readable name used in logging and `SystemInfo` keys. */
+    /**
+     * This signal's key in the reported {@link SystemInfo}, also used in logging — so it must be unique among the
+     * signals of one {@link ConcurrencySystem}, which throws on a duplicate. The four built-in names (`memInfo`,
+     * `eventLoopInfo`, `cpuInfo`, `clientInfo`) land in the correspondingly named `SystemInfo` fields rather than the
+     * `loadSignalInfo` bag; taking one over means switching that built-in off.
+     */
     readonly name: string;
     /**
      * Maximum ratio of overloaded snapshots in a sample before the signal
@@ -24,9 +42,12 @@ export interface LoadSignal {
      * when more than 20% of the sample window is overloaded.
      */
     readonly overloadedRatio: number;
-    /** Start collecting snapshots. Called when the pool starts. */
-    start(): Promise<void>;
-    /** Stop collecting snapshots. Called when the pool shuts down. */
+    /**
+     * Start collecting snapshots, retaining at least the sample window named in the `context`. Called when the
+     * {@link ConcurrencySystem} starts — which may be a *restart*, so drop anything measured before it.
+     */
+    start(context: LoadSignalStartContext): Promise<void>;
+    /** Stop collecting snapshots. Called when the {@link ConcurrencySystem} shuts down. */
     stop(): Promise<void>;
     /**
      * Return snapshots for a recent time window (used for "current" status).
@@ -35,13 +56,19 @@ export interface LoadSignal {
     getSample(sampleDurationMillis?: number): LoadSnapshot[];
 }
 /**
- * A time-pruning, time-windowed store for `LoadSnapshot` values.
- * Signals compose with this instead of inheriting from a base class.
+ * A time-pruning, time-windowed store for `LoadSnapshot` values. All four built-in signals compose with one of these,
+ * and so can yours — it is the only part of their machinery worth reusing.
  */
 export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
     private snapshots;
-    private readonly historyMillis;
-    constructor(historyMillis?: number);
+    /** Retention window in milliseconds. Unbounded until {@link SnapshotStore.useSampleWindow|`useSampleWindow()`}. */
+    private historyMillis;
+    /**
+     * Sizes retention to the window the signal will be sampled over, as handed to it in
+     * {@link LoadSignal.start|`start()`}. Until this is called nothing is pruned at all, so a signal that ignores
+     * its start context grows unboundedly.
+     */
+    useSampleWindow(maxSampleWindowMillis: number): void;
     /**
      * Add a snapshot and prune entries older than the history window.
      */
@@ -51,49 +78,22 @@ export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
      */
     getSample(sampleDurationMillis?: number): T[];
     /**
-     * Direct access to the underlying array (for backward-compat getters).
+     * Direct, unwindowed access to the underlying array — used by signals whose handler needs the previous snapshot
+     * to compute a delta (e.g. the event loop and client signals read the last entry to measure change since it).
      */
     getAll(): T[];
     /**
-     * Create a `LoadSignal` that snapshots on a `betterSetInterval` tick.
-     *
-     * The `handler` receives the store (to read previous snapshots) and the
-     * interval callback (which it **must** call when done). It should call
-     * `store.push()` to record a snapshot.
-     */
-    static fromInterval<T extends LoadSnapshot>(options: {
-        name: string;
-        overloadedRatio: number;
-        intervalMillis: number;
-        snapshotHistoryMillis?: number;
-        handler: (store: SnapshotStore<T>, intervalCallback: () => unknown) => void;
-    }): Omit<LoadSignal, 'getSample'> & {
-        store: SnapshotStore<T>;
-        handle: (cb: () => unknown) => void;
-        getSample(sampleDurationMillis?: number): T[];
-    };
-    /**
-     * Create a `LoadSignal` that snapshots in response to an `EventManager` event.
-     *
-     * The `handler` receives the event payload and the store. It should call
-     * `store.push()` to record a snapshot.
+     * Discards every retained snapshot. The built-in signals do this when they *start*, so that a session neither
+     * samples nor diffs against measurements from before the preceding downtime — pruning is relative to the newest
+     * snapshot rather than the wall clock, so stale entries would otherwise survive indefinitely. Clearing on start
+     * rather than on stop leaves a finished session readable.
      */
-    static fromEvent<T extends LoadSnapshot, E>(options: {
-        name: string;
-        overloadedRatio: number;
-        events: EventManager;
-        event: EventTypeName;
-        snapshotHistoryMillis?: number;
-        handler: (store: SnapshotStore<T>, payload: E) => void;
-    }): Omit<LoadSignal, 'getSample'> & {
-        store: SnapshotStore<T>;
-        handle: (payload: E) => void;
-        getSample(sampleDurationMillis?: number): T[];
-    };
+    clear(): void;
 }
 /**
  * Evaluate whether a sample of `LoadSnapshot` values exceeds the given
  * overloaded ratio, using a time-weighted average. This is the shared
  * evaluation logic used by `SystemStatus` for all signal types.
+ * @internal
  */
 export declare function evaluateLoadSignalSample(sample: LoadSnapshot[], overloadedRatio: number): ClientInfo;

package/autoscaling/load_signal.js

@@ -1,14 +1,19 @@
 import { weightedAvg } from '@crawlee/utils';
-import { betterClearInterval, betterSetInterval } from '@apify/utilities';
 /**
- * A time-pruning, time-windowed store for `LoadSnapshot` values.
- * Signals compose with this instead of inheriting from a base class.
+ * A time-pruning, time-windowed store for `LoadSnapshot` values. All four built-in signals compose with one of these,
+ * and so can yours — it is the only part of their machinery worth reusing.
  */
 export class SnapshotStore {
     snapshots = [];
-    historyMillis;
-    constructor(historyMillis = 30_000) {
-        this.historyMillis = historyMillis;
+    /** Retention window in milliseconds. Unbounded until {@link SnapshotStore.useSampleWindow|`useSampleWindow()`}. */
+    historyMillis = Infinity;
+    /**
+     * Sizes retention to the window the signal will be sampled over, as handed to it in
+     * {@link LoadSignal.start|`start()`}. Until this is called nothing is pruned at all, so a signal that ignores
+     * its start context grows unboundedly.
+     */
+    useSampleWindow(maxSampleWindowMillis) {
+        this.historyMillis = maxSampleWindowMillis;
     }
     /**
      * Add a snapshot and prune entries older than the history window.
@@ -50,64 +55,27 @@ export class SnapshotStore {
         return sample;
     }
     /**
-     * Direct access to the underlying array (for backward-compat getters).
+     * Direct, unwindowed access to the underlying array — used by signals whose handler needs the previous snapshot
+     * to compute a delta (e.g. the event loop and client signals read the last entry to measure change since it).
      */
     getAll() {
         return this.snapshots;
     }
     /**
-     * Create a `LoadSignal` that snapshots on a `betterSetInterval` tick.
-     *
-     * The `handler` receives the store (to read previous snapshots) and the
-     * interval callback (which it **must** call when done). It should call
-     * `store.push()` to record a snapshot.
+     * Discards every retained snapshot. The built-in signals do this when they *start*, so that a session neither
+     * samples nor diffs against measurements from before the preceding downtime — pruning is relative to the newest
+     * snapshot rather than the wall clock, so stale entries would otherwise survive indefinitely. Clearing on start
+     * rather than on stop leaves a finished session readable.
      */
-    static fromInterval(options) {
-        const store = new SnapshotStore(options.snapshotHistoryMillis);
-        let interval = null;
-        const handle = (cb) => options.handler(store, cb);
-        return {
-            name: options.name,
-            overloadedRatio: options.overloadedRatio,
-            store,
-            handle,
-            getSample: (ms) => store.getSample(ms),
-            async start() {
-                interval = betterSetInterval(handle, options.intervalMillis);
-            },
-            async stop() {
-                betterClearInterval(interval);
-            },
-        };
-    }
-    /**
-     * Create a `LoadSignal` that snapshots in response to an `EventManager` event.
-     *
-     * The `handler` receives the event payload and the store. It should call
-     * `store.push()` to record a snapshot.
-     */
-    static fromEvent(options) {
-        const store = new SnapshotStore(options.snapshotHistoryMillis);
-        const handle = (payload) => options.handler(store, payload);
-        return {
-            name: options.name,
-            overloadedRatio: options.overloadedRatio,
-            store,
-            handle,
-            getSample: (ms) => store.getSample(ms),
-            async start() {
-                options.events.on(options.event, handle);
-            },
-            async stop() {
-                options.events.off(options.event, handle);
-            },
-        };
+    clear() {
+        this.snapshots = [];
     }
 }
 /**
  * Evaluate whether a sample of `LoadSnapshot` values exceeds the given
  * overloaded ratio, using a time-weighted average. This is the shared
  * evaluation logic used by `SystemStatus` for all signal types.
+ * @internal
  */
 export function evaluateLoadSignalSample(sample, overloadedRatio) {
     if (sample.length === 0) {

package/autoscaling/memory_load_signal.d.ts

@@ -1,42 +1,55 @@
-import type { Configuration } from '../configuration.js';
-import type { CrawleeLogger } from '../log.js';
-import type { LoadSignal, LoadSnapshot } from './load_signal.js';
+import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
 import type { SystemInfo } from './system_status.js';
+/**
+ * A snapshot produced by the built-in memory signal.
+ * @internal
+ */
 export interface MemorySnapshot extends LoadSnapshot {
     usedBytes?: number;
 }
+/**
+ * Tuning for the built-in **memory** load signal, as accepted both by {@link MemoryLoadSignal} and by the
+ * {@link LoadSignalsOptions.memory|`memory`} shorthand on {@link LoadSignalsOptions}.
+ */
 export interface MemoryLoadSignalOptions {
-    maxUsedMemoryRatio?: number;
+    /**
+     * Defines the maximum ratio of total memory that can be used.
+     * Exceeding this limit overloads the memory.
+     * @default 0.9
+     */
+    maxUsedRatio?: number;
+    /**
+     * Maximum ratio of overloaded snapshots in a sample before memory counts as overloaded.
+     * @default 0.2
+     */
     overloadedRatio?: number;
-    snapshotHistoryMillis?: number;
-    configuration: Configuration;
-    log?: CrawleeLogger;
 }
 /**
- * Tracks memory usage via `SYSTEM_INFO` events and reports overload when
- * the used-to-available memory ratio exceeds a threshold.
+ * Tracks memory usage via `SYSTEM_INFO` events and reports overload when the used-to-available memory ratio exceeds a
+ * threshold. Also warns when memory use becomes critical.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * @category Scaling
  */
 export declare class MemoryLoadSignal implements LoadSignal {
     readonly name = "memInfo";
     readonly overloadedRatio: number;
     private readonly store;
-    private readonly configuration;
-    private readonly events;
-    private readonly log;
-    private readonly maxUsedMemoryRatio;
-    private maxMemoryRatio;
+    private readonly maxUsedRatio;
+    /** All resolved in `start()`, before anything that reads them can fire. */
+    private config;
+    private log;
     private maxMemoryBytes;
+    private events?;
+    private maxMemoryRatio;
     private lastLoggedCriticalMemoryOverloadAt;
-    constructor(options: MemoryLoadSignalOptions);
-    start(): Promise<void>;
+    constructor(options?: MemoryLoadSignalOptions);
+    start(context: LoadSignalStartContext): Promise<void>;
     stop(): Promise<void>;
-    getSample(sampleDurationMillis?: number): MemorySnapshot[];
-    /**
-     * Returns typed memory snapshots for backward compatibility with `Snapshotter`.
-     */
-    getMemorySnapshots(): MemorySnapshot[];
-    /** @internal */
-    _onSystemInfo(systemInfo: SystemInfo): void;
+    getSample(sampleDurationMillis?: number): LoadSnapshot[];
+    /** @internal Records a snapshot from a `SYSTEM_INFO` payload. Exposed for tests. */
+    handle(systemInfo: SystemInfo): void;
     /** @internal */
     _memoryOverloadWarning(systemInfo: SystemInfo, maxMemoryBytes?: number): void;
     private _getTotalMemoryBytes;