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

package/autoscaling/cpu_load_signal.d.ts

@@ -12,7 +12,7 @@ export interface CpuSnapshot extends LoadSnapshot {
 export interface CpuLoadSignalOptions {
     overloadedRatio?: number;
     snapshotHistoryMillis?: number;
-    config: Configuration;
+    configuration: Configuration;
 }
 /**
  * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when

package/autoscaling/memory_load_signal.d.ts

@@ -9,7 +9,7 @@ export interface MemoryLoadSignalOptions {
     maxUsedMemoryRatio?: number;
     overloadedRatio?: number;
     snapshotHistoryMillis?: number;
-    config: Configuration;
+    configuration: Configuration;
     log?: CrawleeLogger;
 }
 /**
@@ -20,7 +20,7 @@ export declare class MemoryLoadSignal implements LoadSignal {
     readonly name = "memInfo";
     readonly overloadedRatio: number;
     private readonly store;
-    private readonly config;
+    private readonly configuration;
     private readonly events;
     private readonly log;
     private readonly maxUsedMemoryRatio;

package/autoscaling/memory_load_signal.js

@@ -12,7 +12,7 @@ export class MemoryLoadSignal {
     name = 'memInfo';
     overloadedRatio;
     store;
-    config;
+    configuration;
     events;
     log;
     maxUsedMemoryRatio;
@@ -21,7 +21,7 @@ export class MemoryLoadSignal {
     lastLoggedCriticalMemoryOverloadAt = null;
     constructor(options) {
         this.store = new SnapshotStore(options.snapshotHistoryMillis);
-        this.config = options.config;
+        this.configuration = options.configuration;
         this.events = serviceLocator.getEventManager();
         this.log = options.log ?? serviceLocator.getLogger().child({ prefix: 'MemoryLoadSignal' });
         this.maxUsedMemoryRatio = options.maxUsedMemoryRatio ?? 0.9;
@@ -29,12 +29,12 @@ export class MemoryLoadSignal {
         this._onSystemInfo = this._onSystemInfo.bind(this);
     }
     async start() {
-        const memoryMbytes = this.config.memoryMbytes ?? 0;
+        const memoryMbytes = this.configuration.memoryMbytes ?? 0;
         if (memoryMbytes > 0) {
             this.maxMemoryBytes = memoryMbytes * 1024 * 1024;
         }
         else {
-            this.maxMemoryRatio = this.config.availableMemoryRatio;
+            this.maxMemoryRatio = this.configuration.availableMemoryRatio;
             if (!this.maxMemoryRatio) {
                 throw new Error('availableMemoryRatio is not set in configuration.');
             }
@@ -96,7 +96,7 @@ export class MemoryLoadSignal {
         }
     }
     async _getTotalMemoryBytes() {
-        const containerized = this.config.containerized ?? (await isContainerized());
+        const containerized = this.configuration.containerized ?? (await isContainerized());
         return (await getMemoryInfo({ containerized, logger: serviceLocator.getLogger() })).totalBytes;
     }
 }

package/autoscaling/snapshotter.d.ts

@@ -47,7 +47,7 @@ export interface SnapshotterOptions {
     /** @internal */
     client?: StorageBackend;
     /** @internal */
-    config?: Configuration;
+    configuration?: Configuration;
 }
 /**
  * Creates snapshots of system resources at given intervals and marks the resource
@@ -78,7 +78,7 @@ export interface SnapshotterOptions {
 export declare class Snapshotter {
     readonly log: CrawleeLogger;
     readonly client: StorageBackend;
-    readonly config: Configuration;
+    readonly configuration: Configuration;
     private readonly memorySignal;
     private readonly eventLoopSignal;
     private readonly cpuSignal;

package/autoscaling/snapshotter.js

@@ -33,7 +33,7 @@ import { MemoryLoadSignal } from './memory_load_signal.js';
 export class Snapshotter {
     log;
     client;
-    config;
+    configuration;
     memorySignal;
     eventLoopSignal;
     cpuSignal;
@@ -71,17 +71,17 @@ export class Snapshotter {
             maxClientErrors: ow.optional.number,
             log: ow.optional.object,
             client: ow.optional.object,
-            config: ow.optional.object,
+            configuration: ow.optional.object,
         }));
-        const { eventLoopSnapshotIntervalSecs = 0.5, clientSnapshotIntervalSecs = 1, snapshotHistorySecs = 30, maxBlockedMillis = 50, maxUsedMemoryRatio = 0.9, maxClientErrors = 3, log = serviceLocator.getLogger(), config = serviceLocator.getConfiguration(), client = serviceLocator.getStorageBackend(), } = options;
+        const { eventLoopSnapshotIntervalSecs = 0.5, clientSnapshotIntervalSecs = 1, snapshotHistorySecs = 30, maxBlockedMillis = 50, maxUsedMemoryRatio = 0.9, maxClientErrors = 3, log = serviceLocator.getLogger(), configuration = serviceLocator.getConfiguration(), client = serviceLocator.getStorageBackend(), } = options;
         this.log = log.child({ prefix: 'Snapshotter' });
         this.client = client;
-        this.config = config;
+        this.configuration = configuration;
         const snapshotHistoryMillis = snapshotHistorySecs * 1000;
         this.memorySignal = new MemoryLoadSignal({
             maxUsedMemoryRatio,
             snapshotHistoryMillis,
-            config: this.config,
+            configuration: this.configuration,
             log: this.log,
         });
         this.eventLoopSignal = createEventLoopLoadSignal({
@@ -91,7 +91,7 @@ export class Snapshotter {
         });
         this.cpuSignal = createCpuLoadSignal({
             snapshotHistoryMillis,
-            config: this.config,
+            configuration: this.configuration,
         });
         this.clientSignal = createClientLoadSignal({
             client: this.client,

package/configuration.d.ts

@@ -57,7 +57,7 @@ export interface Configuration extends ResolvedConfigValues {
 }
 /**
  * `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.
  *
@@ -66,7 +66,7 @@ export interface Configuration extends ResolvedConfigValues {
  * import { BasicCrawler, Configuration } from 'crawlee';
  *
  * // Get the global configuration
- * const config = Configuration.getGlobalConfig();
+ * const config = Configuration.getGlobalConfiguration();
  * // Access configuration values directly as properties
  * console.log(config.headless);
  * console.log(config.persistStateIntervalMillis);
@@ -134,7 +134,7 @@ export declare class Configuration {
      *
      * Delegates to the global ServiceLocator, making it the single source of truth for service management.
      */
