@crawlee/core 4.0.0-beta.118 → 4.0.0-beta.119

package/errors.d.ts

@@ -14,6 +14,16 @@ export declare class CriticalError extends NonRetryableError {
  */
 export declare class MissingRouteError extends CriticalError {
 }
+/**
+ * A schema validation issue, structurally compatible with `StandardSchemaV1.Issue`. Declared here so that
+ * error types do not have to depend on `@standard-schema/spec`.
+ */
+export interface SchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        key: PropertyKey;
+    })[];
+}
 /**
  * Thrown when a request's `userData` does not match the {@link RouteSchemas|Standard Schema} registered for its label.
  *
@@ -21,18 +31,19 @@ export declare class MissingRouteError extends CriticalError {
  */
 export declare class RequestValidationError extends NonRetryableError {
     readonly label: string | symbol;
-    readonly issues: readonly {
-        readonly message: string;
-        readonly path?: readonly (PropertyKey | {
-            key: PropertyKey;
-        })[];
-    }[];
-    constructor(label: string | symbol, issues: readonly {
-        readonly message: string;
-        readonly path?: readonly (PropertyKey | {
-            key: PropertyKey;
-        })[];
-    }[]);
+    readonly issues: readonly SchemaIssue[];
+    constructor(label: string | symbol, issues: readonly SchemaIssue[]);
+}
+/**
+ * Thrown by {@link RecoverableState} when a persisted state record does not match its `stateSchema`.
+ *
+ * Whether a corrupt record should abort the run or be discarded in favour of the defaults depends on what the
+ * state is for, so {@link RecoverableState.initialize} always throws and leaves the choice to the caller.
+ */
+export declare class StateValidationError extends Error {
+    readonly persistStateKey: string;
+    readonly issues: readonly SchemaIssue[];
+    constructor(persistStateKey: string, issues: readonly SchemaIssue[]);
 }
 /**
  * Errors of `RetryRequestError` type will always be retried by the crawler.

package/errors.js

@@ -15,6 +15,16 @@ export class CriticalError extends NonRetryableError {
  */
 export class MissingRouteError extends CriticalError {
 }
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((segment) => (typeof segment === 'object' ? segment.key : segment))
+            .join('.');
+        return `- ${path ? `${path}: ` : ''}${issue.message}`;
+    })
+        .join('\n');
+}
 /**
  * Thrown when a request's `userData` does not match the {@link RouteSchemas|Standard Schema} registered for its label.
  *
@@ -24,19 +34,26 @@ export class RequestValidationError extends NonRetryableError {
     label;
     issues;
     constructor(label, issues) {
-        const details = issues
-            .map((issue) => {
-            const path = (issue.path ?? [])
-                .map((segment) => (typeof segment === 'object' ? segment.key : segment))
-                .join('.');
-            return `- ${path ? `${path}: ` : ''}${issue.message}`;
-        })
-            .join('\n');
-        super(`Request userData for label '${String(label)}' failed schema validation:\n${details}`);
+        super(`Request userData for label '${String(label)}' failed schema validation:\n${formatIssues(issues)}`);
         this.label = label;
         this.issues = issues;
     }
 }
+/**
+ * Thrown by {@link RecoverableState} when a persisted state record does not match its `stateSchema`.
+ *
+ * Whether a corrupt record should abort the run or be discarded in favour of the defaults depends on what the
+ * state is for, so {@link RecoverableState.initialize} always throws and leaves the choice to the caller.
+ */
+export class StateValidationError extends Error {
+    persistStateKey;
+    issues;
+    constructor(persistStateKey, issues) {
+        super(`State persisted under key '${persistStateKey}' failed schema validation:\n${formatIssues(issues)}`);
+        this.persistStateKey = persistStateKey;
+        this.issues = issues;
+    }
+}
 /**
  * Errors of `RetryRequestError` type will always be retried by the crawler.
  *

package/memory-storage/memory-storage.d.ts

@@ -21,17 +21,13 @@ export declare class MemoryStorageBackend implements storage.StorageBackend {
      * cache partitions in the storage backend cache.
      */
     getStorageBackendCacheKey(): string;
