@crawlee/core 4.0.0-beta.18 → 4.0.0-beta.181

package/configuration.js

@@ -1,15 +1,80 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { MemoryStorage } from '@crawlee/memory-storage';
-import { pathExistsSync } from 'fs-extra/esm';
-import log, { LogLevel } from '@apify/log';
-import { LocalEventManager } from './events/local_event_manager.js';
-import { entries } from './typedefs.js';
+import { z } from 'zod';
+import { log, LogLevel } from './log.js';
+import { serviceLocator } from './service_locator.js';
+// Crawlee attaches many listeners to shared EventEmitters (one per crawler/session/autoscaled pool),
+// which can exceed Node's default limit of 10 and trigger spurious MaxListenersExceededWarning logs.
+// Raising the global default avoids false positives; real leaks will still manifest as unbounded growth.
+// TODO: tracked in https://github.com/apify/crawlee/issues/3615 — find a less side-effecting place for this.
+EventEmitter.defaultMaxListeners = 50;
+export function field(schema, envVar) {
+    return { schema, envVar };
+}
+// --- Zod preprocessors ---
+/** Zod preprocessor treating `'0'` and `'false'` as falsy. */
+export const coerceBoolean = z.preprocess((val) => {
+    if (typeof val === 'string') {
+        return !['0', 'false'].includes(val.toLowerCase());
+    }
+    return val;
+}, z.boolean());
+export const coerceNumber = z.preprocess((val) => {
+    if (typeof val === 'string')
+        return Number(val);
+    return val;
+}, z.number());
+/** Zod schema accepting both LogLevel enum values and string names (case-insensitive). */
+const logLevelSchema = z.preprocess((val) => {
+    if (val == null)
+        return val;
+    const s = String(val);
+    if (Number.isFinite(+s))
+        return +s;
+    const key = s.toUpperCase();
+    if (key in LogLevel)
+        return LogLevel[key];
+    return val;
+}, z.enum(LogLevel));
+// --- Crawlee config field definitions ---
+export const crawleeConfigFields = {
+    /** @default true */
+    purgeOnStart: field(coerceBoolean.default(true), 'CRAWLEE_PURGE_ON_START'),
+    /** @default 0.95 */
+    maxUsedCpuRatio: field(coerceNumber.default(0.95)),
+    /** @default 0.25 */
+    availableMemoryRatio: field(coerceNumber.default(0.25), 'CRAWLEE_AVAILABLE_MEMORY_RATIO'),
+    memoryMbytes: field(coerceNumber.optional(), 'CRAWLEE_MEMORY_MBYTES'),
+    /** @default 60_000 */
+    persistStateIntervalMillis: field(coerceNumber.default(60_000), 'CRAWLEE_PERSIST_STATE_INTERVAL_MILLIS'),
+    /**
+     * Internal safety-net timeout for a single request, in milliseconds. When unset the crawler derives it from
+     * the request handler timeout (twice it, and never below 5 minutes).
+     */
+    internalTimeoutMillis: field(coerceNumber.optional(), 'CRAWLEE_INTERNAL_TIMEOUT'),
+    /** @default 1_000 */
+    systemInfoIntervalMillis: field(coerceNumber.default(1_000)),
+    /** @default 'INPUT' */
+    inputKey: field(z.string().default('INPUT'), 'CRAWLEE_INPUT_KEY'),
+    /** @default true */
+    headless: field(coerceBoolean.default(true), 'CRAWLEE_HEADLESS'),
+    /** @default false */
+    xvfb: field(coerceBoolean.default(false), 'CRAWLEE_XVFB'),
+    chromeExecutablePath: field(z.string().optional(), 'CRAWLEE_CHROME_EXECUTABLE_PATH'),
+    defaultBrowserPath: field(z.string().optional(), 'CRAWLEE_DEFAULT_BROWSER_PATH'),
+    /** @default false */
+    disableBrowserSandbox: field(coerceBoolean.default(false), 'CRAWLEE_DISABLE_BROWSER_SANDBOX'),
+    logLevel: field(logLevelSchema.optional(), 'CRAWLEE_LOG_LEVEL'),
+    /** @default true */
+    persistStorage: field(coerceBoolean.default(true), 'CRAWLEE_PERSIST_STORAGE'),
+    /** @default './storage' */
+    storageDir: field(z.string().default('./storage'), 'CRAWLEE_STORAGE_DIR'),
+    containerized: field(coerceBoolean.optional(), 'CRAWLEE_CONTAINERIZED'),
+};
 /**
  * `Configuration` is a value object holding Crawlee configuration. By default, there is a
- * global singleton instance of this class available via `Configuration.getGlobalConfig()`.
+ * global singleton instance of this class available via `Configuration.getGlobalConfiguration()`.
  * Places that depend on a configurable behaviour depend on this class, as they have the global
  * instance as the default value.
  *
@@ -18,14 +83,10 @@ import { entries } from './typedefs.js';
  * import { BasicCrawler, Configuration } from 'crawlee';
  *
  * // Get the global configuration
- * const config = Configuration.getGlobalConfig();
- * // Set the 'persistStateIntervalMillis' option
- * // of global configuration to 10 seconds
- * config.set('persistStateIntervalMillis', 10_000);
- *
- * // No need to pass the configuration to the crawler,
- * // as it's using the global configuration by default
- * const crawler = new BasicCrawler();
+ * const config = Configuration.getGlobalConfiguration();
+ * // Access configuration values directly as properties
+ * console.log(config.headless);
+ * console.log(config.persistStateIntervalMillis);
  * ```
  *
  * *Using custom configuration:*
@@ -35,15 +96,14 @@ import { entries } from './typedefs.js';
  * // Create a new configuration
  * const config = new Configuration({ persistStateIntervalMillis: 30_000 });
  * // Pass the configuration to the crawler
- * const crawler = new BasicCrawler({ ... }, config);
+ * const crawler = new BasicCrawler({ configuration: config });
  * ```
  *
- * The configuration provided via environment variables always takes precedence. We can also
- * define the `crawlee.json` file in the project root directory which will serve as a baseline,
- * so the options provided in constructor will override those. In other words, the precedence is:
+ * Configuration is immutable — values are set via the constructor and cannot be changed afterwards.
+ * The priority order for resolving values is (highest to lowest):
  *
  * ```text
- * crawlee.json < constructor options < environment variables
+ * constructor options > environment variables > crawlee.json > schema defaults
  * ```
  *
  * ## Supported Configuration Options
@@ -53,250 +113,129 @@ import { entries } from './typedefs.js';
  * `memoryMbytes` | `CRAWLEE_MEMORY_MBYTES` | -
  * `logLevel` | `CRAWLEE_LOG_LEVEL` | -
  * `headless` | `CRAWLEE_HEADLESS` | `true`
- * `defaultDatasetId` | `CRAWLEE_DEFAULT_DATASET_ID` | `'default'`
- * `defaultKeyValueStoreId` | `CRAWLEE_DEFAULT_KEY_VALUE_STORE_ID` | `'default'`
- * `defaultRequestQueueId` | `CRAWLEE_DEFAULT_REQUEST_QUEUE_ID` | `'default'`
  * `persistStateIntervalMillis` | `CRAWLEE_PERSIST_STATE_INTERVAL_MILLIS` | `60_000`
+ * `internalTimeoutMillis` | `CRAWLEE_INTERNAL_TIMEOUT` | -
  * `purgeOnStart` | `CRAWLEE_PURGE_ON_START` | `true`
  * `persistStorage` | `CRAWLEE_PERSIST_STORAGE` | `true`
+ * `storageDir` | `CRAWLEE_STORAGE_DIR` | `'./storage'`
  *
  * ## Advanced Configuration Options
  *
  * Key | Environment Variable | Default Value
  * ---|---|---
  * `inputKey` | `CRAWLEE_INPUT_KEY` | `'INPUT'`
- * `xvfb` | `CRAWLEE_XVFB` | -
+ * `xvfb` | `CRAWLEE_XVFB` | `false`
  * `chromeExecutablePath` | `CRAWLEE_CHROME_EXECUTABLE_PATH` | -
  * `defaultBrowserPath` | `CRAWLEE_DEFAULT_BROWSER_PATH` | -
  * `disableBrowserSandbox` | `CRAWLEE_DISABLE_BROWSER_SANDBOX` | -
  * `availableMemoryRatio` | `CRAWLEE_AVAILABLE_MEMORY_RATIO` | `0.25`
- * `containerized | `CRAWLEE_CONTAINERIZED | -
+ * `containerized` | `CRAWLEE_CONTAINERIZED` | -
  */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Configuration {
     /**
-     * Maps environment variables to config keys (e.g. `CRAWLEE_MEMORY_MBYTES` to `memoryMbytes`)
-     */
-    static ENV_MAP = {
-        CRAWLEE_AVAILABLE_MEMORY_RATIO: 'availableMemoryRatio',
-        CRAWLEE_PURGE_ON_START: 'purgeOnStart',
-        CRAWLEE_MEMORY_MBYTES: 'memoryMbytes',
-        CRAWLEE_DEFAULT_DATASET_ID: 'defaultDatasetId',
-        CRAWLEE_DEFAULT_KEY_VALUE_STORE_ID: 'defaultKeyValueStoreId',
-        CRAWLEE_DEFAULT_REQUEST_QUEUE_ID: 'defaultRequestQueueId',
-        CRAWLEE_INPUT_KEY: 'inputKey',
-        CRAWLEE_PERSIST_STATE_INTERVAL_MILLIS: 'persistStateIntervalMillis',
-        CRAWLEE_HEADLESS: 'headless',
-        CRAWLEE_XVFB: 'xvfb',
-        CRAWLEE_CHROME_EXECUTABLE_PATH: 'chromeExecutablePath',
-        CRAWLEE_DEFAULT_BROWSER_PATH: 'defaultBrowserPath',
-        CRAWLEE_DISABLE_BROWSER_SANDBOX: 'disableBrowserSandbox',
-        CRAWLEE_LOG_LEVEL: 'logLevel',
-        CRAWLEE_PERSIST_STORAGE: 'persistStorage',
-        CRAWLEE_CONTAINERIZED: 'containerized',
-    };
-    static BOOLEAN_VARS = [
-        'purgeOnStart',
-        'headless',
-        'xvfb',
-        'disableBrowserSandbox',
-        'persistStorage',
-        'containerized',
-    ];
-    static INTEGER_VARS = ['memoryMbytes', 'persistStateIntervalMillis', 'systemInfoIntervalMillis'];
-    static COMMA_SEPARATED_LIST_VARS = [];
-    static DEFAULTS = {
-        defaultKeyValueStoreId: 'default',
-        defaultDatasetId: 'default',
-        defaultRequestQueueId: 'default',
-        inputKey: 'INPUT',
-        maxUsedCpuRatio: 0.95,
-        availableMemoryRatio: 0.25,
-        storageClientOptions: {},
-        purgeOnStart: true,
-        headless: true,
-        persistStateIntervalMillis: 60_000,
-        systemInfoIntervalMillis: 1_000,
-        persistStorage: true,
-    };
-    /**
-     * Provides access to the current-instance-scoped Configuration without passing it around in parameters.
-     * @internal
+     * Field definitions for this configuration class.
+     * Subclasses override this to register additional fields.
      */
-    static storage = new AsyncLocalStorage();
-    options;
-    services = new Map();
-    /** @internal */
-    static globalConfig;
-    storageManagers = new Map();
+    static fields = crawleeConfigFields;
+    #resolvedValues;
     /**
-     * Creates new `Configuration` instance with provided options. Env vars will have precedence over those.
+     * Creates new `Configuration` instance with provided options.
+     * Constructor options take precedence over environment variables, which take precedence
+     * over crawlee.json values, which take precedence over schema defaults.
      */
     constructor(options = {}) {
-        this.buildOptions(options);
-        // Increase the global limit for event emitter memory leak warnings.
-        EventEmitter.defaultMaxListeners = 50;
-        // set the log level to support CRAWLEE_ prefixed env var too
-        const logLevel = this.get('logLevel');
-        if (logLevel) {
-            const level = Number.isFinite(+logLevel)
-                ? +logLevel
-                : LogLevel[String(logLevel).toUpperCase()];
-            log.setLevel(level);
-        }
-    }
-    /**
-     * Returns configured value. First checks the environment variables, then provided configuration,
-     * fallbacks to the `defaultValue` argument if provided, otherwise uses the default value as described
-     * in the above section.
-     */
-    get(key, defaultValue) {
-        // prefer env vars, always iterate through the whole map as there might be duplicate env vars for the same option
-        let envValue;
-        for (const [k, v] of entries(Configuration.ENV_MAP)) {
-            if (key === v) {
-                envValue = process.env[k];
-                if (envValue) {
-                    break;
-                }
-            }
+        const fields = this.constructor.fields;
+        const fileOptions = Configuration.loadFileOptions();
+        this.#resolvedValues = Configuration.resolveAll(fields, options, fileOptions);
+        this.registerAccessors();
+        // Set the log level
+        const logLevel = this.logLevel;
+        if (logLevel != null) {
+            log.setLevel(logLevel);
         }
-        if (envValue != null) {
-            return this._castEnvValue(key, envValue);
-        }
-        // check instance level options
-        if (this.options.has(key)) {
-            return this.options.get(key);
-        }
-        // fallback to defaults
-        return (defaultValue ?? Configuration.DEFAULTS[key] ?? envValue);
-    }
-    _castEnvValue(key, value) {
-        if (Configuration.INTEGER_VARS.includes(key)) {
-            return +value;
-        }
-        if (Configuration.BOOLEAN_VARS.includes(key)) {
-            // 0, false and empty string are considered falsy values
-            return !['0', 'false', ''].includes(String(value).toLowerCase());
-        }
-        if (Configuration.COMMA_SEPARATED_LIST_VARS.includes(key)) {
-            if (!value)
-                return [];
-            return String(value)
-                .split(',')
-                .map((v) => v.trim());
-        }
-        return value;
     }
     /**
-     * Sets value for given option. Only affects this `Configuration` instance, the value will not be propagated down to the env var.
-     * To reset a value, we can omit the `value` argument or pass `undefined` there.
-     */
-    set(key, value) {
-        this.options.set(key, value);
-    }
-    /**
-     * Sets value for given option. Only affects the global `Configuration` instance, the value will not be propagated down to the env var.
-     * To reset a value, we can omit the `value` argument or pass `undefined` there.
-     */
-    static set(key, value) {
-        this.getGlobalConfig().set(key, value);
-    }
-    /**
-     * Returns cached instance of {@link StorageClient} using options as defined in the environment variables or in
-     * this {@link Configuration} instance. Only first call of this method will create the client, following calls will
-     * return the same client instance.
+     * Returns the global configuration instance. It will respect the environment variables.
      *
-     * Caching works based on the `storageClientOptions`, so calling this method with different options will return
-     * multiple instances, one for each variant of the options.
-     * @internal
+     * Delegates to the global ServiceLocator, making it the single source of truth for service management.
      */
-    getStorageClient() {
-        if (this.options.has('storageClient')) {
-            return this.options.get('storageClient');
-        }
-        const options = this.options.get('storageClientOptions');
-        return this.createMemoryStorage(options);
-    }
-    getEventManager() {
-        if (this.options.has('eventManager')) {
-            return this.options.get('eventManager');
-        }
-        if (this.services.has('eventManager')) {
-            return this.services.get('eventManager');
-        }
-        const eventManager = new LocalEventManager(this);
-        this.services.set('eventManager', eventManager);
-        return eventManager;
+    static getGlobalConfiguration() {
+        return serviceLocator.getConfiguration();
     }
     /**
-     * Creates an instance of MemoryStorage using options as defined in the environment variables or in this `Configuration` instance.
-     * @internal
+     * Resolves all field values once using the priority chain:
+     * constructor options > env vars > crawlee.json > schema defaults.
      */
-    createMemoryStorage(options = {}) {
-        const cacheKey = `MemoryStorage-${JSON.stringify(options)}`;
-        if (this.services.has(cacheKey)) {
-            return this.services.get(cacheKey);
+    static resolveAll(fields, userOptions, fileOptions) {
+        const values = {};
+        for (const [key, fieldDef] of Object.entries(fields)) {
+            // 1. Constructor options (highest priority)
+            if (key in userOptions && userOptions[key] !== undefined) {
+                values[key] = fieldDef.schema.parse(userOptions[key]);
+                continue;
+            }
+            // 2. Environment variables
+            const envValue = Configuration.readEnvVar(fieldDef);
+            if (envValue != null) {
+                values[key] = fieldDef.schema.parse(envValue);
+                continue;
+            }
+            // 3. crawlee.json file options
+            if (key in fileOptions && fileOptions[key] !== undefined) {
+                values[key] = fieldDef.schema.parse(fileOptions[key]);
+                continue;
+            }
+            // 4. Schema default (by parsing undefined through the schema)
+            const parsed = fieldDef.schema.safeParse(undefined);
+            values[key] = parsed.success ? parsed.data : undefined;
         }
-        const storage = new MemoryStorage({
-            persistStorage: this.get('persistStorage'),
-            // Override persistStorage if user provides it via storageClientOptions
-            ...options,
-        });
-        this.services.set(cacheKey, storage);
-        return storage;
-    }
-    useStorageClient(client) {
-        this.options.set('storageClient', client);
-    }
-    static useStorageClient(client) {
-        this.getGlobalConfig().useStorageClient(client);
-    }
-    useEventManager(events) {
-        this.options.set('eventManager', events);
+        return values;
     }
     /**
-     * Returns the global configuration instance. It will respect the environment variables.
+     * Registers getters (and throwing setters) on the instance for each field.
      */
-    static getGlobalConfig() {
-        if (Configuration.storage.getStore()) {
-            return Configuration.storage.getStore();
+    registerAccessors() {
+        const fields = this.constructor.fields;
+        const descriptors = {};
+        for (const key of Object.keys(fields)) {
+            descriptors[key] = {
+                get: () => this.#resolvedValues[key],
+                set() {
+                    throw new TypeError('Configuration is immutable. Pass options via the constructor instead.');
+                },
+                enumerable: true,
+                configurable: false,
+            };
         }
-        Configuration.globalConfig ??= new Configuration();
-        return Configuration.globalConfig;
-    }
-    /**
-     * Gets default {@link StorageClient} instance.
-     */
-    static getStorageClient() {
-        return this.getGlobalConfig().getStorageClient();
+        Object.defineProperties(this, descriptors);
     }
     /**
-     * Gets default {@link EventManager} instance.
+     * Reads the first defined env var value for a field definition.
+     * Empty strings are treated as unset, falling through to crawlee.json or schema defaults.
+     * (Crawlee v3 coerced `''` to `false`/`0`/`''` per type — v4 drops that for consistency.)
      */
-    static getEventManager() {
-        return this.getGlobalConfig().getEventManager();
+    static readEnvVar(fieldDef) {
+        if (!fieldDef.envVar)
+            return undefined;
+        const envVars = Array.isArray(fieldDef.envVar) ? fieldDef.envVar : [fieldDef.envVar];
+        for (const envVar of envVars) {
+            const value = process.env[envVar];
+            if (value != null && value !== '')
+                return value;
+        }
+        return undefined;
     }
     /**
-     * Resets global configuration instance. The default instance holds configuration based on env vars,
-     * if we want to change them, we need to first reset the global state. Used mainly for testing purposes.
+     * Loads config options from crawlee.json in the current working directory.
      */
-    static resetGlobalState() {
-        delete this.globalConfig;
-    }
-    buildOptions(options) {
-        // try to load configuration from crawlee.json as the baseline
-        const path = join(process.cwd(), 'crawlee.json');
-        if (pathExistsSync(path)) {
-            try {
-                const file = readFileSync(path);
-                const optionsFromFileConfig = JSON.parse(file.toString());
-                Object.assign(options, optionsFromFileConfig);
-            }
-            catch {
-                // ignore
-            }
+    static loadFileOptions() {
+        try {
+            const file = readFileSync(join(process.cwd(), 'crawlee.json'));
+            return JSON.parse(file.toString());
+        }
+        catch {
+            return {};
         }
-        this.options = new Map(entries(options));
     }
 }
-//# sourceMappingURL=configuration.js.map

package/debug.d.ts

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

package/debug.js

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

package/errors.d.ts

@@ -10,36 +10,57 @@ export declare class NonRetryableError extends Error {
 export declare class CriticalError extends NonRetryableError {
 }
 /**
- * @ignore
+ * 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 declare class MissingRouteError extends CriticalError {
+export interface SchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        key: PropertyKey;
+    })[];
 }
 /**
- * Errors of `RetryRequestError` type will always be retried by the crawler.
+ * Thrown when a request's `userData` does not match the {@link RouteSchemas|Standard Schema} registered for its label.
  *
- * *This error overrides the `maxRequestRetries` option, i.e. the request can be retried indefinitely until it succeeds.*
+ * As the `userData` does not change between attempts, this error is non-retryable.
  */
-export declare class RetryRequestError extends Error {
-    constructor(message?: string);
+export declare class RequestValidationError extends NonRetryableError {
+    readonly label: string | symbol;
+    readonly issues: readonly SchemaIssue[];
+    constructor(label: string | symbol, issues: readonly SchemaIssue[]);
 }
 /**
- * Errors of `SessionError` type will trigger a session rotation.
+ * Thrown by {@link RecoverableState} when a persisted state record does not match its `stateSchema`.
  *
- * This error doesn't respect the `maxRequestRetries` option and has a separate limit of `maxSessionRotations`.
+ * 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 SessionError extends RetryRequestError {
-    constructor(message?: string);
+export declare class StateValidationError extends Error {
+    readonly persistStateKey: string;
+    readonly issues: readonly SchemaIssue[];
+    constructor(persistStateKey: string, issues: readonly SchemaIssue[]);
 }
-export declare class ContextPipelineInterruptedError extends Error {
+/**
+ * Errors of `SessionError` type retire the session associated with the request and trigger a regular retry.
+ *
+ * The retry counts towards the `maxRequestRetries` limit, just like any other error.
+ */
+export declare class SessionError extends Error {
     constructor(message?: string);
 }
-export declare class ContextPipelineInitializationError extends Error {
-    constructor(error: unknown, options?: ErrorOptions);
-}
-export declare class ContextPipelineCleanupError extends CriticalError {
-    constructor(error: unknown, options?: ErrorOptions);
+/**
+ * Wraps the failure of a callback registered with {@link StorageTransaction.afterCommit|`afterCommit`}
+ * that ran after the request's writes had already been committed.
+ *
+ * Non-retryable by nature: the writes are durable, so re-running the request handler would duplicate
+ * them. A callback that throws a `NonRetryableError` of its own is left alone.
+ */
+export declare class AfterCommitError extends NonRetryableError {
+    constructor(cause: unknown);
 }
-export declare class RequestHandlerError extends Error {
-    constructor(error: unknown, options?: ErrorOptions);
+/**
+ * Thrown when attempting to set a different service instance after one has already been retrieved.
+ */
+export declare class ServiceConflictError extends Error {
+    constructor(serviceName: string, newValue: unknown, existingValue: unknown);
 }
-//# sourceMappingURL=errors.d.ts.map