feat: schema-validated router labels via standard-schema

[B4nan]

Makes the router's request label drive the type of request.userData end-to-end — from declaring routes, through the request handler, all the way to the methods that enqueue new requests. Targets v4.

The compile-time-only subset (typed route map for the router) was split out and already merged to master in #3747. This PR is the full v4 version: it adds runtime schema validation and propagates the route map to the crawler/context request methods.

1. Typed route map (compile-time)

Declare a label → userData map and pass it as the router's second type argument. Handlers get request.userData typed per label, and unknown labels are a compile error. Fully backwards compatible — the default route map is open (Record<string, …>), so existing untyped usage and the legacy flat-userData generic keep working.

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 () => {}); // ❌ not a known label

The default handler (addDefaultHandler) is a fallback for any request, so its userData stays loosely typed.

2. Schema-validated labels (types + runtime validation)

Passing a per-label Standard Schema (Zod, Valibot, ArkType, …) both infers the userData types and validates them at runtime before the handler runs, replacing request.userData with the parsed value. Invalid userData throws a new non-retryable RequestValidationError (the data won't change between attempts) carrying the schema issues.

import { z } from 'zod';

const router = createCheerioRouter({
    PRODUCT: z.object({ sku: z.string(), price: z.coerce.number() }),
    CATEGORY: z.object({ categoryId: z.string() }),
});

router.addHandler('PRODUCT', async ({ request }) => {
    request.userData.price; // number — inferred from the schema, coerced/validated at runtime
});

3. Propagation to crawler & context request methods

When a typed router is used, the route map now also types the request inputs: providing a declared label requires the matching userData shape (and rejects unknown labels); unlabeled requests keep loose userData (they hit the default handler).

• Handler context — ctx.addRequests / ctx.enqueueLinks are typed from the route map. Driven by the router itself, so it works for every crawler type.
• Crawler instance — Routes is inferred from the requestHandler option and types crawler.addRequests / crawler.run. Threaded through all crawler classes (Basic/Http/Cheerio/JSDOM/LinkeDOM and the browser family: Browser/Playwright/Puppeteer/Stagehand/AdaptivePlaywright).

const crawler = new PlaywrightCrawler({ requestHandler: router });

await crawler.addRequests([{ url, label: 'PRODUCT', userData: { sku: 's', price: 1 } }]); // ✅
await crawler.addRequests([{ url, label: 'PRODUCT', userData: { sku: 1 } }]);             // ❌ wrong userData
await crawler.addRequests([{ url, label: 'NOPE' }]);                                      // ❌ unknown label

How

• New RouteSchemas / RoutesFromSchemas (via StandardSchemaV1.InferOutput); Router.create and the createXRouter factories gain overloads for the route map, the legacy flat-userData form, and the schema map (disambiguated by value type). Adds the tiny, types-only @standard-schema/spec dep to @crawlee/core (zod is already a core dep on v4 and implements the interface).
• LabeledSource / TypedRequestsLike build a label-discriminated request-input type; a signature-preserving transform retypes enqueueLinks's label/userData without changing argument optionality or return type (which differ per crawler).
• A Routes generic is inferred from requestHandler and threaded through the crawler-class hierarchy.

All of it is backwards compatible via the open route-map default.

Relates to #3082. The remaining parts of that issue (typed pushData / key-value store) are a separate axis and are not in scope here.

🤖 Generated with Claude Code