fix(core): align typed router with v3 PR review polish

- default handler keeps `request.userData` loosely typed (it is a fallback
  for any request, including labels not in the route map)
- split factory/`Router.create` into explicit overloads (route map vs legacy
  flat userData) for backwards compatibility, keeping the schema overload
- drop the exported `RouteMap` alias (referenced as prose in docs instead)

Author: B4nan

packages/basic-crawler/src/internals/basic-crawler.ts

@@ -2349,9 +2349,12 @@ export interface CrawlerRunOptions extends CrawlerAddRequestsOptions {
  */
 export function createBasicRouter<
     Context extends BasicCrawlingContext = BasicCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createBasicRouter<
+    Context extends BasicCrawlingContext = BasicCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createBasicRouter<
     Context extends BasicCrawlingContext = BasicCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/cheerio-crawler/src/internals/cheerio-crawler.ts

@@ -366,9 +366,12 @@ export async function cheerioCrawlerEnqueueLinks(
  */
 export function createCheerioRouter<
     Context extends CheerioCrawlingContext = CheerioCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createCheerioRouter<
+    Context extends CheerioCrawlingContext = CheerioCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createCheerioRouter<
     Context extends CheerioCrawlingContext = CheerioCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/core/src/errors.ts

@@ -17,7 +17,7 @@ export class CriticalError extends NonRetryableError {}
 export class MissingRouteError extends CriticalError {}
 
 /**
- * Thrown when a request's `userData` does not match the {@apilink RouteMap} schema registered for its label.
+ * Thrown when a request's `userData` does not match the {@apilink RouteSchemas|Standard Schema} registered for its label.
  *
  * As the `userData` does not change between attempts, this error is non-retryable.
  */

packages/core/src/router.ts

@@ -9,18 +9,21 @@ import type { Awaitable } from './typedefs.js';
 const defaultRoute = Symbol('default-route');
 
 /**
- * A map of request labels to the shape of `request.userData` expected for that label. Pass it as the
- * `Routes` type argument of {@apilink Router} (or a `createXRouter` factory) to get per-label typing of
- * `request.userData` and autocomplete/validation of labels in {@apilink Router.addHandler}.
- *
- * ```ts
- * interface MyRoutes {
- *     PRODUCT: { sku: string; price: number };
- *     CATEGORY: { categoryId: string };
- * }
- * ```
+ * The crawling context received by a route handler, with `request.userData` narrowed to `UserData`.
+ */
+export type RouterHandlerContext<Context, UserData extends Dictionary> = Omit<Context, 'request'> & {
+    request: LoadedRequest<Request<UserData>>;
+};
+
+/**
+ * The set of labels accepted by {@apilink 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 RouteMap = Record<string, Dictionary>;
+export type RouterLabel<Routes extends Record<keyof Routes, Dictionary>> = string extends keyof Routes
+    ? string | symbol
+    : (keyof Routes & string) | symbol;
 
 /**
  * A map of request labels to a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType, …)
@@ -31,32 +34,15 @@ export type RouteMap = Record<string, Dictionary>;
 export type RouteSchemas = Record<string, StandardSchemaV1>;
 
 /**
- * Derives a {@apilink RouteMap} (label → `userData` type) from a {@apilink RouteSchemas} map by inferring
- * each schema's output type. Outputs that are not object-shaped fall back to a plain {@apilink Dictionary}.
+ * Derives a route map (label → `userData` type) from a {@apilink RouteSchemas} map by inferring each
+ * schema's output type. Outputs that are not object-shaped fall back to a plain {@apilink Dictionary}.
  */
 export type RoutesFromSchemas<Schemas extends RouteSchemas> = {
     [Label in keyof Schemas]: StandardSchemaV1.InferOutput<Schemas[Label]> extends Dictionary
         ? StandardSchemaV1.InferOutput<Schemas[Label]>
         : Dictionary;
 };
 
-/**
- * The crawling context received by a route handler, with `request.userData` narrowed to `UserData`.
- */
-export type RouterHandlerContext<Context, UserData extends Dictionary> = Omit<Context, 'request'> & {
-    request: LoadedRequest<Request<UserData>>;
-};
-
-/**
- * The set of labels accepted by {@apilink Router.addHandler}. When the router declares a concrete
- * {@apilink RouteMap} (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 Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext,
     Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
@@ -137,9 +123,9 @@ export type RouterRoutes<Context, Routes extends Record<keyof Routes, Dictionary
  *
  * ## Typed labels
  *
- * To get `request.userData` typed per label, declare a {@apilink RouteMap} and pass it as the second
- * type argument. The label passed to {@apilink Router.addHandler} then drives the type of
- * `request.userData`, and unknown labels are rejected at compile time:
+ * To get `request.userData` typed per label, declare a route map and pass it as the second type
+ * argument. The label passed to {@apilink Router.addHandler} then drives the type of `request.userData`,
+ * and unknown labels are rejected at compile time:
  *
  * ```ts
  * import { createCheerioRouter, CheerioCrawlingContext } from 'crawlee';
@@ -194,7 +180,7 @@ export class Router<
     protected constructor() {}
 
     /**
-     * Registers new route handler for given label. When the router declares a {@apilink RouteMap}, the
+     * 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>(
@@ -203,8 +189,9 @@ export class Router<
     ): void;
 
     /**
-     * Registers new route handler for given label, with an explicit `request.userData` type. Use this
-     * overload to type a handler whose label is not part of the router's {@apilink RouteMap}.
+     * 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>,
@@ -217,10 +204,11 @@ export class Router<
     }
 
     /**
-     * Registers default route handler. By default `request.userData` is typed as the union of all
-     * `userData` shapes declared in the router's {@apilink RouteMap}.
+     * 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.
      */
-    addDefaultHandler<UserData extends Dictionary = Routes[keyof Routes]>(
+    addDefaultHandler<UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(
         handler: (ctx: RouterHandlerContext<Context, UserData>) => Awaitable<void>,
     ) {
         this.validate(defaultRoute);
@@ -332,12 +320,21 @@ export class Router<
      * });
      * ```
      */
+    // The handler overloads keep the second type argument backwards compatible. When it is a route map
+    // (every value is a `Dictionary`) the first overload applies and labels are typed per route. Otherwise
+    // it fails the `Record<keyof Routes, Dictionary>` constraint and falls through to the second overload,
+    // where it is treated as the legacy flat `userData` shape shared by all handlers. The third overload
+    // accepts a Standard Schema per label, inferring the route map and validating `userData` at runtime.
     static create<
         Context extends Omit<RestrictedCrawlingContext, 'enqueueLinks'> = CrawlingContext,
-        UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-        Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+        Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
     >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
 
+    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,
@@ -357,7 +354,7 @@ export class Router<
 
         for (const [label, value] of Object.entries(routesOrSchemas ?? {})) {
             if (typeof value === 'function') {
-                router.addHandler(label as keyof Context & string, value as (ctx: any) => Awaitable<void>);
+                router.addHandler(label, value as (ctx: any) => Awaitable<void>);
             } else {
                 router.schemas.set(label, value);
             }

packages/http-crawler/src/internals/file-download.ts

@@ -262,9 +262,12 @@ function trackBodyConsumption(response: Response): { response: ResponseWithUrl;
  */
 export function createFileRouter<
     Context extends FileDownloadCrawlingContext = FileDownloadCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createFileRouter<
+    Context extends FileDownloadCrawlingContext = FileDownloadCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createFileRouter<
     Context extends FileDownloadCrawlingContext = FileDownloadCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/http-crawler/src/internals/http-crawler.ts

@@ -843,9 +843,12 @@ interface RequestFunctionOptions {
  */
 export function createHttpRouter<
     Context extends HttpCrawlingContext = HttpCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createHttpRouter<
+    Context extends HttpCrawlingContext = HttpCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createHttpRouter<
     Context extends HttpCrawlingContext = HttpCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/jsdom-crawler/src/internals/jsdom-crawler.ts

@@ -497,9 +497,12 @@ function extractUrlsFromWindow(window: DOMWindow, selector: string, baseUrl: str
  */
 export function createJSDOMRouter<
     Context extends JSDOMCrawlingContext = JSDOMCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createJSDOMRouter<
+    Context extends JSDOMCrawlingContext = JSDOMCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createJSDOMRouter<
     Context extends JSDOMCrawlingContext = JSDOMCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/linkedom-crawler/src/internals/linkedom-crawler.ts

@@ -387,9 +387,12 @@ function extractUrlsFromWindow(window: Window, selector: string, baseUrl: string
  */
 export function createLinkeDOMRouter<
     Context extends LinkeDOMCrawlingContext = LinkeDOMCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createLinkeDOMRouter<
+    Context extends LinkeDOMCrawlingContext = LinkeDOMCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createLinkeDOMRouter<
     Context extends LinkeDOMCrawlingContext = LinkeDOMCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/playwright-crawler/src/internals/adaptive-playwright-crawler.ts

@@ -784,9 +784,12 @@ export class AdaptivePlaywrightCrawler<
 
 export function createAdaptivePlaywrightRouter<
     Context extends AdaptivePlaywrightCrawlerContext = AdaptivePlaywrightCrawlerContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createAdaptivePlaywrightRouter<
+    Context extends AdaptivePlaywrightCrawlerContext = AdaptivePlaywrightCrawlerContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createAdaptivePlaywrightRouter<
     Context extends AdaptivePlaywrightCrawlerContext = AdaptivePlaywrightCrawlerContext,
     const Schemas extends RouteSchemas = RouteSchemas,

packages/playwright-crawler/src/internals/playwright-crawler.ts

@@ -349,9 +349,12 @@ export function handleCloudflareChallengeHook(options?: HandleCloudflareChalleng
  */
 export function createPlaywrightRouter<
     Context extends PlaywrightCrawlingContext = PlaywrightCrawlingContext,
-    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
-    Routes extends Record<keyof Routes, Dictionary> = Record<string, UserData>,
+    Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>,
 >(routes?: RouterRoutes<Context, Routes>): RouterHandler<Context, Routes>;
+export function createPlaywrightRouter<
+    Context extends PlaywrightCrawlingContext = PlaywrightCrawlingContext,
+    UserData extends Dictionary = GetUserDataFromRequest<Context['request']>,
+>(routes?: RouterRoutes<Context, Record<string, UserData>>): RouterHandler<Context, Record<string, UserData>>;
 export function createPlaywrightRouter<
     Context extends PlaywrightCrawlingContext = PlaywrightCrawlingContext,
     const Schemas extends RouteSchemas = RouteSchemas,