-    private static resolveStorageKey;
     createDatasetBackend(options?: storage.StorageIdentifier): Promise<storage.DatasetBackend>;
     createKeyValueStoreBackend(options?: storage.StorageIdentifier): Promise<storage.KeyValueStoreBackend>;
     createRequestQueueBackend(options?: storage.StorageIdentifier): Promise<RequestQueueBackend>;
     storageExists(id: string, type: 'Dataset' | 'KeyValueStore' | 'RequestQueue'): Promise<boolean>;
     /**
-     * Cleans up the default storages before the run starts. For the in-memory storage this simply
-     * resets the in-memory state of the cached default dataset, key-value store and request queue.
-     *
-     * As with `FileSystemStorageBackend`, the run's input (the `INPUT` key in the default key-value
-     * store) is preserved — only the rest of the default storages is cleared.
+     * Cleans up the run-scoped storages before the run starts. For the in-memory storage this simply
+     * resets the in-memory state of the cached backends.
      */
     purge(): Promise<void>;
     /**

package/memory-storage/memory-storage.js

@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { DatasetBackend } from './resource-clients/dataset.js';
 import { KeyValueStoreBackend } from './resource-clients/key-value-store.js';
 import { RequestQueueBackend } from './resource-clients/request-queue.js';
+/** The alias the default (unnamed) storage is opened under. */
+const DEFAULT_STORAGE_ALIAS = '__default__';
 export class MemoryStorageBackend {
     logger;
     /**
@@ -22,22 +24,24 @@ export class MemoryStorageBackend {
     getStorageBackendCacheKey() {
         return this.#instanceCacheKey;
     }
-    static resolveStorageKey(options) {
-        const isAlias = 'alias' in options && !!options.alias;
-        const rawKey = isAlias ? options.alias : (options.name ?? options.id);
+    static #resolveStorageKey(options) {
+        // No identifier at all means the default storage, which is opened under the reserved alias —
+        // same rule as `resolveStorageIdentifier` in the storage frontends, so that a backend used
+        // directly lands on the very storage the frontends would have opened.
+        const alias = options.alias || (!options.id && !options.name ? DEFAULT_STORAGE_ALIAS : undefined);
+        // `alias` covers the identifier-less case, so one of the three is always set.
+        const rawKey = alias ?? options.name ?? options.id;
         // Normalize the internal __default__ alias to the user-facing 'default' name.
-        const cacheKey = rawKey === '__default__' ? 'default' : rawKey;
-        return { isAlias, cacheKey };
+        const cacheKey = rawKey === DEFAULT_STORAGE_ALIAS ? 'default' : rawKey;
+        return { isAlias: alias !== undefined, cacheKey };
     }
     async createDatasetBackend(options = {}) {
-        const { isAlias, cacheKey } = MemoryStorageBackend.resolveStorageKey(options);
-        if (cacheKey) {
-            const found = this.datasetBackendCache.find((store) => store.id === cacheKey ||
-                store.name?.toLowerCase() === cacheKey.toLowerCase() ||
-                store.cacheKey.toLowerCase() === cacheKey.toLowerCase());
-            if (found) {
-                return found;
-            }
+        const { isAlias, cacheKey } = MemoryStorageBackend.#resolveStorageKey(options);
+        const found = this.datasetBackendCache.find((store) => store.id === cacheKey ||
+            store.name?.toLowerCase() === cacheKey.toLowerCase() ||
+            store.cacheKey.toLowerCase() === cacheKey.toLowerCase());
+        if (found) {
+            return found;
         }
         const newStore = new DatasetBackend({
             name: isAlias ? undefined : cacheKey,
@@ -48,14 +52,12 @@ export class MemoryStorageBackend {
         return newStore;
     }
     async createKeyValueStoreBackend(options = {}) {
-        const { isAlias, cacheKey } = MemoryStorageBackend.resolveStorageKey(options);
-        if (cacheKey) {
-            const found = this.keyValueStoreBackendCache.find((store) => store.id === cacheKey ||
-                store.name?.toLowerCase() === cacheKey.toLowerCase() ||
-                store.cacheKey.toLowerCase() === cacheKey.toLowerCase());
-            if (found) {
-                return found;
-            }
+        const { isAlias, cacheKey } = MemoryStorageBackend.#resolveStorageKey(options);
+        const found = this.keyValueStoreBackendCache.find((store) => store.id === cacheKey ||
+            store.name?.toLowerCase() === cacheKey.toLowerCase() ||
+            store.cacheKey.toLowerCase() === cacheKey.toLowerCase());
+        if (found) {
+            return found;
         }
         const newStore = new KeyValueStoreBackend({
             name: isAlias ? undefined : cacheKey,
@@ -66,14 +68,12 @@ export class MemoryStorageBackend {
         return newStore;
     }
     async createRequestQueueBackend(options = {}) {
-        const { isAlias, cacheKey } = MemoryStorageBackend.resolveStorageKey(options);
-        if (cacheKey) {
-            const found = this.requestQueueBackendCache.find((queue) => queue.id === cacheKey ||
-                queue.name?.toLowerCase() === cacheKey.toLowerCase() ||
-                queue.cacheKey.toLowerCase() === cacheKey.toLowerCase());
-            if (found) {
-                return found;
-            }
+        const { isAlias, cacheKey } = MemoryStorageBackend.#resolveStorageKey(options);
+        const found = this.requestQueueBackendCache.find((queue) => queue.id === cacheKey ||
+            queue.name?.toLowerCase() === cacheKey.toLowerCase() ||
+            queue.cacheKey.toLowerCase() === cacheKey.toLowerCase());
+        if (found) {
+            return found;
         }
         const newStore = new RequestQueueBackend({
             name: isAlias ? undefined : cacheKey,
@@ -102,28 +102,22 @@ export class MemoryStorageBackend {
         return backends.some((store) => store.id === id);
     }
     /**
-     * Cleans up the default storages before the run starts. For the in-memory storage this simply
-     * resets the in-memory state of the cached default dataset, key-value store and request queue.
-     *
-     * As with `FileSystemStorageBackend`, the run's input (the `INPUT` key in the default key-value
-     * store) is preserved — only the rest of the default storages is cleared.
+     * Cleans up the run-scoped storages before the run starts. For the in-memory storage this simply
+     * resets the in-memory state of the cached backends.
      */
     async purge() {
-        // The run default is opened via `{ alias: '__default__' }`, which `resolveStorageKey`
-        // normalizes to `cacheKey === 'default'` (with `name === undefined`) — that is the clause
-        // that actually matches it. The `name === 'default'` clause additionally covers a store a user
-        // explicitly opened via `{ name: 'default' }`. (`'__default__'` never reaches `cacheKey`,
-        // as it is always normalized to `'default'` first, so it does not need to be checked here.)
+        // `#resolveStorageKey` leaves `name` unset for the default and alias-keyed storages, which is what
+        // marks them as run-scoped. `'default'` is the exception — it collapses onto the default storage.
+        const isRunScoped = (store) => store.name === undefined || store.name === 'default';
         const isDefault = (store) => store.name === 'default' || store.cacheKey === 'default';
-        const purgeDefaults = async (cache, purgeStore) => {
-            await Promise.all(cache.filter(isDefault).map(async (store) => purgeStore(store)));
+        const purgeRunScoped = async (cache, purgeStore) => {
+            await Promise.all(cache.filter(isRunScoped).map(async (store) => purgeStore(store)));
         };
         await Promise.all([
-            // Preserve the run input (INPUT) when purging the default key-value store, matching
-            // `FileSystemStorageBackend`.
-            purgeDefaults(this.keyValueStoreBackendCache, async (store) => store.purgeExceptInput()),
-            purgeDefaults(this.datasetBackendCache, async (store) => store.purge()),
-            purgeDefaults(this.requestQueueBackendCache, async (store) => store.purge()),
+            // Only the default store holds the run input, so it is the only one that keeps `INPUT`.
+            purgeRunScoped(this.keyValueStoreBackendCache, async (store) => isDefault(store) ? store.purgeExceptInput() : store.purge()),
+            purgeRunScoped(this.datasetBackendCache, async (store) => store.purge()),
+            purgeRunScoped(this.requestQueueBackendCache, async (store) => store.purge()),
         ]);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/core",
-    "version": "4.0.0-beta.118",
+    "version": "4.0.0-beta.119",
     "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,9 +52,9 @@
         "@apify/log": "^2.5.18",
         "@apify/timeout": "^0.4.4",
         "@apify/utilities": "^2.15.5",
-        "@crawlee/fs-storage": "4.0.0-beta.118",
-        "@crawlee/types": "4.0.0-beta.118",
-        "@crawlee/utils": "4.0.0-beta.118",
+        "@crawlee/fs-storage": "4.0.0-beta.119",
+        "@crawlee/types": "4.0.0-beta.119",
+        "@crawlee/utils": "4.0.0-beta.119",
         "@sapphire/async-queue": "^1.5.5",
         "@sapphire/shapeshift": "^4.0.0",
         "@vladfrangu/async_event_emitter": "^2.4.6",
@@ -78,5 +78,5 @@
             }
         }
     },
