@crawlee/core 4.0.0-beta.14 → 4.0.0-beta.141

package/request.js

@@ -1,32 +1,13 @@
 import crypto from 'node:crypto';
 import util from 'node:util';
-import ow from 'ow';
-import { normalizeUrl } from '@apify/utilities';
-import { log as defaultLog } from './log.js';
+import { z } from 'zod';
+import { cryptoRandomObjectId, normalizeUrl } from '@apify/utilities';
+import { serviceLocator } from './service_locator.js';
 import { keys } from './typedefs.js';
-// new properties on the Request object breaks serialization
-const log = defaultLog.child({ prefix: 'Request' });
-const requestOptionalPredicates = {
-    id: ow.optional.string,
-    loadedUrl: ow.optional.string.url,
-    uniqueKey: ow.optional.string,
-    method: ow.optional.string,
-    payload: ow.optional.any(ow.string, ow.uint8Array),
-    noRetry: ow.optional.boolean,
-    retryCount: ow.optional.number,
-    sessionRotationCount: ow.optional.number,
-    maxRetries: ow.optional.number,
-    errorMessages: ow.optional.array.ofType(ow.string),
-    headers: ow.optional.object,
-    userData: ow.optional.object,
-    label: ow.optional.string,
-    handledAt: ow.optional.any(ow.string.date, ow.date),
-    keepUrlFragment: ow.optional.boolean,
-    useExtendedUniqueKey: ow.optional.boolean,
-    skipNavigation: ow.optional.boolean,
-    crawlDepth: ow.optional.number.greaterThanOrEqual(0),
-    state: ow.optional.number.greaterThanOrEqual(0).lessThanOrEqual(6),
-};
+import { parseArgument, schemas } from './validators.js';
+const dateString = z.string().refine((value) => !Number.isNaN(Date.parse(value)), {
+    message: 'Invalid input: expected a date string',
+});
 export var RequestState;
 (function (RequestState) {
     RequestState[RequestState["UNPROCESSED"] = 0] = "UNPROCESSED";
@@ -38,6 +19,34 @@ export var RequestState;
     RequestState[RequestState["ERROR"] = 6] = "ERROR";
     RequestState[RequestState["SKIPPED"] = 7] = "SKIPPED";
 })(RequestState || (RequestState = {}));
+const requestUrlSchema = z.object({ url: z.string() });
+// new properties on the Request object breaks serialization
+const requestOptionalSchemaShapes = {
+    id: z.string().optional(),
+    loadedUrl: z.url().optional(),
+    uniqueKey: z.string().optional(),
+    method: z.string().optional(),
+    payload: z.union([z.string(), z.instanceof(Uint8Array)]).optional(),
+    noRetry: z.boolean().optional(),
+    retryCount: schemas.anyNumber.optional(),
+    sessionId: z.string().optional(),
+    maxRetries: schemas.anyNumber.optional(),
+    errorMessages: schemas.arrayOf(z.string(), 'strings').optional(),
+    headers: z.looseObject({}).optional(),
+    userData: z.looseObject({}).optional(),
+    label: z.string().optional(),
+    handledAt: z.union([dateString, z.date()]).optional(),
+    keepUrlFragment: z.boolean().optional(),
+    useExtendedUniqueKey: z.boolean().optional(),
+    alwaysEnqueue: z.boolean().optional(),
+    skipNavigation: z.boolean().optional(),
+    crawlDepth: schemas.anyNumber
+        .refine((value) => value >= 0, 'Expected a number greater than or equal to 0')
+        .optional(),
+    state: z.enum(RequestState).optional(),
+};
+// Each schema is wrapped in a single-key object so validation errors carry the property name.
+const requestOptionalSchemas = Object.fromEntries(Object.entries(requestOptionalSchemaShapes).map(([key, schema]) => [key, z.object({ [key]: schema })]));
 /**
  * Represents a URL to be crawled, optionally including HTTP method, headers, payload and other metadata.
  * The `Request` object also stores information about errors that occurred during processing of the request.
@@ -101,8 +110,13 @@ class CrawleeRequest {
     /** Object with HTTP headers. Key is header name, value is the value. */
     headers;
     /** Private store for the custom user data assigned to the request. */