-    static getGlobalConfig(): Configuration;
+    static getGlobalConfiguration(): Configuration;
     /**
      * Resolves all field values once using the priority chain:
      * constructor options > env vars > crawlee.json > schema defaults.

package/configuration.js

@@ -75,7 +75,7 @@ export const crawleeConfigFields = {
 };
 /**
  * `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.
  *
@@ -84,7 +84,7 @@ export const crawleeConfigFields = {
  * import { BasicCrawler, Configuration } from 'crawlee';
  *
  * // Get the global configuration
- * const config = Configuration.getGlobalConfig();
+ * const config = Configuration.getGlobalConfiguration();
  * // Access configuration values directly as properties
  * console.log(config.headless);
  * console.log(config.persistStateIntervalMillis);
@@ -163,7 +163,7 @@ export class Configuration {
      *
      * Delegates to the global ServiceLocator, making it the single source of truth for service management.
      */
-    static getGlobalConfig() {
+    static getGlobalConfiguration() {
         return serviceLocator.getConfiguration();
     }
     /**

package/crawlers/crawler_commons.d.ts

@@ -3,13 +3,65 @@ import type { ReadonlyDeep, SetRequired } from 'type-fest';
 import type { Configuration } from '../configuration.js';
 import type { EnqueueLinksOptions } from '../enqueue_links/enqueue_links.js';
 import type { CrawleeLogger } from '../log.js';
-import type { Request, Source } from '../request.js';
+import type { Request, RequestOptions, Source } from '../request.js';
 import type { Dataset } from '../storages/dataset.js';
 import { KeyValueStore, type RecordOptions } from '../storages/key_value_store.js';
 import type { RequestQueueOperationOptions } from '../storages/request_queue.js';
 import type { StorageIdentifier } from '../storages/storage_instance_manager.js';
 /** @internal */
 export type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * A request input (URL string, request-options object, or {@link Request}) whose `userData` is typed
+ * according to its `label`, based on a router's route map.
+ *
+ * When the route map is open (the default `Record<string, ...>`), this is just the regular loose
+ * {@link Source} input. When the map declares concrete labels, providing a `label` requires the matching
+ * `userData` shape and rejects labels not present in the map; unlabeled requests keep loose `userData`.
+ * @internal
+ */
+export type LabeledSource<Routes extends Record<keyof Routes, Dictionary>> = string extends keyof Routes ? string | Source : string | Request | ({
+    requestsFromUrl?: string;
+    regex?: RegExp;
+} & ({
+    [Label in keyof Routes & string]: Omit<Partial<RequestOptions<Routes[Label]>>, 'label'> & {
+        label: Label;
+    };
+}[keyof Routes & string] | (Omit<Partial<RequestOptions>, 'label'> & {
+    label?: undefined;
+})));
+/**
+ * The iterable/array of {@link LabeledSource} inputs accepted by the label-aware `addRequests`/`run`
+ * methods of a crawler bound to a typed router.
+ * @internal
+ */
+export type TypedRequestsLike<Routes extends Record<keyof Routes, Dictionary>> = AsyncIterable<LabeledSource<Routes>> | Iterable<LabeledSource<Routes>> | LabeledSource<Routes>[];
+/**
+ * The label-aware `addRequests` method signature exposed on a request handler's context when the crawler is
+ * bound to a typed router. Mirrors {@link RestrictedCrawlingContext.addRequests} with typed sources.
+ * @internal
+ */
+export type TypedContextAddRequests<Routes extends Record<keyof Routes, Dictionary>> = (requestsLike: ReadonlyDeep<LabeledSource<Routes>[]>, options?: ReadonlyDeep<RequestQueueOperationOptions>) => Promise<void>;
+/**
+ * An `enqueueLinks`-options object with its `label`/`userData` retyped according to a router's route map: a
+ * declared `label` requires the matching `userData` shape (unknown labels are rejected), while unlabeled
+ * calls keep loose `userData`. Returns the options unchanged when the route map is open (the default).
+ */
+type TypedEnqueueLinksOptions<Options, Routes extends Record<keyof Routes, Dictionary>> = string extends keyof Routes ? Options : Omit<Options, 'label' | 'userData'> & ({
+    [Label in keyof Routes & string]: {
+        label: Label;
+        userData?: Routes[Label];
+    };
+}[keyof Routes & string] | {
+    label?: undefined;
+    userData?: Dictionary;
+});
+/**
+ * Transforms a context's existing `enqueueLinks` method so that the `label`/`userData` in its options follow
+ * the router's route map, while preserving everything else about the signature (argument optionality and
+ * return type, which differ between crawler types).
+ * @internal
+ */
+export type TypedContextEnqueueLinks<EnqueueLinks, Routes extends Record<keyof Routes, Dictionary>> = EnqueueLinks extends (options?: infer Options) => infer Result ? (options?: TypedEnqueueLinksOptions<Options, Routes>) => Result : EnqueueLinks extends (options: infer Options) => infer Result ? (options: TypedEnqueueLinksOptions<Options, Routes>) => Result : EnqueueLinks;
 /** @internal */
 export type WithRequired<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
@@ -139,12 +191,12 @@ export interface CrawlingContext<UserData extends Dictionary = Dictionary> exten
  * @experimental
  */
 export declare class RequestHandlerResult {
-    private config;
+    private configuration;
     private crawleeStateKey;
     private _keyValueStoreChanges;
     private pushDataCalls;
     private addRequestsCalls;
-    constructor(config: Configuration, crawleeStateKey: string);
+    constructor(configuration: Configuration, crawleeStateKey: string);
     /**
      * A record of calls to {@link RestrictedCrawlingContext.pushData}, {@link RestrictedCrawlingContext.addRequests}, {@link RestrictedCrawlingContext.enqueueLinks} made by a request handler.
      */
@@ -187,3 +239,4 @@ export declare class RequestHandlerResult {
     private getKeyValueStoreChangedValue;
     private setKeyValueStoreChangedValue;
 }
+export {};

package/crawlers/crawler_commons.js

@@ -5,13 +5,13 @@ import { KeyValueStore } from '../storages/key_value_store.js';
  * @experimental
  */
 export class RequestHandlerResult {
-    config;
+    configuration;
     crawleeStateKey;
     _keyValueStoreChanges = {};
     pushDataCalls = [];
     addRequestsCalls = [];
-    constructor(config, crawleeStateKey) {
-        this.config = config;
+    constructor(configuration, crawleeStateKey) {
+        this.configuration = configuration;
         this.crawleeStateKey = crawleeStateKey;
     }
     /**
@@ -81,10 +81,10 @@ export class RequestHandlerResult {
         return await store.getAutoSavedValue(this.crawleeStateKey, defaultValue);
     };
     getKeyValueStore = async (identifier) => {
-        const store = await KeyValueStore.open(identifier, { config: this.config });
+        const store = await KeyValueStore.open(identifier, { configuration: this.configuration });
         const storeId = store.id;
         return {
-            id: storeId ?? this.config.defaultKeyValueStoreId,
+            id: storeId ?? this.configuration.defaultKeyValueStoreId,
             name: store.name,
             getValue: async (key) => this.getKeyValueStoreChangedValue(storeId, key) ?? (await store.getValue(key)),
             setValue: async (key, value, options) => {
@@ -95,12 +95,12 @@ export class RequestHandlerResult {
         };
     };
     getKeyValueStoreChangedValue = (storeKey, key) => {
-        const id = storeKey ?? this.config.defaultKeyValueStoreId;
+        const id = storeKey ?? this.configuration.defaultKeyValueStoreId;
         this._keyValueStoreChanges[id] ??= {};
         return this.keyValueStoreChanges[id][key]?.changedValue ?? null;
     };
     setKeyValueStoreChangedValue = (storeKey, key, changedValue, options) => {
-        const id = storeKey ?? this.config.defaultKeyValueStoreId;
+        const id = storeKey ?? this.configuration.defaultKeyValueStoreId;
         this._keyValueStoreChanges[id] ??= {};
         this._keyValueStoreChanges[id][key] = { changedValue, options };
     };

package/crawlers/statistics.js

@@ -225,7 +225,7 @@ export class Statistics {
      * displaying the current state in predefined intervals
      */
     async startCapturing() {
-        this.keyValueStore ??= await KeyValueStore.open(null, { config: serviceLocator.getConfiguration() });
+        this.keyValueStore ??= await KeyValueStore.open(null, { configuration: serviceLocator.getConfiguration() });
         if (this.state.crawlerStartedAt === null) {
             this.state.crawlerStartedAt = new Date();
         }

package/events/local_event_manager.d.ts

@@ -11,7 +11,7 @@ export declare class LocalEventManager extends EventManager {
      * Creates a new `LocalEventManager` based on the provided `Configuration`.
      * Uses the global configuration from the service locator if none is provided.
      */
-    static fromConfig(config?: Configuration): LocalEventManager;
+    static fromConfiguration(configuration?: Configuration): LocalEventManager;
     /**
      * Initializes the EventManager and sets up periodic `systemInfo` events.
      * This is automatically called at the beginning of `crawler.run()`.

package/events/local_event_manager.js

@@ -11,11 +11,11 @@ export class LocalEventManager extends EventManager {
      * Creates a new `LocalEventManager` based on the provided `Configuration`.
      * Uses the global configuration from the service locator if none is provided.
      */
-    static fromConfig(config) {
-        const resolvedConfig = config ?? serviceLocator.getConfiguration();
+    static fromConfiguration(configuration) {
+        const resolvedConfiguration = configuration ?? serviceLocator.getConfiguration();
         return new LocalEventManager({
-            persistStateIntervalMillis: resolvedConfig.persistStateIntervalMillis,
-            systemInfoIntervalMillis: resolvedConfig.systemInfoIntervalMillis,
+            persistStateIntervalMillis: resolvedConfiguration.persistStateIntervalMillis,
+            systemInfoIntervalMillis: resolvedConfiguration.systemInfoIntervalMillis,
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/core",
-    "version": "4.0.0-beta.85",
+    "version": "4.0.0-beta.87",
     "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"
@@ -53,9 +53,9 @@
         "@apify/pseudo_url": "^2.0.59",
         "@apify/timeout": "^0.3.2",
         "@apify/utilities": "^2.15.5",
-        "@crawlee/fs-storage": "4.0.0-beta.85",
-        "@crawlee/types": "4.0.0-beta.85",
-        "@crawlee/utils": "4.0.0-beta.85",
+        "@crawlee/fs-storage": "4.0.0-beta.87",
+        "@crawlee/types": "4.0.0-beta.87",
+        "@crawlee/utils": "4.0.0-beta.87",
         "@sapphire/async-queue": "^1.5.5",
         "@sapphire/shapeshift": "^4.0.0",
         "@vladfrangu/async_event_emitter": "^2.4.6",
@@ -79,5 +79,5 @@
             }
         }
     },
-    "gitHead": "8d6d3cd9da3dc9cb0b7822b28eb317019b6806bc"
+    "gitHead": "1b7604cd77b694460aac4448b4555444fa1b2bdb"
 }

package/recoverable_state.d.ts

@@ -35,7 +35,7 @@ export interface RecoverableStateOptions<TStateModel = Record<string, unknown>>
     /**
      * Configuration instance to use
      */
-    config?: Configuration;
+    configuration?: Configuration;
     /**
      * Optional function to transform the state to a JSON string before persistence.
      * If not provided, JSON.stringify will be used.

package/recoverable_state.js

@@ -59,7 +59,9 @@ export class RecoverableState {
         else if (this.persistStateKvsId) {
             kvsIdentifier = { id: this.persistStateKvsId };
         }
-        this.keyValueStore = await KeyValueStore.open(kvsIdentifier, { config: serviceLocator.getConfiguration() });
+        this.keyValueStore = await KeyValueStore.open(kvsIdentifier, {
+            configuration: serviceLocator.getConfiguration(),
+        });
         await this.loadSavedState();
         // Register for persist state events
         const eventManager = serviceLocator.getEventManager();

package/router.d.ts

@@ -1,6 +1,6 @@
 import type { Dictionary } from '@crawlee/types';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { CrawlingContext, LoadedRequest, RestrictedCrawlingContext } from './crawlers/crawler_commons.js';
+import type { CrawlingContext, LoadedRequest, RestrictedCrawlingContext, TypedContextAddRequests, TypedContextEnqueueLinks } from './crawlers/crawler_commons.js';
 import type { Request } from './request.js';
 import type { Awaitable } from './typedefs.js';
 /**
@@ -10,11 +10,18 @@ import type { Awaitable } from './typedefs.js';
  */
 export declare const defaultRoute: unique symbol;
 /**
- * The crawling context received by a route handler, with `request.userData` narrowed to `UserData`.
+ * The crawling context received by a route handler, with `request.userData` narrowed to `UserData`, and
+ * `addRequests`/`enqueueLinks` typed according to the router's route map (`Routes`) so that enqueuing a
+ * request under a declared label requires the matching `userData` shape.
  */
-export type RouterHandlerContext<Context, UserData extends Dictionary> = Omit<Context, 'request'> & {
+export type RouterHandlerContext<Context, UserData extends Dictionary, Routes extends Record<keyof Routes, Dictionary>> = Omit<Context, 'request' | 'addRequests' | 'enqueueLinks'> & {
     request: LoadedRequest<Request<UserData>>;
-};
+    addRequests: TypedContextAddRequests<Routes>;
+} & (Context extends {
+    enqueueLinks: infer EnqueueLinks;
+} ? {
+    enqueueLinks: TypedContextEnqueueLinks<EnqueueLinks, Routes>;
+} : {});
 /**
  * A map of request labels to a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType, …)
  * validating that label's `request.userData`. Pass it to {@link Router.create} or a `createXRouter`
@@ -24,14 +31,29 @@ export type RouterHandlerContext<Context, UserData extends Dictionary> = Omit<Co
 export type RouteSchemas = Record<string, StandardSchemaV1> & {
     [defaultRoute]?: StandardSchemaV1;
 };
+/** Infers a label's `userData` type from its schema, falling back to a plain {@link Dictionary}. */
+type SchemaUserData<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema> extends Dictionary ? StandardSchemaV1.InferOutput<Schema> : Dictionary;
 /**
- * Derives a route map (label → `userData` type) from a {@link RouteSchemas} map by inferring each
- * schema's output type. Outputs that are not object-shaped fall back to a plain {@link Dictionary}. The
- * {@link defaultRoute} schema drives runtime validation only, so it is excluded from the typed route map.
+ * Derives a route map (label → `userData` type) from a {@link RouteSchemas} map by inferring each schema's
+ * output type. Outputs that are not object-shaped fall back to a plain {@link Dictionary}. The
+ * {@link defaultRoute} schema is kept under its symbol key so {@link Router.addDefaultHandler} can pick it
+ * up; string labels (the ones {@link Router.addHandler} and the crawler-level typing accept) ignore it.
  */
 export type RoutesFromSchemas<Schemas extends RouteSchemas> = {
-    [Label in Extract<keyof Schemas, string>]: StandardSchemaV1.InferOutput<Schemas[Label]> extends Dictionary ? StandardSchemaV1.InferOutput<Schemas[Label]> : Dictionary;
-};
+    [Label in Extract<keyof Schemas, string>]: SchemaUserData<Schemas[Label]>;
+} & (Schemas extends {
+    [defaultRoute]: StandardSchemaV1;
+} ? {
+    [defaultRoute]: SchemaUserData<Schemas[typeof defaultRoute]>;
+} : {});
+/**
+ * The `userData` type of the default route: inferred from the {@link defaultRoute} schema when the route map
+ * carries one, otherwise the provided `Fallback`.
+ * @internal
+ */
+export type DefaultRouteUserData<Routes, Fallback extends Dictionary> = Routes extends {
+    [defaultRoute]: infer DefaultUserData extends Dictionary;
+} ? DefaultUserData : Fallback;
 /**
  * Validates `userData` against a {@link RouteSchemas|Standard Schema}, returning the parsed (and coerced)
  * value. Throws a {@link RequestValidationError} when validation fails.
@@ -173,19 +195,20 @@ export declare class Router<Context extends Omit<RestrictedCrawlingContext, 'enq
      * Registers new route handler for given label. When the router declares a route map, the
      * `label` is restricted to the declared labels and `request.userData` is typed accordingly.
      */
-    addHandler<Label extends keyof Routes & string>(label: Label, handler: (ctx: RouterHandlerContext<Context, Routes[Label]>) => Awaitable<void>): void;
+    addHandler<Label extends keyof Routes & string>(label: Label, handler: (ctx: RouterHandlerContext<Context, Routes[Label], Routes>) => Awaitable<void>): void;
     /**
      * Registers new route handler for given label, explicitly typing `request.userData` via the
      * `UserData` type argument. Useful when the router has no declared route map (the open default)
      * and you want to type a single handler, or to register a handler under a `symbol` label.
      */
-    addHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(label: RouterLabel<Routes>, handler: (ctx: RouterHandlerContext<Context, UserData>) => Awaitable<void>): void;
+    addHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(label: RouterLabel<Routes>, handler: (ctx: RouterHandlerContext<Context, UserData, Routes>) => Awaitable<void>): void;
     /**
      * Registers default route handler. As a fallback it can receive any request (including labels not
-     * declared in the route map), so `request.userData` defaults to the context's `userData` type
-     * (loosely typed by default). Pass an explicit `UserData` type argument to narrow it.
+     * declared in the route map). When the router was created with a {@link defaultRoute} schema,
+     * `request.userData` is typed from it; otherwise it defaults to the context's (loosely typed) `userData`.
+     * Pass an explicit `UserData` type argument to narrow it.
      */
-    addDefaultHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(handler: (ctx: RouterHandlerContext<Context, UserData>) => Awaitable<void>): void;
+    addDefaultHandler<UserData extends Dictionary = DefaultRouteUserData<Routes, GetUserDataFromRequest<Context['request']>>>(handler: (ctx: RouterHandlerContext<Context, UserData, Routes>) => Awaitable<void>): void;
     /**
      * Returns the {@link RouteSchemas|Standard Schema} registered for a label, if any. Used by the crawler
      * to validate `request.userData` when requests are added.
@@ -234,3 +257,4 @@ export declare class Router<Context extends Omit<RestrictedCrawlingContext, 'enq
     static create<Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext, UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
     static create<Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext, const Schemas extends RouteSchemas = RouteSchemas>(schemas: Schemas): RouterHandler<Context, RoutesFromSchemas<Schemas>>;
 }
+export {};

package/router.js

@@ -155,8 +155,9 @@ export class Router {
     }
     /**
      * Registers default route handler. As a fallback it can receive any request (including labels not
-     * declared in the route map), so `request.userData` defaults to the context's `userData` type
-     * (loosely typed by default). Pass an explicit `UserData` type argument to narrow it.
+     * declared in the route map). When the router was created with a {@link defaultRoute} schema,
+     * `request.userData` is typed from it; otherwise it defaults to the context's (loosely typed) `userData`.
+     * Pass an explicit `UserData` type argument to narrow it.
      */
     addDefaultHandler(handler) {
         this.validate(defaultRoute);

package/service_locator.d.ts

@@ -93,9 +93,9 @@ interface ServiceLocatorInterface {
  *
  * const crawler = new BasicCrawler({
  *     requestHandler: async ({ request }) => { ... },
- *     configuration: new Configuration({ ... }),  // custom config
+ *     configuration: new Configuration({ ... }),           // custom configuration
  *     storageBackend: new MemoryStorageBackend(),          // custom storage
- *     eventManager: LocalEventManager.fromConfig(),  // custom events
+ *     eventManager: LocalEventManager.fromConfiguration(), // custom events
  * });
  * // Crawler has its own isolated ServiceLocator instance
  * ```

package/service_locator.js

@@ -31,9 +31,9 @@ import { StorageInstanceManager } from './storages/storage_instance_manager.js';
  *
  * const crawler = new BasicCrawler({
  *     requestHandler: async ({ request }) => { ... },
- *     configuration: new Configuration({ ... }),  // custom config
+ *     configuration: new Configuration({ ... }),           // custom configuration
  *     storageBackend: new MemoryStorageBackend(),          // custom storage
- *     eventManager: LocalEventManager.fromConfig(),  // custom events
+ *     eventManager: LocalEventManager.fromConfiguration(), // custom events
  * });
  * // Crawler has its own isolated ServiceLocator instance
  * ```
@@ -88,7 +88,7 @@ export class ServiceLocator {
                 this.getLogger().warning('Implicit creation of event manager will implicitly set configuration as side effect. ' +
                     'It is advised to explicitly first set the configuration instead.');
             }
-            this.eventManager = LocalEventManager.fromConfig(this.getConfiguration());
+            this.eventManager = LocalEventManager.fromConfiguration(this.getConfiguration());
         }
         return this.eventManager;
     }
@@ -111,10 +111,10 @@ export class ServiceLocator {
                 this.getLogger().warning('Implicit creation of storage backend will implicitly set configuration as side effect. ' +
                     'It is advised to explicitly first set the configuration instead.');
             }
-            const config = this.getConfiguration();
-            this.storageBackend = config.persistStorage
+            const configuration = this.getConfiguration();
+            this.storageBackend = configuration.persistStorage
                 ? new FileSystemStorageBackend({
-                    localDataDirectory: config.storageDir,
+                    localDataDirectory: configuration.storageDir,
                     logger: this.getLogger().child({ prefix: 'FileSystemStorageBackend' }),
                 })
                 : new MemoryStorageBackend({

package/session_pool/session_pool.js

@@ -141,7 +141,7 @@ export class SessionPool {
             return;
         }
         this.keyValueStore = await KeyValueStore.open(this.persistStateKeyValueStoreId ? { id: this.persistStateKeyValueStoreId } : null, {
-            config: serviceLocator.getConfiguration(),
+            configuration: serviceLocator.getConfiguration(),
         });
         if (!this.persistStateKeyValueStoreId) {
             this.log.debug(`No 'persistStateKeyValueStoreId' options specified, this session pool's data has been saved in the KeyValueStore with the id: ${this.keyValueStore.id}`);

package/storages/dataset.d.ts

@@ -140,7 +140,7 @@ export interface DatasetExportToOptions extends DatasetExportOptions {
  * @category Result Stores
  */
 export declare class Dataset<Data extends Dictionary = Dictionary> {
-    readonly config: Configuration;
+    readonly configuration: Configuration;
     id: string;
     name?: string;
     backend: DatasetBackend<Data>;
@@ -149,7 +149,7 @@ export declare class Dataset<Data extends Dictionary = Dictionary> {
     /**
      * @internal
      */
-    constructor(options: DatasetOptions, config?: Configuration);
+    constructor(options: DatasetOptions, configuration?: Configuration);
     /**
      * Backend-independent usage counters tracked for this dataset (read / write operations issued to
      * the underlying storage backend). Counted per backend call.

package/storages/dataset.js

@@ -83,7 +83,7 @@ export function assertJsonSerializable(item, index) {
  * @category Result Stores
  */
 export class Dataset {
-    config;
+    configuration;
     id;
     name;
     backend;
@@ -95,8 +95,8 @@ export class Dataset {
     /**
      * @internal
      */
-    constructor(options, config = Configuration.getGlobalConfig()) {
-        this.config = config;
+    constructor(options, configuration = Configuration.getGlobalConfiguration()) {
+        this.configuration = configuration;
         this.id = options.metadata.id;
         this.name = options.metadata.name;
         this.backend = options.backend;
@@ -168,7 +168,7 @@ export class Dataset {
      * @param [contentType] Only JSON and CSV are supported currently, defaults to JSON.
      */
     async exportTo(key, options, contentType) {
-        const kvStore = await KeyValueStore.open(options?.toKVS ?? null, { config: this.config });
+        const kvStore = await KeyValueStore.open(options?.toKVS ?? null, { configuration: this.configuration });
         const items = await this.export(options);
         if (contentType === 'text/csv') {
             // To handle empty dataset exports gracefully.
@@ -455,12 +455,12 @@ export class Dataset {
     static async open(identifier, options = {}) {
         checkStorageAccess();
         ow(options, ow.object.exactShape({
-            config: ow.optional.object.instanceOf(Configuration),
+            configuration: ow.optional.object.instanceOf(Configuration),
             storageBackend: ow.optional.object,
         }));
-        options.config ??= Configuration.getGlobalConfig();
+        options.configuration ??= Configuration.getGlobalConfiguration();
         const storageBackend = options.storageBackend ?? serviceLocator.getStorageBackend();
-        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, config: options.config });
+        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, configuration: options.configuration });
         const resolved = await resolveStorageIdentifier(identifier, storageBackend, 'Dataset');
         return serviceLocator.getStorageInstanceManager().openStorage(this, {
             ...resolved,

package/storages/key_value_store.d.ts

@@ -61,7 +61,7 @@ import type { StorageOpenOptions } from './utils.js';
  * @category Result Stores
  */
 export declare class KeyValueStore {
-    readonly config: Configuration;
+    readonly configuration: Configuration;
     readonly id: string;
     readonly name?: string;
     private readonly backend;
@@ -72,7 +72,7 @@ export declare class KeyValueStore {
     /**
      * @internal
      */
-    constructor(options: KeyValueStoreOptions, config?: Configuration);
+    constructor(options: KeyValueStoreOptions, configuration?: Configuration);
     /**
      * Backend-independent usage counters tracked for this key-value store (read / write / delete /
      * list operations issued to the underlying storage backend). Counted per backend call.

package/storages/key_value_store.js

@@ -67,7 +67,7 @@ const KVS_KEYS_DEFAULT_LIMIT = 1000;
  * @category Result Stores
  */
 export class KeyValueStore {
-    config;
+    configuration;
     id;
     name;
     backend;
@@ -83,8 +83,8 @@ export class KeyValueStore {
     /**
      * @internal
      */
-    constructor(options, config = Configuration.getGlobalConfig()) {
-        this.config = config;
+    constructor(options, configuration = Configuration.getGlobalConfiguration()) {
+        this.configuration = configuration;
         this.id = options.metadata.id;
         this.name = options.metadata.name;
         this.backend = options.backend;
@@ -517,12 +517,12 @@ export class KeyValueStore {
     static async open(identifier, options = {}) {
         checkStorageAccess();
         ow(options, ow.object.exactShape({
-            config: ow.optional.object.instanceOf(Configuration),
+            configuration: ow.optional.object.instanceOf(Configuration),
             storageBackend: ow.optional.object,
         }));
-        options.config ??= Configuration.getGlobalConfig();
+        options.configuration ??= Configuration.getGlobalConfiguration();
         const storageBackend = options.storageBackend ?? serviceLocator.getStorageBackend();
-        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, config: options.config });
+        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, configuration: options.configuration });
         const resolved = await resolveStorageIdentifier(identifier, storageBackend, 'KeyValueStore');
         return serviceLocator.getStorageInstanceManager().openStorage(this, {
             ...resolved,
@@ -649,6 +649,6 @@ export class KeyValueStore {
      */
     static async getInput() {
         const store = await this.open();
-        return store.getValue(store.config.inputKey);
+        return store.getValue(store.configuration.inputKey);
     }
 }

package/storages/request_list.d.ts

@@ -146,7 +146,7 @@ export interface RequestListOptions {
      */
     keepDuplicateUrls?: boolean;
     /** @internal */
-    config?: Configuration;
+    configuration?: Configuration;
     /**
      * The HTTP client to be used to download `requestsFromUrl` URLs.
      *

package/storages/request_queue.js

@@ -711,14 +711,14 @@ export class RequestQueue {
     static async open(identifier, options = {}) {
         checkStorageAccess();
         ow(options, ow.object.exactShape({
-            config: ow.optional.object.instanceOf(Configuration),
+            configuration: ow.optional.object.instanceOf(Configuration),
             storageBackend: ow.optional.object,
             proxyConfiguration: ow.optional.object,
             httpClient: ow.optional.object,
         }));
         const storageBackend = options.storageBackend ?? serviceLocator.getStorageBackend();
-        const config = options.config ?? serviceLocator.getConfiguration();
-        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, config });
+        const configuration = options.configuration ?? serviceLocator.getConfiguration();
+        await purgeDefaultStorages({ onlyPurgeOnce: true, storageBackend, configuration });
         const resolved = await resolveStorageIdentifier(identifier, storageBackend, 'RequestQueue');
         const queue = await serviceLocator
             .getStorageInstanceManager()

package/storages/sitemap_request_loader.js

@@ -90,7 +90,6 @@ export class SitemapRequestLoader {
             globs: ow.optional.array.ofType(ow.any(ow.string, ow.object.hasKeys('glob'))),
             exclude: ow.optional.array.ofType(ow.any(ow.string, ow.regExp, ow.object.hasKeys('glob'), ow.object.hasKeys('regexp'))),
             regexps: ow.optional.array.ofType(ow.any(ow.regExp, ow.object.hasKeys('regexp'))),
-            config: ow.optional.object,
             persistenceOptions: ow.optional.object,
         }));
         const { globs, exclude, regexps } = options;

package/storages/utils.d.ts

@@ -9,7 +9,7 @@ interface PurgeDefaultStorageOptions {
      * If set to `true`, calling multiple times will only have effect at the first time.
      */
     onlyPurgeOnce?: boolean;
-    config?: Configuration;
+    configuration?: Configuration;
     storageBackend?: StorageBackend;
 }
 /**
@@ -37,9 +37,9 @@ export declare function purgeDefaultStorages(options?: PurgeDefaultStorageOption
  * This is a shortcut for running (optional) `purge` method on the StorageBackend interface, in other words
  * it will call the `purge` method of the underlying storage implementation we are currently using.
  */
-export declare function purgeDefaultStorages(config?: Configuration, storageBackend?: StorageBackend): Promise<void>;
+export declare function purgeDefaultStorages(configuration?: Configuration, storageBackend?: StorageBackend): Promise<void>;
 export interface UseStateOptions {
-    config?: Configuration;
+    configuration?: Configuration;
     /**
      * The name of the key-value store you'd like the state to be stored in.
      * If not provided, the default store will be used.
@@ -53,7 +53,7 @@ export interface UseStateOptions {
  *
  * @param name The name of the store to use.
  * @param defaultValue If the store does not yet have a value in it, the value will be initialized with the `defaultValue` you provide.
- * @param options An optional object parameter where a custom `keyValueStoreName` and `config` can be passed in.
+ * @param options An optional object parameter where a custom `keyValueStoreName` and `configuration` can be passed in.
  */
 export declare function useState<State extends Dictionary = Dictionary>(name?: string, defaultValue?: State, options?: UseStateOptions): Promise<State>;
 /**
@@ -119,7 +119,7 @@ export interface StorageOpenOptions {
     /**
      * SDK configuration instance, defaults to the static register.
      */
-    config?: Configuration;
+    configuration?: Configuration;
     /**
      * Optional storage backend that should be used to open storages.
      */

package/storages/utils.js

@@ -2,18 +2,18 @@ import crypto from 'node:crypto';
 import { Configuration } from '../configuration.js';
 import { serviceLocator } from '../service_locator.js';
 import { KeyValueStore } from './key_value_store.js';
-export async function purgeDefaultStorages(configOrOptions, storageBackend) {
-    const options = configOrOptions instanceof Configuration
+export async function purgeDefaultStorages(configurationOrOptions, storageBackend) {
+    const options = configurationOrOptions instanceof Configuration
         ? {
             storageBackend,
-            config: configOrOptions,
+            configuration: configurationOrOptions,
         }
-        : (configOrOptions ?? {});
-    const { config = serviceLocator.getConfiguration(), onlyPurgeOnce = false } = options;
+        : (configurationOrOptions ?? {});
+    const { configuration = serviceLocator.getConfiguration(), onlyPurgeOnce = false } = options;
     ({ storageBackend = serviceLocator.getStorageBackend() } = options);
     const casted = storageBackend;
     // if `onlyPurgeOnce` is true, will purge anytime this function is called, otherwise - only on start
-    if (!onlyPurgeOnce || (config.purgeOnStart && !casted.__purged)) {
+    if (!onlyPurgeOnce || (configuration.purgeOnStart && !casted.__purged)) {
         casted.__purged = true;
         await casted.purge?.();
     }
@@ -25,11 +25,11 @@ export async function purgeDefaultStorages(configOrOptions, storageBackend) {
  *
  * @param name The name of the store to use.
  * @param defaultValue If the store does not yet have a value in it, the value will be initialized with the `defaultValue` you provide.
- * @param options An optional object parameter where a custom `keyValueStoreName` and `config` can be passed in.
+ * @param options An optional object parameter where a custom `keyValueStoreName` and `configuration` can be passed in.
  */
 export async function useState(name, defaultValue = {}, options) {
     const kvStore = await KeyValueStore.open(options?.keyValueStoreName ? { name: options.keyValueStoreName } : null, {
-        config: options?.config || serviceLocator.getConfiguration(),
+        configuration: options?.configuration || serviceLocator.getConfiguration(),
     });
     return kvStore.getAutoSavedValue(name || 'CRAWLEE_GLOBAL_STATE', defaultValue);
 }