-    "gitHead": "7306bd05a126662898a4f2fe7779f6b53425cadf"
+    "gitHead": "552fe2371a3c6e9e9f3514010536ea6abdc27eb4"
 }

package/recoverable_state.d.ts

@@ -1,4 +1,16 @@
 import type { Configuration, CrawleeLogger } from '@crawlee/core';
+import { KeyValueStore } from '@crawlee/core';
+import type { Awaitable } from '@crawlee/types';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * One direction of the conversion between the state model and its persisted form - either a plain function, or a
+ * [Standard Schema](https://standardschema.dev) whose validated output is the result.
+ *
+ * A schema that fails to validate makes {@link RecoverableState} throw a {@link StateValidationError}. Zod
+ * codecs work directly, as their validation *is* the decode direction; use `(state) => codec.encode(state)` for the
+ * other one.
+ */
+export type StateConversion<TFrom, TTo> = ((value: TFrom) => Awaitable<TTo>) | StandardSchemaV1<TFrom, TTo>;
 export interface RecoverableStatePersistenceOptions {
     /**
      * The key under which the state is stored in the KeyValueStore
@@ -9,44 +21,45 @@ export interface RecoverableStatePersistenceOptions {
      */
     persistenceEnabled?: boolean;
     /**
-     * The name of the KeyValueStore to use for persistence.
-     * If neither a name nor an id are supplied, the default store will be used.
+     * The KeyValueStore to persist into, defaulting to the default store. Accepts a pending
+     * {@link KeyValueStore.open} so that callers do not have to be async to point at a specific store.
      */
-    persistStateKvsName?: string;
+    keyValueStore?: KeyValueStore | PromiseLike<KeyValueStore>;
     /**
-     * The identifier of the KeyValueStore to use for persistence.
-     * If neither a name nor an id are supplied, the default store will be used.
+     * Time limit for a single load or save of the state, in milliseconds.
+     * @default 60_000
      */
-    persistStateKvsId?: string;
+    persistenceTimeoutMillis?: number;
 }
 /**
  * Options for configuring the RecoverableState
  */
-export interface RecoverableStateOptions<TStateModel = Record<string, unknown>> extends RecoverableStatePersistenceOptions {
+export interface RecoverableStateOptions<TStateModel = Record<string, unknown>, TPersistedState = TStateModel> extends RecoverableStatePersistenceOptions {
     /**
-     * The default state used if no persisted state is found.
-     * A deep copy is made each time the state is used.
+     * The state used when no persisted state is found, and the state {@link RecoverableState.reset} restores.
+     *
+     * A plain value is deep-copied with `structuredClone` each time it is used, so pass a factory for a state
+     * that `structuredClone` cannot rebuild - one holding class instances, say, or one derived from a schema.
      */
-    defaultState: TStateModel;
+    defaultState: TStateModel | (() => TStateModel);
     /**
      * A logger instance for logging operations related to state persistence
      */
     logger?: CrawleeLogger;
     /**
-     * Configuration instance to use
+     * Configuration instance to use when opening the KeyValueStore
      */
     configuration?: Configuration;
     /**
-     * Optional function to transform the state to a JSON string before persistence.
-     * If not provided, JSON.stringify will be used.
+     * Optional conversion of the state to a plain JSON-serializable value before it is persisted.
+     * If not provided, the state is persisted as is.
      */
-    serialize?: (state: TStateModel) => string;
+    serialize?: StateConversion<TStateModel, TPersistedState>;
     /**
-     * Optional function to transform a JSON-serialized object back to the state model.
-     * If not provided, JSON.parse is used.
-     * It is advisable to perform validation in this function and to throw an exception if it fails.
+     * Optional conversion of a persisted value back to the state model, and the place to validate a record before
+     * trusting it. If not provided, the persisted value is used as is.
      */
-    deserialize?: (serializedState: string) => TStateModel;
+    deserialize?: StateConversion<TPersistedState, TStateModel>;
 }
 /**
  * A class for managing persistent recoverable state using a plain JavaScript object.
@@ -58,19 +71,23 @@ export interface RecoverableStateOptions<TStateModel = Record<string, unknown>>
  * The state is represented by a plain JavaScript object that can be serialized to and deserialized from JSON.
  * The class automatically hooks into the event system to persist state when needed.
  */
-export declare class RecoverableState<TStateModel = Record<string, unknown>> {
+export declare class RecoverableState<TStateModel = Record<string, unknown>, TPersistedState = TStateModel> {
     #private;
     /**
      * Initialize a new recoverable state object.
      *
      * @param options Configuration options for the recoverable state
      */
-    constructor(options: RecoverableStateOptions<TStateModel>);
+    constructor(options: RecoverableStateOptions<TStateModel, TPersistedState>);
     /**
      * Initialize the recoverable state.
      *
-     * This method must be called before using the recoverable state. It loads the saved state
-     * if persistence is enabled and registers the object to listen for PERSIST_STATE events.
+     * If persistence is enabled, this method loads the saved state and registers the object to listen for
+     * PERSIST_STATE events. A state established beforehand by {@link RecoverableState.reset} survives if there
+     * is no record to restore.
+     *
+     * Calling this again after a {@link RecoverableState.teardown} starts a new persistence window - the
+     * listener is registered again and the record reloaded.
      *
      * @returns The loaded state object
      */
@@ -79,33 +96,45 @@ export declare class RecoverableState<TStateModel = Record<string, unknown>> {
      * Clean up resources used by the recoverable state.
      *
      * If persistence is enabled, this method deregisters the object from PERSIST_STATE events
-     * and persists the current state one last time.
+     * and persists the current state one last time, warning rather than throwing if that write fails - cleanup
+     * runs when the work is already done, and failing it would bury whatever the caller was doing. The in-memory
+     * state is left alone, and {@link RecoverableState.initialize} can be called again to open a new
+     * persistence window.
      */
     teardown(): Promise<void>;
     /**
      * Get the current state.
+     *
+     * Throws until the state has been established, by either {@link RecoverableState.initialize} or the
+     * synchronous {@link RecoverableState.reset} - the latter being how a caller that cannot await in its
+     * constructor gets a usable state right away.
      */
     get currentValue(): TStateModel;
     /**
-     * Reset the state to the default values and clear any persisted state.
+     * Reset the in-memory state to the default values, leaving any persisted record alone.
      *
-     * Resets the current state to the default state and, if persistence is enabled,
-     * clears the persisted state from the KeyValueStore.
+     * Use {@link RecoverableState.resetStore} to clear the persisted record as well.
      */
-    reset(): Promise<void>;
+    reset(): void;
+    /**
+     * Clear the persisted state record, leaving the in-memory state alone.
+     *
+     * This is a between-lifecycles operation - its point is to stop the next {@link RecoverableState.initialize}
+     * from restoring the record, so it throws while PERSIST_STATE events are still being handled, where the next
+     * one would write the record straight back. Use {@link RecoverableState.reset} to reset the state itself,
+     * or {@link RecoverableState.teardown} before clearing the record.
+     *
+     * A no-op if persistence is disabled or no KeyValueStore is available yet.
+     */
+    resetStore(): Promise<void>;
     /**
      * Persist the current state to the KeyValueStore.
      *
      * This method is typically called in response to a PERSIST_STATE event, but can also be called
-     * directly when needed.
+     * directly when needed. It is a no-op if persistence is disabled, if no KeyValueStore is available yet, or if
+     * there is no state to write. A failed write only rejects here - the periodic and teardown ones warn instead.
      *
      * @param eventData Optional data associated with a PERSIST_STATE event
      */
-    persistState(eventData?: {
-        isMigrating: boolean;
-    }): Promise<void>;
-    /**
-     * Load the saved state from the KeyValueStore
-     */
-    private loadSavedState;
+    persistState(eventData?: Record<string, unknown>): Promise<void>;
 }

package/recoverable_state.js

@@ -1,4 +1,6 @@
-import { EventType, KeyValueStore, serviceLocator } from '@crawlee/core';
+import { addTimeoutToPromise, storage as timeoutStorage } from '@apify/timeout';
+import { EventType, KeyValueStore, serviceLocator, StateValidationError } from '@crawlee/core';
+const DEFAULT_PERSISTENCE_TIMEOUT_MILLIS = 60_000;
 /**
  * A class for managing persistent recoverable state using a plain JavaScript object.
  *
@@ -12,132 +14,199 @@ import { EventType, KeyValueStore, serviceLocator } from '@crawlee/core';
 export class RecoverableState {
     #defaultState;
     #state = null;
+    #initialized = false;
+    #listening = false;
     #persistenceEnabled;
     #persistStateKey;
-    #persistStateKvsName;
-    #persistStateKvsId;
-    #keyValueStore = null;
+    #persistenceTimeoutMillis;
+    #configuration;
+    #keyValueStore;
     #log;
     #serialize;
     #deserialize;
+    #persistStateQuietly;
     /**
      * Initialize a new recoverable state object.
      *
      * @param options Configuration options for the recoverable state
      */
     constructor(options) {
-        this.#defaultState = options.defaultState;
+        const { defaultState } = options;
+        this.#defaultState =
+            typeof defaultState === 'function'
+                ? defaultState
+                : () => structuredClone(defaultState);
         this.#persistStateKey = options.persistStateKey;
         this.#persistenceEnabled = options.persistenceEnabled ?? false;
-        this.#persistStateKvsName = options.persistStateKvsName;
-        this.#persistStateKvsId = options.persistStateKvsId;
+        this.#persistenceTimeoutMillis = options.persistenceTimeoutMillis ?? DEFAULT_PERSISTENCE_TIMEOUT_MILLIS;
+        this.#configuration = options.configuration;
+        this.#keyValueStore = options.keyValueStore ?? null;
         this.#log = options.logger ?? serviceLocator.getLogger().child({ prefix: 'RecoverableState' });
-        this.#serialize = options.serialize ?? JSON.stringify;
-        this.#deserialize = options.deserialize ?? JSON.parse;
-        this.persistState = this.persistState.bind(this);
+        this.#serialize = this.#toConversion(options.serialize);
+        this.#deserialize = this.#toConversion(options.deserialize);
+        // The automatic persists, where a rejection has nowhere useful to go - the event manager does not catch
+        // listener errors, and throwing from teardown would bury the outcome of the work it cleans up after.
+        this.#persistStateQuietly = async (eventData) => this.persistState(eventData).catch((error) => this.#log.warning(`Failed to persist the state under key '${this.#persistStateKey}'.`, { error }));
+    }
+    /** Normalizes a conversion option into a function. Absent conversions pass the value through unchanged. */
+    #toConversion(conversion) {
+        if (conversion === undefined) {
+            return async (value) => value;
+        }
+        if (typeof conversion === 'function') {
+            return async (value) => conversion(value);
+        }
+        return async (value) => {
+            const result = await conversion['~standard'].validate(value);
+            if (result.issues) {
+                throw new StateValidationError(this.#persistStateKey, result.issues);
+            }
+            return result.value;
+        };
     }
     /**
      * Initialize the recoverable state.
      *
-     * This method must be called before using the recoverable state. It loads the saved state
-     * if persistence is enabled and registers the object to listen for PERSIST_STATE events.
+     * If persistence is enabled, this method loads the saved state and registers the object to listen for
+     * PERSIST_STATE events. A state established beforehand by {@link RecoverableState.reset} survives if there
+     * is no record to restore.
+     *
+     * Calling this again after a {@link RecoverableState.teardown} starts a new persistence window - the
+     * listener is registered again and the record reloaded.
      *
      * @returns The loaded state object
      */
     async initialize() {
-        if (this.#state !== null && this.#state !== undefined) {
+        if (this.#initialized) {
             return this.currentValue;
         }
-        if (!this.#persistenceEnabled) {
-            this.#state = this.#deserialize(this.#serialize(this.#defaultState));
-            return this.currentValue;
-        }
-        let kvsIdentifier = null;
-        if (this.#persistStateKvsName) {
-            kvsIdentifier = { name: this.#persistStateKvsName };
-        }
-        else if (this.#persistStateKvsId) {
-            kvsIdentifier = { id: this.#persistStateKvsId };
+        if (this.#persistenceEnabled) {
+            this.#keyValueStore ??= KeyValueStore.open(null, {
+                configuration: this.#configuration ?? serviceLocator.getConfiguration(),
+            });
+            await this.#resolveKeyValueStore();
+            serviceLocator.getEventManager().on(EventType.PERSIST_STATE, this.#persistStateQuietly);
+            this.#listening = true;
         }
-        this.#keyValueStore = await KeyValueStore.open(kvsIdentifier, {
-            configuration: serviceLocator.getConfiguration(),
-        });
-        await this.loadSavedState();
-        // Register for persist state events
-        const eventManager = serviceLocator.getEventManager();
-        eventManager.on(EventType.PERSIST_STATE, this.persistState);
+        // Flipped before the record is loaded, so that a caller catching a `StateValidationError` is left with a
+        // fully wired object running on the default state rather than a half-initialized one.
+        this.#initialized = true;
+        this.#state ??= this.#defaultState();
+        await this.#loadSavedState();
         return this.currentValue;
     }
     /**
      * Clean up resources used by the recoverable state.
      *
      * If persistence is enabled, this method deregisters the object from PERSIST_STATE events
-     * and persists the current state one last time.
+     * and persists the current state one last time, warning rather than throwing if that write fails - cleanup
+     * runs when the work is already done, and failing it would bury whatever the caller was doing. The in-memory
+     * state is left alone, and {@link RecoverableState.initialize} can be called again to open a new
+     * persistence window.
      */
     async teardown() {
-        if (!this.#persistenceEnabled || !this.persistState) {
+        this.#initialized = false;
+        if (!this.#persistenceEnabled) {
             return;
         }
-        const eventManager = serviceLocator.getEventManager();
-        eventManager.off(EventType.PERSIST_STATE, this.persistState);
-        await this.persistState();
+        serviceLocator.getEventManager().off(EventType.PERSIST_STATE, this.#persistStateQuietly);
+        this.#listening = false;
+        await this.#persistStateQuietly();
     }
     /**
      * Get the current state.
+     *
+     * Throws until the state has been established, by either {@link RecoverableState.initialize} or the
+     * synchronous {@link RecoverableState.reset} - the latter being how a caller that cannot await in its
+     * constructor gets a usable state right away.
      */
     get currentValue() {
         if (this.#state === null) {
-            throw new Error('Recoverable state has not yet been loaded');
+            throw new Error('Recoverable state has not yet been loaded - call initialize() or reset() first');
         }
         return this.#state;
     }
     /**
-     * Reset the state to the default values and clear any persisted state.
+     * Reset the in-memory state to the default values, leaving any persisted record alone.
      *
-     * Resets the current state to the default state and, if persistence is enabled,
-     * clears the persisted state from the KeyValueStore.
+     * Use {@link RecoverableState.resetStore} to clear the persisted record as well.
      */
-    async reset() {
-        this.#state = this.#deserialize(this.#serialize(this.#defaultState));
-        if (this.#persistenceEnabled) {
-            if (this.#keyValueStore === null) {
-                throw new Error('Recoverable state has not yet been initialized');
-            }
-            await this.#keyValueStore.setValue(this.#persistStateKey, null);
+    reset() {
+        this.#state = this.#defaultState();
+    }
+    /**
+     * Clear the persisted state record, leaving the in-memory state alone.
+     *
+     * This is a between-lifecycles operation - its point is to stop the next {@link RecoverableState.initialize}
+     * from restoring the record, so it throws while PERSIST_STATE events are still being handled, where the next
+     * one would write the record straight back. Use {@link RecoverableState.reset} to reset the state itself,
+     * or {@link RecoverableState.teardown} before clearing the record.
+     *
+     * A no-op if persistence is disabled or no KeyValueStore is available yet.
+     */
+    async resetStore() {
+        if (this.#listening) {
+            throw new Error(`Cannot clear the state persisted under key '${this.#persistStateKey}' while it is still being persisted periodically - the next PERSIST_STATE event would write it straight back. Use reset() to reset the state itself, or teardown() before clearing the record.`);
+        }
+        if (!this.#persistenceEnabled) {
+            return;
+        }
+        const keyValueStore = await this.#resolveKeyValueStore();
+        if (keyValueStore === null) {
+            return;
         }
+        await this.#withTimeout(async () => keyValueStore.setValue(this.#persistStateKey, null), 'Clearing the persisted state');
     }
     /**
      * Persist the current state to the KeyValueStore.
      *
      * This method is typically called in response to a PERSIST_STATE event, but can also be called
-     * directly when needed.
+     * directly when needed. It is a no-op if persistence is disabled, if no KeyValueStore is available yet, or if
+     * there is no state to write. A failed write only rejects here - the periodic and teardown ones warn instead.
      *
      * @param eventData Optional data associated with a PERSIST_STATE event
      */
     async persistState(eventData) {
-        this.#log.debug(`Persisting state of the RecoverableState (eventData=${JSON.stringify(eventData)}).`);
-        if (this.#keyValueStore === null || this.#state === null) {
-            throw new Error('Recoverable state has not yet been initialized');
+        if (!this.#persistenceEnabled || this.#state === null) {
+            return;
         }
-        if (this.#persistenceEnabled) {
-            await this.#keyValueStore.setValue(this.#persistStateKey, this.#serialize(this.#state), {
-                contentType: 'text/plain', // HACK - the result is expected to be JSON, but we do this to avoid the implicit JSON.parse in `KeyValueStore.getValue`
-            });
+        const keyValueStore = await this.#resolveKeyValueStore();
+        if (keyValueStore === null) {
+            return;
         }
+        this.#log.debug(`Persisting state of the RecoverableState (eventData=${JSON.stringify(eventData)}).`);
+        const serializedState = await this.#serialize(this.currentValue);
+        await this.#withTimeout(async () => keyValueStore.setValue(this.#persistStateKey, serializedState), 'Persisting the state');
+    }
+    /** Awaits a store handed over as a pending `open()`, keeping the resolved instance for later calls. */
+    async #resolveKeyValueStore() {
+        if (this.#keyValueStore === null) {
+            return null;
+        }
+        this.#keyValueStore = await this.#keyValueStore;
+        return this.#keyValueStore;
     }
     /**
-     * Load the saved state from the KeyValueStore
+     * Load the saved state from the KeyValueStore. Leaves the current state alone if there is no record to load.
      */
-    async loadSavedState() {
-        if (this.#keyValueStore === null) {
-            throw new Error('Recoverable state has not yet been initialized');
+    async #loadSavedState() {
+        if (!this.#persistenceEnabled) {
+            return;
         }
-        const storedState = await this.#keyValueStore.getValue(this.#persistStateKey);
-        if (storedState === null || storedState === undefined) {
-            this.#state = this.#deserialize(this.#serialize(this.#defaultState));
+        const keyValueStore = await this.#resolveKeyValueStore();
+        if (keyValueStore === null) {
+            return;
         }
-        else {
-            this.#state = this.#deserialize(storedState);
+        const storedState = await this.#withTimeout(async () => keyValueStore.getValue(this.#persistStateKey), 'Loading the persisted state');
+        if (storedState === null || storedState === undefined) {
+            return;
         }
+        this.#state = await this.#deserialize(storedState);
+    }
+    async #withTimeout(operation, description) {
+        // `@apify/timeout` shares one `AbortController` across nested frames and `KeyValueStore` checks it on
+        // every operation, so a teardown-time persist running inside an already-expired request handler timeout
+        // would be aborted before it started. Hence a fresh timeout context.
+        return timeoutStorage.exit(async () => addTimeoutToPromise(operation, this.#persistenceTimeoutMillis, `${description} under key '${this.#persistStateKey}' timed out after ${this.#persistenceTimeoutMillis / 1000} seconds.`));
     }
 }

package/storages/throttling_request_manager.d.ts

@@ -66,7 +66,7 @@ export interface ThrottlingRequestManagerOptions<T extends IRequestManager = IRe
      *
      * A domain that keeps answering 429 for this long is not going to be crawled by waiting longer - the
      * concurrency is too high for it, or it has blocked us outright. Its requests are deliberately left in
-     * their queue, so re-running the crawl without purging storages picks them up once the domain recovers.
+     * their queue, so re-running the crawl with `purgeOnStart` disabled picks them up once the domain recovers.
      *
      * A crawler running with `keepAlive` is exempt - outliving a domain that will not let us through is the
      * whole point there.
@@ -119,9 +119,9 @@ export declare class ThrottlingRequestManager<T extends IRequestManager = IReque
     private readonly subManagers;
     private readonly log;
     /**
-     * Sub-managers are keyed by a stable alias, so they outlive the process. They must therefore be reopened
-     * for every configured domain rather than created on first insert - otherwise a restart sees an empty map,
-     * reports the crawl finished, and strands whatever the previous run left in them.
+     * Sub-managers are keyed by a stable alias, so with `purgeOnStart` disabled they outlive the process. They
+     * must therefore be reopened for every configured domain rather than created on first insert - otherwise a
+     * restart sees an empty map, reports the crawl finished, and strands whatever the previous run left in them.
      */
     private subManagersReady?;
     /** Batches still being added in the background; keeps {@link ThrottlingRequestManager.isFinished} honest. */

package/storages/throttling_request_manager.js

@@ -62,9 +62,9 @@ export class ThrottlingRequestManager {
     subManagers = new Map();
     log;
     /**
-     * Sub-managers are keyed by a stable alias, so they outlive the process. They must therefore be reopened
-     * for every configured domain rather than created on first insert - otherwise a restart sees an empty map,
-     * reports the crawl finished, and strands whatever the previous run left in them.
+     * Sub-managers are keyed by a stable alias, so with `purgeOnStart` disabled they outlive the process. They
+     * must therefore be reopened for every configured domain rather than created on first insert - otherwise a
+     * restart sees an empty map, reports the crawl finished, and strands whatever the previous run left in them.
      */
     subManagersReady;
     /** Batches still being added in the background; keeps {@link ThrottlingRequestManager.isFinished} honest. */

package/storages/utils.d.ts

@@ -14,7 +14,8 @@ interface PurgeDefaultStorageOptions {
 }
 /**
  * Cleans up the local storage folder (defaults to `./storage`) created when running code locally.
- * Purging will remove all the files in all storages except for INPUT.json in the default KV store.
+ * Purging empties the storages that belong to a single run — the default one and every alias-keyed one —
+ * keeping only INPUT.json in the default KV store. Named storages persist across runs and are not touched.
  *
  * Purging of storages is happening automatically when we run our crawler (or when we open some storage
  * explicitly, e.g. via `RequestList.open()`). We can disable that via `purgeOnStart` {@link Configuration}
@@ -28,7 +29,8 @@ interface PurgeDefaultStorageOptions {
 export declare function purgeDefaultStorages(options?: PurgeDefaultStorageOptions): Promise<void>;
 /**
  * Cleans up the local storage folder (defaults to `./storage`) created when running code locally.
- * Purging will remove all the files in all storages except for INPUT.json in the default KV store.
+ * Purging empties the storages that belong to a single run — the default one and every alias-keyed one —
+ * keeping only INPUT.json in the default KV store. Named storages persist across runs and are not touched.
  *
  * Purging of storages is happening automatically when we run our crawler (or when we open some storage
  * explicitly, e.g. via `RequestList.open()`). We can disable that via `purgeOnStart` {@link Configuration}