-    _userData = {};
-    /** Custom user data assigned to the request. */
+    #userData = {};
+    /**
+     * Custom user data assigned to the request.
+     *
+     * All data stored in `userData` must be JSON-serializable.
+     * Storing non-serializable values (e.g. functions, symbols) may result in unexpected results.
+     */
     userData = {};
     /**
      * ISO datetime string that indicates the time when the request has been processed.
@@ -113,76 +127,89 @@ class CrawleeRequest {
      * `Request` parameters including the URL, HTTP method and headers, and others.
      */
     constructor(options) {
-        ow(options, 'RequestOptions', ow.object);
-        ow(options.url, 'RequestOptions.url', ow.string);
-        // 'ow' validation is slow, because it checks all predicates
+        // A bare URL is a common slip — point at the object form instead of a generic type error.
+        if (typeof options === 'string') {
+            throw new TypeError(`\`Request\` options must be an object, got the string '${options}'. ` +
+                'Did you mean `new Request({ url })`?');
+        }
+        parseArgument(options, schemas.anyObject, 'RequestOptions');
+        parseArgument(options, requestUrlSchema, 'RequestOptions');
+        // Full-shape validation is slow, because it checks all predicates
         // even if the validated object has only 1 property.
         // This custom validation loop iterates only over existing
         // properties and speeds up the validation cca 3-fold.
-        // See https://github.com/sindresorhus/ow/issues/193
         keys(options).forEach((prop) => {
             // skip url, because it is validated above
             if (prop === 'url') {
                 return;
             }
-            const predicate = requestOptionalPredicates[prop];
+            const schema = requestOptionalSchemas[prop];
             const value = options[prop];
-            if (predicate) {
-                ow(value, `RequestOptions.${prop}`, predicate);
+            if (schema) {
+                parseArgument({ [prop]: value }, schema, 'RequestOptions');
             }
         });
-        const { id, url, loadedUrl, uniqueKey, payload, noRetry = false, retryCount = 0, sessionRotationCount = 0, maxRetries, errorMessages = [], headers = {}, userData = {}, label, handledAt, keepUrlFragment = false, useExtendedUniqueKey = false, skipNavigation, enqueueStrategy, crawlDepth, } = options;
+        const { id, url, loadedUrl, uniqueKey, payload, noRetry = false, retryCount = 0, sessionId, maxRetries, errorMessages = [], headers = {}, userData = {}, label, handledAt, keepUrlFragment = false, useExtendedUniqueKey = false, alwaysEnqueue = false, skipNavigation, enqueueStrategy, crawlDepth, } = options;
         let { method = 'GET' } = options;
         method = method.toUpperCase();
         if (method === 'GET' && payload)
             throw new Error('Request with GET method cannot have a payload.');
+        if (uniqueKey && alwaysEnqueue) {
+            throw new Error('`alwaysEnqueue` cannot be used together with a custom `uniqueKey`.');
+        }
         this.id = id;
         this.url = url;
         this.loadedUrl = loadedUrl;
         this.uniqueKey =
             uniqueKey ||
-                CrawleeRequest.computeUniqueKey({ url, method, payload, keepUrlFragment, useExtendedUniqueKey });
+                CrawleeRequest.computeUniqueKey({
+                    url,
+                    method,
+                    payload,
+                    keepUrlFragment,
+                    useExtendedUniqueKey,
+                    alwaysEnqueue,
+                });
         this.method = method;
         this.payload = payload;
         this.noRetry = noRetry;
         this.retryCount = retryCount;
-        this.sessionRotationCount = sessionRotationCount;
         this.errorMessages = [...errorMessages];
         this.headers = { ...headers };
         this.handledAt = handledAt instanceof Date ? handledAt.toISOString() : handledAt;
         if (label) {
             userData.label = label;
         }
+        // Read `__crawlee` explicitly - on a `userData` coming from another Request instance the
+        // bag is non-enumerable, so the spread alone would silently drop the internal state
+        // (e.g. `skipNavigation`) when a request is re-wrapped after a storage round trip.
+        this.#userData = { __crawlee: userData.__crawlee ?? {}, ...userData };
+        // `userData` must stay an enumerable own accessor — serialization in the storages relies on it
         Object.defineProperties(this, {
-            _userData: {
-                value: { __crawlee: {}, ...userData },
-                enumerable: false,
-                writable: true,
-            },
             userData: {
-                get: () => this._userData,
+                get: () => this.#userData,
                 set: (value) => {
                     Object.defineProperties(value, {
                         __crawlee: {
-                            value: this._userData.__crawlee,
+                            value: this.#userData.__crawlee,
                             enumerable: false,
                             writable: true,
                         },
                         toJSON: {
                             value: () => {
-                                if (Object.keys(this._userData.__crawlee).length > 0) {
+                                if (Object.keys(this.#userData.__crawlee).length > 0) {
                                     return {
-                                        ...this._userData,
-                                        __crawlee: this._userData.__crawlee,
+                                        ...this.#userData,
+                                        __crawlee: this.#userData.__crawlee,
                                     };
                                 }
-                                return this._userData;
+                                return this.#userData;
                             },
                             enumerable: false,
                             writable: true,
                         },
                     });
-                    this._userData = value;
+                    this.#userData = value;
                 },
                 enumerable: true,
             },
@@ -195,6 +222,8 @@ class CrawleeRequest {
             this.maxRetries = maxRetries;
         if (crawlDepth != null)
             this.userData.__crawlee.crawlDepth ??= crawlDepth;
+        if (sessionId)
+            this.sessionId = sessionId;
         // If it's already set, don't override it (for instance when fetching from storage)
         if (enqueueStrategy) {
             this.enqueueStrategy ??= enqueueStrategy;
@@ -211,11 +240,23 @@ class CrawleeRequest {
             body: this.payload,
         });
     }
-    /** Tells the crawler processing this request to skip the navigation and process the request directly. */
+    /**
+     * Tells the crawler processing this request to skip the navigation and process the request directly.
+     *
+     * When this is set to `true`, the crawling context will not contain the results of the navigation
+     * (e.g. `response`, `body`, `contentType`, `$` or `request.loadedUrl`).
+     * Accessing these properties will throw a {@link NavigationSkippedError} at runtime.
+     */
     get skipNavigation() {
         return this.userData.__crawlee?.skipNavigation ?? false;
     }
-    /** Tells the crawler processing this request to skip the navigation and process the request directly. */
+    /**
+     * Tells the crawler processing this request to skip the navigation and process the request directly.
+     *
+     * When this is set to `true`, the crawling context will not contain the results of the navigation
+     * (e.g. `response`, `body`, `contentType`, `$` or `request.loadedUrl`).
+     * Accessing these properties will throw a {@link NavigationSkippedError} at runtime.
+     */
     set skipNavigation(value) {
         if (!this.userData.__crawlee) {
             this.userData.__crawlee = { skipNavigation: value };
@@ -239,18 +280,13 @@ class CrawleeRequest {
         this.userData.__crawlee ??= {};
         this.userData.__crawlee.crawlDepth = value;
     }
-    /** Indicates the number of times the crawling of the request has rotated the session due to a session or a proxy error. */
-    get sessionRotationCount() {
-        return this.userData.__crawlee?.sessionRotationCount ?? 0;
+    /** ID of a session to use for this request. When set, the crawler will fetch this session from the session pool instead of creating a new one. */
+    get sessionId() {
+        return this.userData.__crawlee?.sessionId;
     }
-    /** Indicates the number of times the crawling of the request has rotated the session due to a session or a proxy error. */
-    set sessionRotationCount(value) {
-        if (!this.userData.__crawlee) {
-            this.userData.__crawlee = { sessionRotationCount: value };
-        }
-        else {
-            this.userData.__crawlee.sessionRotationCount = value;
-        }
+    set sessionId(value) {
+        this.userData.__crawlee ??= {};
+        this.userData.__crawlee.sessionId = value;
     }
     /** shortcut for getting `request.userData.label` */
     get label() {
@@ -286,6 +322,23 @@ class CrawleeRequest {
             this.userData.__crawlee.state = value;
         }
     }
+    /**
+     * Reason for skipping this request.
+     */
+    get skippedReason() {
+        return this.userData.__crawlee?.skippedReason;
+    }
+    /**
+     * Reason for skipping this request.
+     */
+    set skippedReason(value) {
+        if (!this.userData.__crawlee) {
+            this.userData.__crawlee = { skippedReason: value };
+        }
+        else {
+            this.userData.__crawlee.skippedReason = value;
+        }
+    }
     get enqueueStrategy() {
         return this.userData.__crawlee?.enqueueStrategy;
     }
@@ -348,19 +401,28 @@ class CrawleeRequest {
         this.errorMessages.push(message);
     }
     /** @internal */
-    static computeUniqueKey({ url, method = 'GET', payload, keepUrlFragment = false, useExtendedUniqueKey = false, }) {
+    static computeUniqueKey({ url, method = 'GET', payload, keepUrlFragment = false, useExtendedUniqueKey = false, alwaysEnqueue = false, }) {
         const normalizedMethod = method.toUpperCase();
         const normalizedUrl = normalizeUrl(url, keepUrlFragment) || url; // It returns null when url is invalid, causing weird errors.
+        let uniqueKey;
         if (!useExtendedUniqueKey) {
             if (normalizedMethod !== 'GET' && payload) {
-                log.warningOnce(`We've encountered a ${normalizedMethod} Request with a payload. ` +
+                serviceLocator
+                    .getLogger()
+                    .warningOnce(`We've encountered a ${normalizedMethod} Request with a payload. ` +
                     'This is fine. Just letting you know that if your requests point to the same URL ' +
                     'and differ only in method and payload, you should see the "useExtendedUniqueKey" option of Request constructor.');
             }
-            return normalizedUrl;
+            uniqueKey = normalizedUrl;
+        }
+        else {
+            const payloadHash = payload ? CrawleeRequest.hashPayload(payload) : '';
+            uniqueKey = `${normalizedMethod}|${payloadHash}|${normalizedUrl}`;
+        }
+        if (alwaysEnqueue) {
+            uniqueKey = `${cryptoRandomObjectId(17)}|${uniqueKey}`;
         }
-        const payloadHash = payload ? CrawleeRequest.hashPayload(payload) : '';
-        return `${normalizedMethod}(${payloadHash}):${normalizedUrl}`;
+        return uniqueKey;
     }
     /** @internal */
     static hashPayload(payload) {
@@ -368,4 +430,3 @@ class CrawleeRequest {
     }
 }
 export { CrawleeRequest as Request };
-//# sourceMappingURL=request.js.map

package/router.d.ts

@@ -1,14 +1,91 @@
-import type { Dictionary } from '@crawlee/types';
-import type { CrawlingContext, LoadedRequest, RestrictedCrawlingContext } from './crawlers/crawler_commons.js';
+import type { Awaitable, Dictionary } from '@crawlee/types';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CrawlingContext, LoadedRequest, RestrictedCrawlingContext, TypedContextAddRequests, TypedContextEnqueueLinks } from './crawlers/crawler_commons.js';
 import type { Request } from './request.js';
-import type { Awaitable } from './typedefs.js';
-export interface RouterHandler<Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext> extends Router<Context> {
+/**
+ * The key of the default route — the fallback handler registered via {@link Router.addDefaultHandler}.
+ * Use it in a {@link RouteSchemas} map to register a schema that validates the `userData` of every request
+ * that falls through to the default handler (i.e. whose label has no route of its own).
+ */
+export declare const defaultRoute: unique symbol;
+/**
+ * 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, 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`
+ * factory to derive the per-label `request.userData` types *and* validate them at runtime. The optional
+ * {@link defaultRoute} key registers a schema for requests handled by the default route.
+ */
+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 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>]: 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`.
+ */
+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.
+ * @internal
+ */
+export declare function validateUserData(label: string | symbol, schema: StandardSchemaV1, userData: unknown): Promise<Dictionary>;
+/**
+ * The set of labels accepted by {@link Router.addHandler}. When the router declares a concrete
+ * route map (e.g. `{ PRODUCT: ...; CATEGORY: ... }`), only those labels (plus symbols) are
+ * allowed — unknown labels become a compile-time error. When the map is left open (the default
+ * `Record<string, ...>`), any string or symbol label is accepted, preserving the original behaviour.
+ */
+export type RouterLabel<Routes extends Record<keyof Routes, Dictionary>> = string extends keyof Routes ? string | symbol : (keyof Routes & string) | symbol;
+export interface RouterHandler<Context extends RestrictedCrawlingContext = CrawlingContext, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>> extends Router<Context, Routes> {
     (ctx: Context): Awaitable<void>;
 }
 export type GetUserDataFromRequest<T> = T extends Request<infer Y> ? Y : never;
-export type RouterRoutes<Context, UserData extends Dictionary> = {
-    [label in string | symbol]: (ctx: Omit<Context, 'request'> & {
-        request: Request<UserData>;
+/**
+ * Per-route overrides, passed as the last argument of {@link Router.addHandler|`addHandler`} and
+ * {@link Router.addDefaultHandler|`addDefaultHandler`}.
+ */
+export interface RouteOptions {
+    /**
+     * Overrides the crawler's `requestHandlerTimeoutSecs` for this route only. Useful when one kind of page
+     * needs markedly more time than the rest - a listing page behind an infinite scroll, say - and you do not
+     * want to raise the timeout for every other page to accommodate it.
+     *
+     * Applies only to this route's handler. The navigation and the navigation hooks keep their own timeouts.
+     */
+    requestHandlerTimeoutSecs?: number;
+}
+export type RouterRoutes<Context, Routes extends Record<keyof Routes, Dictionary>> = {
+    [Label in keyof Routes]: (ctx: Omit<Context, 'request'> & {
+        request: Request<Routes[Label]>;
     }) => Awaitable<void>;
 };
 /**
@@ -75,36 +152,129 @@ export type RouterRoutes<Context, UserData extends Dictionary> = {
  *    ctx.log.info('...');
  * });
  * ```
+ *
+ * To get `request.userData` typed per label, declare a route map and pass it as the second
+ * type argument. The label passed to {@link Router.addHandler} then drives the type of
+ * `request.userData`, and unknown labels are rejected at compile time:
+ *
+ * ```ts
+ * import { createCheerioRouter, CheerioCrawlingContext } from 'crawlee';
+ *
+ * interface Routes {
+ *     PRODUCT: { sku: string; price: number };
+ *     CATEGORY: { categoryId: string };
+ * }
+ *
+ * const router = createCheerioRouter<CheerioCrawlingContext, Routes>();
+ *
+ * router.addHandler('PRODUCT', async ({ request }) => {
+ *     request.userData.sku;   // string
+ *     request.userData.price; // number
+ * });
+ *
+ * router.addHandler('TYPO', async () => {}); // compile error: not a known label
+ * ```
+ *
+ * Passing a [Standard Schema](https://standardschema.dev) per label instead of a plain type both infers the
+ * `request.userData` types *and* validates them at runtime — when the request is handled, and when it is
+ * added to the crawler (`crawler.addRequests`, `context.addRequests`, `enqueueLinks`). A failing request
+ * throws a {@link RequestValidationError}.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * import { createCheerioRouter } from 'crawlee';
+ *
+ * const router = createCheerioRouter({
+ *     PRODUCT: z.object({ sku: z.string(), price: z.number() }),
+ *     CATEGORY: z.object({ categoryId: z.string() }),
+ * });
+ *
+ * router.addHandler('PRODUCT', async ({ request }) => {
+ *     request.userData.price; // number, inferred from the schema and validated at runtime
+ * });
+ * ```
+ *
+ * A single route can take longer than the rest without raising the crawler-wide
+ * `requestHandlerTimeoutSecs` for everything - pass a per-route timeout as the last argument:
+ *
+ * ```ts
+ * // LIST pages scroll through a lot of content, DETAIL pages are quick
+ * router.addHandler('LIST', async (ctx) => { ... }, { requestHandlerTimeoutSecs: 120 });
+ * router.addHandler('DETAIL', async (ctx) => { ... }); // keeps the crawler's default
+ * ```
+ *
+ * When the time a route needs is only apparent once it is already running, call
+ * {@link CrawlingContext.extendTimeout|`context.extendTimeout`} from inside the handler:
+ *
+ * ```ts
+ * router.addHandler('LIST', async ({ page, extendTimeout }) => {
+ *     const pageCount = await countPages(page);
+ *     extendTimeout(pageCount * 10); // ask for 10 more seconds per page
+ *     await scrapeAllPages(page);
+ * });
+ * ```
  */
-export declare class Router<Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'>> {
-    private readonly routes;
-    private readonly middlewares;
+export declare class Router<Context extends RestrictedCrawlingContext, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>> {
+    #private;
     /**
      * use Router.create() instead!
      * @ignore
      */
-    protected constructor();
+    private constructor();
+    /**
+     * 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. Pass
+     * {@link RouteOptions|`options`} to give this route its own `requestHandlerTimeoutSecs`,
+     * overriding the crawler's default for requests with this label.
+     */
+    addHandler<Label extends keyof Routes & string>(label: Label, handler: (ctx: RouterHandlerContext<Context, Routes[Label], Routes>) => Awaitable<void>, options?: RouteOptions): 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, Routes>) => Awaitable<void>, options?: RouteOptions): void;
     /**
-     * Registers new route handler for given label.
+     * Registers default route handler. As a fallback it can receive any request (including labels not
+     * 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. Pass {@link RouteOptions|`options`} to give the
+     * default route its own `requestHandlerTimeoutSecs`, overriding the crawler's default for requests that fall
+     * through to it.
      */
-    addHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(label: string | symbol, handler: (ctx: Omit<Context, 'request'> & {
-        request: LoadedRequest<Request<UserData>>;
-    }) => Awaitable<void>): void;
+    addDefaultHandler<UserData extends Dictionary = DefaultRouteUserData<Routes, GetUserDataFromRequest<Context['request']>>>(handler: (ctx: RouterHandlerContext<Context, UserData, Routes>) => Awaitable<void>, options?: RouteOptions): void;
     /**
-     * Registers default route handler.
+     * Returns the {@link RouteSchemas|Standard Schema} registered for a label, if any. Used by the crawler
+     * to validate `request.userData` when requests are added.
+     * @internal
      */
-    addDefaultHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(handler: (ctx: Omit<Context, 'request'> & {
-        request: LoadedRequest<Request<UserData>>;
-    }) => Awaitable<void>): void;
+    getSchema(label?: string | symbol): StandardSchemaV1 | undefined;
     /**
      * Registers a middleware that will be fired before the matching route handler.
      * Multiple middlewares can be registered, they will be fired in the same order.
      */
     use(middleware: (ctx: Context) => Awaitable<void>): void;
+    /**
+     * Returns the `requestHandlerTimeoutSecs` registered for a label, or `undefined` when the route did not
+     * override it and the crawler's own timeout should apply. Falls back to the default route the same way
+     * {@link Router.getHandler|`getHandler`} does, so a label with no route of its own inherits whatever
+     * the default route asked for. Used by the crawler; not meant to be called directly.
+     */
+    getTimeoutSecs(label?: string | symbol): number | undefined;
+    /**
+     * The longest `requestHandlerTimeoutSecs` any route asked for, or `undefined` when no route overrides it.
+     * The crawler needs an upper bound up front, before it knows which routes a run will actually hit.
+     */
+    getMaxTimeoutSecs(): number | undefined;
     /**
      * Returns route handler for given label. If no label is provided, the default request handler will be returned.
      */
     getHandler(label?: string | symbol): (ctx: Context) => Awaitable<void>;
+    /**
+     * Validates `request.userData` against the schema registered for its label (if any), replacing it with
+     * the parsed value. Throws a {@link RequestValidationError} when validation fails.
+     */
+    private validateRequest;
     /**
      * Throws when the label already exists in our registry.
      */
@@ -129,6 +299,8 @@ export declare class Router<Context extends Omit<RestrictedCrawlingContext, 'enq
      * await crawler.run();
      * ```
      */
-    static create<Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext, UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(routes?: RouterRoutes<Context, UserData>): RouterHandler<Context>;
+    static create<Context extends RestrictedCrawlingContext = CrawlingContext, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>>(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+    static create<Context extends RestrictedCrawlingContext = CrawlingContext, UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
+    static create<Context extends RestrictedCrawlingContext = CrawlingContext, const Schemas extends RouteSchemas = RouteSchemas>(schemas: Schemas): RouterHandler<Context, RoutesFromSchemas<Schemas>>;
 }
-//# sourceMappingURL=router.d.ts.map
+export {};