@crawlee/core 4.0.0-beta.123 → 4.0.0-beta.125

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';
 /**
@@ -13,8 +14,11 @@ export interface PersistenceOptions {
 }
 /**
  * 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.
+ * 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
@@ -22,13 +26,13 @@ export interface PersistenceOptions {
  *
  * @category Crawlers
  */
-export interface IStatistics {
+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;
+    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. */
@@ -78,9 +82,12 @@ export interface CalculatedStatistics {
  * 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 implements IStatistics {
+export declare class Statistics<StateExtension extends object = {}, PersistedStateExtension extends object = StateExtension> implements IStatistics<StateExtension> {
     #private;
     private static id;
     /**
@@ -95,33 +102,26 @@ export declare class Statistics implements IStatistics {
      * Statistic instance id.
      */
     readonly id: string;
-    protected readonly persistStateKey: string;
     private readonly log;
     /**
      * Current statistic state used for doing calculations on {@link Statistics.calculate} calls
      */
-    get state(): StatisticState;
+    get state(): StatisticState & StateExtension;
     /**
      * Contains the current retries histogram. Index 0 means 0 retries, index 2, 2 retries, and so on
      */
     get requestRetryHistogram(): number[];
     /**
      * 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.
+     * 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.
      *
      * The persisted record is left alone - use {@link Statistics.resetStore} to clear that as well.
      */
     reset(): void;
-    /**
-     * The pristine state a new instance starts with and {@link Statistics.reset} restores.
-     *
-     * A subclass tracking extra fields declares their initial values here.
-     */
-    protected defaultState(): StatisticState;
     /**
      * Clear the persisted statistics record, leaving the in-memory state alone.
      *
@@ -174,27 +174,16 @@ export declare class Statistics implements IStatistics {
      * crawler calls this from its migration handler, where a rejection would go unhandled.
      */
     persistState(): Promise<void>;
-    /**
-     * Rebuilds the state from a persisted record.
-     *
-     * A subclass tracking extra fields restores them here, on top of the result of `super.deserializeState()`.
-     */
-    protected deserializeState(persistedState: StatisticPersistedState): StatisticState;
-    /**
-     * Builds the record written to the key value store, merging in the derived aggregates so that a consumer
-     * reading the record does not have to reconstruct them.
-     */
-    protected serializeState(state: StatisticState): StatisticPersistedState;
     /**
      * 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
@@ -233,6 +222,57 @@ 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>;
+}
+/**
+ * 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 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.

package/crawlers/statistics.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { RecoverableState } from '../recoverable_state.js';
+import { convertStateSync, RecoverableState } from '../recoverable_state.js';
 import { serviceLocator } from '../service_locator.js';
 import { KeyValueStore } from '../storages/key_value_store.js';
 import { parseArgument, schemas, validators } from '../validators.js';
@@ -27,6 +27,7 @@ const statisticsOptionsSchema = z.strictObject({
     persistenceOptions: schemas.anyObject.default(() => ({ enable: true })),
     saveErrorSnapshots: z.boolean().default(false),
     id: z.union([schemas.anyNumber, z.string()]).optional(),
+    stateExtension: schemas.anyObject.default(() => ({})),
 });
 const errorTrackerConfig = {
     showErrorCode: true,
@@ -44,12 +45,14 @@ const errorTrackerConfig = {
  * `null`. Both {@link Statistics.serializeState} and {@link Statistics.deserializeState} run through this,
  * which is what keeps them describing the same record.
  *
- * Nothing is optional on purpose: `serializeState` has always written every field, so a record missing one is not
- * one of ours and is discarded whole rather than partially trusted - a counter restored as a string would poison
- * every later increment.
+ * Nothing is optional on purpose: the record has always carried every field, so one missing a field is not one of
+ * ours and is discarded whole rather than partially trusted - a counter restored as a string would poison every
+ * later increment.
+ *
+ * Custom fields are not this schema's business either way: they are added to the record after the encode and
+ * validated by their own conversion on the way back, so the keys it does not know about are simply dropped here.
  */
-const persistedStatisticState = z
-    .object({
+const persistedStatisticState = z.object({
     requestsFinished: z.number(),
     requestsFailed: z.number(),
     requestsRetries: z.number(),
@@ -75,10 +78,7 @@ const persistedStatisticState = z
     requestsWithStatusCode: z.record(z.string(), z.number()),
     errors: z.record(z.string(), z.unknown()),
     retryErrors: z.record(z.string(), z.unknown()),
-})
-    // A subclass tracking extra fields spreads them into the record; they are none of this schema's business,
-    // but they must not be dropped on the way through it.
-    .catchall(z.unknown());
+});
 /** `Infinity` is what the statistics use for "nothing to average yet"; JSON has only `null` for it. */
 function finiteOrNull(value) {
     return Number.isFinite(value) ? value : null;
@@ -88,8 +88,7 @@ function finiteOrNull(value) {
  *
  * Built per instance rather than kept as a constant because a record carries three things the state does not: the
  * instance `id`, the derived aggregates of the overridable {@link Statistics.calculate}, and - on the way back -
- * the fields that are rebuilt from {@link Statistics.defaultState} rather than restored, the error trackers
- * among them.
+ * the fields that are rebuilt from the instance's default state rather than restored, the error trackers among them.
  *
  * The model side is deliberately opaque: zod rebuilds what it validates, and `state.errors` has to stay the very
  * object the error trackers write into, not a copy of it.
@@ -153,6 +152,9 @@ function buildStatisticStateCodec(statistics) {
  * 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 class Statistics {
@@ -170,9 +172,12 @@ export class Statistics {
      * Statistic instance id.
      */
     id;
-    persistStateKey;
+    #persistStateKey;
     #stateCodec;
     #recoverableState;
+    #stateExtension;
+    #defaultStateExtension;
+    #stateExtensionKeys;
     #logIntervalMillis;
     #logMessage;
     #requestsInProgress = new Map();
@@ -192,31 +197,40 @@ export class Statistics {
     }
     /**
      * 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.
+     * persistence or error snapshots, share it across sequential runs, or track extra fields via `state`.
      */
     constructor(options = {}) {
-        const { logIntervalSecs, logMessage, log, keyValueStore, persistenceOptions, saveErrorSnapshots, id } = parseArgument(options, statisticsOptionsSchema);
+        const { logIntervalSecs, logMessage, log, keyValueStore, persistenceOptions, saveErrorSnapshots, id, stateExtension, } = parseArgument(options, statisticsOptionsSchema);
         this.id = id ?? String(Statistics.id++);
-        this.persistStateKey = `CRAWLEE_CRAWLER_STATISTICS_${this.id}`;
+        this.#persistStateKey = `CRAWLEE_CRAWLER_STATISTICS_${this.id}`;
         this.log = (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;
-        // Late-bound on purpose - both hooks are override points, and a subclass's must be the ones that run.
+        this.#stateExtension = stateExtension;
+        this.#defaultStateExtension = this.#resolveDefaultStateExtension(this.#stateExtension);
+        this.#stateExtensionKeys = Object.keys(this.#defaultStateExtension());
+        for (const key of this.#stateExtensionKeys) {
+            if (key in this.#builtInDefaultState()) {
+                throw new Error(`The custom statistics field \`${String(key)}\` collides with a built-in one - it would shadow ` +
+                    'the value the crawler tracks. Rename it in `stateExtension`.');
+            }
+        }
+        // `calculate()` is late-bound on purpose - it is an override point, and a subclass's must be the one that runs.
         this.#stateCodec = buildStatisticStateCodec({
             statsId: this.id,
-            defaultState: () => this.defaultState(),
+            defaultState: () => this.#defaultState(),
             calculate: () => this.calculate(),
         });
         this.#recoverableState = new RecoverableState({
-            persistStateKey: this.persistStateKey,
+            persistStateKey: this.#persistStateKey,
             persistenceEnabled: persistenceOptions.enable,
             keyValueStore,
             logger: this.log,
-            defaultState: () => this.defaultState(),
-            serialize: (state) => this.serializeState(state),
-            deserialize: (persistedState) => this.deserializeState(persistedState),
+            defaultState: () => this.#defaultState(),
+            serialize: (state) => this.#serializeState(state),
+            deserialize: (persistedState) => this.#deserializeState(persistedState),
         });
         // initialize by "resetting"
         this.reset();
@@ -232,12 +246,44 @@ export class Statistics {
         this.#recoverableState.reset();
         this.#requestsInProgress.clear();
     }
+    /** The pristine state a new instance starts with and {@link Statistics.reset} restores. */
+    #defaultState() {
+        return {
+            ...this.#builtInDefaultState(),
+            ...this.#defaultStateExtension(),
+        };
+    }
     /**
-     * The pristine state a new instance starts with and {@link Statistics.reset} restores.
+     * The factory behind the custom half of the default state - it has to hand out a fresh object every time, or a
+     * `reset()` would write through to the defaults of the next one.
      *
-     * A subclass tracking extra fields declares their initial values here.
+     * With no `defaultState` given, the defaults are what `deserialize` makes of an empty record. That keeps a
+     * single declaration of the custom fields - a schema with a `.default()` per field is enough - and the defaults
+     * cannot then disagree with the conversion that has to accept them back.
      */
-    defaultState() {
+    #resolveDefaultStateExtension(options) {
+        const { defaultState, deserialize } = options;
+        if (typeof defaultState === 'function') {
+            return defaultState;
+        }
+        if (defaultState !== undefined) {
+            return () => structuredClone(defaultState);
+        }
+        if (deserialize === undefined) {
+            return () => ({});
+        }
+        return () => {
+            try {
+                return convertStateSync(deserialize, {}, this.#persistStateKey);
+            }
+            catch (error) {
+                throw new Error('Could not derive the default values of the custom statistics fields from `stateExtension.deserialize` - ' +
+                    'give every field a default, or declare `stateExtension.defaultState` explicitly.', { cause: error });
+            }
+        };
+    }
+    /** The built-in half of {@link Statistics.defaultState}, before any custom fields are merged over it. */
+    #builtInDefaultState() {
         return {
             requestsFinished: 0,
             requestsFailed: 0,
@@ -390,28 +436,58 @@ export class Statistics {
     async persistState() {
         await this.#recoverableState
             .persistState()
-            .catch((error) => this.log.warning(`Failed to persist the statistics to ${this.persistStateKey}`, { error }));
+            .catch((error) => this.log.warning(`Failed to persist the statistics to ${this.#persistStateKey}`, { error }));
     }
-    /**
-     * Rebuilds the state from a persisted record.
-     *
-     * A subclass tracking extra fields restores them here, on top of the result of `super.deserializeState()`.
-     */
-    deserializeState(persistedState) {
-        // The cast is the index signature the `catchall` puts on the schema and an interface cannot have - the
-        // record is an unvalidated blob off the key-value store either way, which is what the decode is for.
+    /** Rebuilds the state from a persisted record. */
+    #deserializeState(persistedState) {
+        // The cast covers the custom fields, whose type is open here - and the record is an unvalidated blob off the
+        // key-value store either way, which is what the decode is for. Their keys are not in the schema, so the
+        // decode drops them; `#restoreStateExtension` is what brings them back.
         const restored = z.safeDecode(this.#stateCodec, persistedState);
         if (!restored.success) {
             // Statistics are bookkeeping - a record that cannot be made sense of is worth a warning and a fresh
             // start, not a failed crawl.
             this.log.warning('Received invalid state from Key-value store, starting the statistics from scratch.', {
-                persistStateKey: this.persistStateKey,
+                persistStateKey: this.#persistStateKey,
                 issues: restored.error.issues,
             });
-            return this.defaultState();
+            return this.#defaultState();
+        }
+        this.log.debug('Recreating state from KeyValueStore', { persistStateKey: this.#persistStateKey });
+        return { ...this.#defaultState(), ...restored.data, ...this.#restoreStateExtension(persistedState) };
+    }
+    /**
+     * The custom {@link StatisticsOptions.stateExtension|`stateExtension`} fields as they were persisted - the codec only rebuilds
+     * the built-in ones.
+     *
+     * Given a `deserialize`, the whole record goes through it, so a field the record does not carry - one declared
+     * after the record was written - comes back as whatever default the conversion gives it. Without one, the
+     * declared keys are copied over as they were persisted and a missing one keeps the default it already has.
+     */
+    #restoreStateExtension(persistedState) {
+        const { deserialize } = this.#stateExtension;
+        if (deserialize === undefined) {
+            const restored = {};
+            for (const key of this.#stateExtensionKeys) {
+                // The record is an unvalidated blob and there is no conversion to check it with, so this is the
+                // caller's word for it - the state ends up holding whatever was written. The two halves only line
+                // up at all because the fields are persisted as they are without a `serialize`.
+                const persistedValue = persistedState[key];
+                if (persistedValue !== undefined) {
+                    restored[key] = persistedValue;
+                }
+            }
+            return restored;
+        }
+        try {
+            return convertStateSync(deserialize, persistedState, this.#persistStateKey);
+        }
+        catch (error) {
+            // Same policy as a built-in field that cannot be made sense of, but scoped to the custom ones - a
+            // corrupt counter of your own is no reason to throw away the crawler's.
+            this.log.warning('Received invalid custom statistics fields from Key-value store, starting those from scratch.', { persistStateKey: this.#persistStateKey, error });
+            return {};
         }
-        this.log.debug('Recreating state from KeyValueStore', { persistStateKey: this.persistStateKey });
-        return { ...this.defaultState(), ...restored.data };
     }
     #stopLogging() {
         if (this.#logInterval) {
@@ -423,14 +499,38 @@ export class Statistics {
      * Builds the record written to the key value store, merging in the derived aggregates so that a consumer
      * reading the record does not have to reconstruct them.
      */
-    serializeState(state) {
-        return z.encode(this.#stateCodec, state);
+    #serializeState(state) {
+        const { builtIn, extension } = this.#splitState(state);
+        return {
+            ...z.encode(this.#stateCodec, builtIn),
+            ...this.#serializeStateExtension(extension),
+        };
+    }
+    /** The custom {@link StatisticsOptions.stateExtension|`stateExtension`} fields as they go into the record. */
+    #serializeStateExtension(extension) {
+        const { serialize } = this.#stateExtension;
+        if (serialize === undefined) {
+            return extension;
+        }
+        // Unlike the way back, a failure here throws: the value is the caller's own, and a record written from a
+        // state that does not match its own declaration is not worth having.
+        return convertStateSync(serialize, extension, this.#persistStateKey);
+    }
+    /** Separates the declared custom fields from the built-in ones, so that each half goes through its own conversion. */
+    #splitState(state) {
+        const builtIn = { ...state };
+        const extension = {};
+        for (const key of this.#stateExtensionKeys) {
+            extension[key] = state[key];
+            delete builtIn[key];
+        }
+        return { builtIn, extension };
     }
     /**
      * Make this class serializable when called with `JSON.stringify(statsInstance)` directly
      * or through `keyValueStore.setValue('KEY', statsInstance)`
      */
     toJSON() {
-        return this.serializeState(this.state);
+        return this.#serializeState(this.state);
     }
 }

package/events/event_manager.js

@@ -18,7 +18,8 @@ export class EventManager {
     #persistStateIntervalMillis;
     constructor(options) {
         this.#persistStateIntervalMillis = options.persistStateIntervalMillis;
-        this.events.setMaxListeners(50);
+        // One MIGRATING listener per RequestQueue, and ThrottlingRequestManager opens one per domain.
+        this.events.setMaxListeners(150);
     }
     /**
      * Initializes the event manager by starting the `persistState` event interval.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/core",
-    "version": "4.0.0-beta.123",
+    "version": "4.0.0-beta.125",
     "description": "The scalable web crawling and scraping library for JavaScript/Node.js. Enables development of data extraction and web automation jobs (not only) with headless Chrome and Puppeteer.",
     "engines": {
         "node": ">=22.0.0"
@@ -52,11 +52,12 @@
         "@apify/log": "^2.5.18",
         "@apify/timeout": "^0.4.4",
         "@apify/utilities": "^2.15.5",
-        "@crawlee/fs-storage": "4.0.0-beta.123",
-        "@crawlee/http-client": "4.0.0-beta.123",
-        "@crawlee/types": "4.0.0-beta.123",
-        "@crawlee/utils": "4.0.0-beta.123",
+        "@crawlee/fs-storage": "4.0.0-beta.125",
+        "@crawlee/http-client": "4.0.0-beta.125",
+        "@crawlee/types": "4.0.0-beta.125",
+        "@crawlee/utils": "4.0.0-beta.125",
         "@sapphire/async-queue": "^1.5.5",
+        "@standard-schema/spec": "^1.0.0",
         "@vladfrangu/async_event_emitter": "^2.4.6",
         "content-type": "^1.0.5",
         "csv-stringify": "^6.5.2",
@@ -77,5 +78,5 @@
             }
         }
     },
-    "gitHead": "f77648095c6a3f5ed8815c7620ea765db430ae44"
+    "gitHead": "04a7212dd4abe4a5f94f5fc9632acb6089819c8b"
 }

package/recoverable_state.d.ts

@@ -11,6 +11,21 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * other one.
  */
 export type StateConversion<TFrom, TTo> = ((value: TFrom) => Awaitable<TTo>) | StandardSchemaV1<TFrom, TTo>;
+/**
+ * A {@link StateConversion} for a caller that cannot await one - {@link Statistics}, whose `toJSON()` is
+ * synchronous, being the reason this exists.
+ *
+ * Only the function arm can be narrowed here: a Standard Schema is free to validate asynchronously, so a schema
+ * that does is rejected when it runs rather than when it is passed.
+ */
+export type SyncStateConversion<TFrom, TTo> = ((value: TFrom) => TTo) | StandardSchemaV1<TFrom, TTo>;
+/**
+ * Applies a {@link SyncStateConversion}, throwing a {@link StateValidationError} for a schema that rejects
+ * the value.
+ *
+ * @internal
+ */
+export declare function convertStateSync<TFrom, TTo>(conversion: SyncStateConversion<TFrom, TTo>, value: TFrom, persistStateKey: string): TTo;
 export interface RecoverableStatePersistenceOptions {
     /**
      * The key under which the state is stored in the KeyValueStore

package/recoverable_state.js

@@ -1,6 +1,25 @@
 import { addTimeoutToPromise, storage as timeoutStorage } from '@apify/timeout';
 import { EventType, KeyValueStore, serviceLocator, StateValidationError } from '@crawlee/core';
 const DEFAULT_PERSISTENCE_TIMEOUT_MILLIS = 60_000;
+/**
+ * Applies a {@link SyncStateConversion}, throwing a {@link StateValidationError} for a schema that rejects
+ * the value.
+ *
+ * @internal
+ */
+export function convertStateSync(conversion, value, persistStateKey) {
+    if (typeof conversion === 'function') {
+        return conversion(value);
+    }
+    const result = conversion['~standard'].validate(value);
+    if ('then' in result) {
+        throw new Error(`The state conversion for '${persistStateKey}' validated asynchronously, which this caller cannot await.`);
+    }
+    if (result.issues) {
+        throw new StateValidationError(persistStateKey, result.issues);
+    }
+    return result.value;
+}
 /**
  * A class for managing persistent recoverable state using a plain JavaScript object.
  *