@crawlee/core 4.0.0-beta.99 → 4.0.0-rc.0

package/crawlers/statistics.d.ts

@@ -1,4 +1,5 @@
 import type { CrawleeLogger } from '../log.js';
+import type { SyncStateConversion } from '../recoverable_state.js';
 import { KeyValueStore } from '../storages/key_value_store.js';
 import { ErrorTracker } from './error_tracker.js';
 /**
@@ -11,6 +12,68 @@ 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 can be
+ * plugged in without subclassing the crawler.
+ *
+ * `StateExtension` describes the custom fields tracked alongside the built-in {@link StatisticState} ones - see
+ * {@link StatisticsOptions.stateExtension}.
+ *
+ * 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<StateExtension extends object = {}> {
+    /** 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 & StateExtension;
+    /** 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?(): 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.
@@ -19,9 +82,13 @@ export interface PersistenceOptions {
  * under the key `CRAWLEE_CRAWLER_STATISTICS_*`, persists between
  * migrations and abort/resurrect
  *
+ * Custom fields are tracked by passing {@link StatisticsOptions.stateExtension|`stateExtension`} - the extra fields are then part
+ * of {@link Statistics.state|`state`}, persisted and restored along with the built-in ones.
+ *
  * @category Crawlers
  */
-export declare class Statistics {
+export declare class Statistics<StateExtension extends object = {}, PersistedStateExtension extends object = StateExtension> implements IStatistics<StateExtension> {
+    #private;
     private static id;
     /**
      * An error tracker for final retry errors.
@@ -35,38 +102,32 @@ export declare class Statistics {
      * Statistic instance id.
      */
     readonly id: string;
+    private readonly log;
     /**
      * Current statistic state used for doing calculations on {@link Statistics.calculate} calls
      */
-    state: StatisticState;
+    get state(): StatisticState & StateExtension;
     /**
      * Contains the current retries histogram. Index 0 means 0 retries, index 2, 2 retries, and so on
      */
-    readonly requestRetryHistogram: number[];
-    protected keyValueStore?: KeyValueStore;
-    protected readonly persistStateKey: string;
-    private logIntervalMillis;
-    private logMessage;
-    private listener;
-    private requestsInProgress;
-    private readonly log;
-    private instanceStart;
-    private logInterval;
-    private _events?;
-    private persistenceOptions;
-    private get events();
+    get requestRetryHistogram(): number[];
     /**
-     * @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 track extra fields via `state`.
      */
-    constructor(options?: StatisticsOptions);
+    constructor(options?: StatisticsOptions<StateExtension, PersistedStateExtension>);
     /**
-     * Set the current statistic instance to pristine values
+     * Set the current statistic instance to pristine values.
+     *
+     * The persisted record is left alone - use {@link Statistics.resetStore} to clear that as well.
      */
     reset(): void;
     /**
-     * @param options - Override the persistence options provided in the constructor
+     * Clear the persisted statistics record, leaving the in-memory state alone.
+     *
+     * Throws while capturing - the next PERSIST_STATE event would write the record straight back.
      */
-    resetStore(options?: PersistenceOptions): Promise<void>;
+    resetStore(): Promise<void>;
     /**
      * Increments the status code counter.
      */
@@ -95,15 +156,7 @@ export declare class Statistics {
     /**
      * 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
@@ -115,25 +168,22 @@ export declare class Statistics {
     stopCapturing(): Promise<void>;
     private saveRetryCountForJob;
     /**
-     * Persist internal state to the key value store
-     * @param options - Override the persistence options provided in the constructor
-     */
-    persistState(options?: PersistenceOptions): Promise<void>;
-    /**
-     * Loads the current statistic from the key value store if any
+     * Persist internal state to the key value store.
+     *
+     * Statistics are bookkeeping - a store that refuses the write is worth a warning, not a failed crawl. The
+     * crawler calls this from its migration handler, where a rejection would go unhandled.
      */
-    protected maybeLoadStatistics(): Promise<void>;
-    private teardown;
+    persistState(): Promise<void>;
     /**
      * Make this class serializable when called with `JSON.stringify(statsInstance)` directly
      * or through `keyValueStore.setValue('KEY', statsInstance)`
      */
-    toJSON(): StatisticPersistedState;
+    toJSON(): StatisticPersistedState & PersistedStateExtension;
 }
 /**
  * Configuration for the {@link Statistics} instance used by the crawler
  */
-export interface StatisticsOptions {
+export interface StatisticsOptions<StateExtension extends object = {}, PersistedStateExtension extends object = StateExtension> {
     /**
      * Interval in seconds to log the current statistics
      * @default 60
@@ -172,19 +222,81 @@ export interface StatisticsOptions {
      * if crawler creation order changes.
      */
     id?: string;
+    /**
+     * Custom fields to track alongside the built-in {@link StatisticState} ones. They become part of
+     * {@link Statistics.state|`state`} (typed as such), are persisted with the rest of the state, and are
+     * restored on migration or resurrect.
+     *
+     * ```ts
+     * const statistics = new Statistics({ stateExtension: { defaultState: { productsFound: 0 } } });
+     * statistics.state.productsFound++;
+     * ```
+     */
+    stateExtension?: StatisticStateExtensionOptions<StateExtension, PersistedStateExtension>;
 }
 /**
- * Format of the persisted stats
+ * How the custom fields of {@link StatisticsOptions.stateExtension} are initialized and converted to and from the
+ * persisted record - the same three things {@link RecoverableStateOptions} asks for, scoped to the custom half
+ * of the statistics state.
  */
-export interface StatisticPersistedState extends Omit<StatisticState, 'statsPersistedAt'> {
-    requestRetryHistogram: number[];
+export interface StatisticStateExtensionOptions<StateExtension extends object, PersistedStateExtension extends object = StateExtension> {
+    /**
+     * The values the fields start with, and the ones {@link Statistics.reset} restores. A plain value is
+     * deep-copied with `structuredClone` each time it is used; pass a factory for a state `structuredClone` cannot
+     * rebuild.
+     *
+     * Can be omitted when `deserialize` supplies its own defaults, which is then the single place the fields are
+     * declared - see the example on {@link StatisticStateExtensionOptions.deserialize|`deserialize`}.
+     */
+    defaultState?: StateExtension | (() => StateExtension);
+    /**
+     * Rebuilds the custom fields from the persisted record, and the place to validate them before trusting them.
+     * Receives the whole record, so it has to supply a value for every field - `.default()` in a schema, or
+     * {@link StatisticStateExtensionOptions.defaultState|`defaultState`} alongside a conversion that copes with
+     * a missing field itself.
+     *
+     * ```ts
+     * const statistics = new Statistics({
+     *     stateExtension: { deserialize: z.object({ productsFound: z.number().default(0) }) },
+     * });
+     * ```
+     *
+     * Without it, the declared fields are restored as they were persisted - which is a record off the key-value
+     * store taken at its word, `productsFound` included in whatever type it happens to hold.
+     *
+     * A conversion that rejects the record costs the custom fields their persisted values (they start from the
+     * defaults, with a warning) and nothing else.
+     */
+    deserialize?: SyncStateConversion<unknown, StateExtension>;
+    /**
+     * Converts the custom fields to the JSON-serializable form they are persisted in. Not needed for fields that
+     * already are one - pair it with `deserialize` for the fields that are not.
+     */
+    serialize?: SyncStateConversion<StateExtension, PersistedStateExtension>;
+}
+/**
+ * Format of the persisted stats.
+ *
+ * The `null`s are `Infinity` on the way out - JSON has no infinity, so a record written before anything
+ * finished or failed carries a `null` in its place.
+ */
+export interface StatisticPersistedState extends Omit<StatisticState, 'statsPersistedAt' | 'crawlerStartedAt' | 'crawlerFinishedAt' | 'requestMinDurationMillis' | 'requestsFailedPerMinute' | 'requestsFinishedPerMinute' | 'requestRetryHistogram' | 'instanceStart'> {
     statsId: string;
-    requestAvgFailedDurationMillis: number;
-    requestAvgFinishedDurationMillis: number;
+    requestsFailedPerMinute: number | null;
+    requestsFinishedPerMinute: number | null;
+    /** ISO strings - the live state keeps these as `Date`s. */
+    crawlerStartedAt: string | null;
+    crawlerFinishedAt: string | null;
+    statsPersistedAt: string;
+    requestMinDurationMillis: number | null;
+    /** A retry count that no request ever reached leaves a `null` here. */
+    requestRetryHistogram: (number | null)[];
+    requestAvgFailedDurationMillis: number | null;
+    requestAvgFinishedDurationMillis: number | null;
     requestTotalDurationMillis: number;
     requestsTotal: number;
+    /** {@link StatisticState.instanceStart} of the run that wrote the record. */
     crawlerLastStartTimestamp: number;
-    statsPersistedAt: string;
 }
 /**
  * Contains the statistics state
@@ -206,4 +318,11 @@ export interface StatisticState {
     errors: Record<string, unknown>;
     retryErrors: Record<string, unknown>;
     requestsWithStatusCode: Record<string, number>;
+    /** Retries histogram - index `i` holds the number of requests that finished after `i` retries. */
+    requestRetryHistogram: number[];
+    /**
+     * When the current capture window started, as a `Date.now()` timestamp. Rebased on load so that the runtime
+     * reported by {@link Statistics.calculate} spans a migration rather than restarting from zero.
+     */
+    instanceStart: number;
 }