@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

package/src/handles/meta.ts

@@ -29,15 +29,20 @@
  */
 
 import { createHandle, type Handle } from "../handle.js";
+import { isThenable } from "./is-thenable.js";
 import type {
   MetaDescriptor,
+  MetaDescriptorBase,
   TitleDescriptor,
   UnsetDescriptor,
 } from "../router/types.js";
 
-/**
- * Type guard for unset descriptor
- */
+function isPromiseDescriptor(
+  descriptor: MetaDescriptor,
+): descriptor is Promise<MetaDescriptorBase> {
+  return isThenable(descriptor);
+}
+
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -49,9 +54,6 @@ function isUnsetDescriptor(
   );
 }
 
-/**
- * Type guard for title descriptor (any form)
- */
 function isTitleDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
@@ -62,9 +64,6 @@ function isTitleDescriptor(
   );
 }
 
-/**
- * Type guard for title template descriptor
- */
 function isTitleTemplate(
   title: TitleDescriptor,
 ): title is { template: string; default: string } {
@@ -76,21 +75,13 @@ function isTitleTemplate(
   );
 }
 
-/**
- * Type guard for absolute title descriptor
- */
 function isAbsoluteTitle(
   title: TitleDescriptor,
 ): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
-/**
- * Get a unique key for a meta descriptor for deduplication.
- * Returns undefined for descriptors that shouldn't be deduplicated.
- */
 function getMetaKey(descriptor: MetaDescriptor): string | undefined {
-  // Skip unset descriptors - they are processed separately
   if (isUnsetDescriptor(descriptor)) {
     return undefined;
   }
@@ -110,13 +101,10 @@ function getMetaKey(descriptor: MetaDescriptor): string | undefined {
     return `httpEquiv:${descriptor.httpEquiv}`;
   }
   if ("script:ld+json" in descriptor) {
-    // JSON-LD scripts can have multiple, don't dedupe by default
     return undefined;
   }
   if ("tagName" in descriptor) {
-    // For link tags, dedupe by rel if present
     if (descriptor.tagName === "link" && "rel" in descriptor) {
-      // Some link rels should be unique (canonical), others not (stylesheet)
       const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
       if (uniqueRels.includes(descriptor.rel as string)) {
         return `link:${descriptor.rel}`;
@@ -136,9 +124,6 @@ const defaultMetaDescriptors: MetaDescriptor[] = [
   { name: "viewport", content: "width=device-width, initial-scale=1" },
 ];
 
-/**
- * Helper to add or replace a descriptor in the result array
- */
 function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
@@ -155,9 +140,6 @@ function addOrReplace(
   }
 }
 
-/**
- * Helper to update indices after removing an element
- */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
   removedIndex: number,
@@ -169,17 +151,11 @@ function updateIndicesAfterRemoval(
   }
 }
 
-/**
- * Collect function for Meta handle.
- * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
- * Supports title templates, absolute titles, and unset descriptors.
- */
 function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
   const result: MetaDescriptor[] = [];
   const keyToIndex = new Map<string, number>();
   let titleTemplate: string | undefined;
 
-  // Add defaults first so they can be overridden
   for (const descriptor of defaultMetaDescriptors) {
     const key = getMetaKey(descriptor);
     if (key !== undefined) {
@@ -190,7 +166,37 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Handle unset descriptors
+      // Promise descriptors cannot be inspected synchronously (their content is
+      // unknown until resolved in <MetaTags> via React's use()), so they bypass
+      // key-based dedup and title-templating: they are appended verbatim. Warn in
+      // dev when a title template is active so the author knows an async
+      // descriptor will NOT participate in the template/dedup.
+      //
+      // The warning is deliberately a GENERAL note, not a duplicate-<title>
+      // prediction: collectMeta cannot tell whether this Promise resolves to a
+      // title (which would indeed yield a 2nd <title>) or to an ordinary
+      // descriptor like an async og:image (which would not). Asserting a
+      // duplicate <title> here is a false positive for the common og:image case,
+      // so the message states only that async descriptors bypass templating —
+      // not that a duplicate <title> WILL occur.
+      if (isPromiseDescriptor(descriptor)) {
+        if (
+          titleTemplate !== undefined &&
+          process.env.NODE_ENV !== "production"
+        ) {
+          console.warn(
+            `[Meta] A Promise meta descriptor was pushed while a title template is active. ` +
+              `Async descriptors bypass deduplication and title-templating: the template is ` +
+              `not applied to them. If this Promise resolves to a title, resolve the value ` +
+              `before pushing (or push a synchronous descriptor) so it participates in the ` +
+              `template; if it resolves to a non-title descriptor (e.g. og:image), this ` +
+              `note does not apply.`,
+          );
+        }
+        result.push(descriptor);
+        continue;
+      }
+
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -202,14 +208,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle title descriptors with template/absolute support
       if (isTitleDescriptor(descriptor)) {
         const titleValue = descriptor.title;
 
         if (isTitleTemplate(titleValue)) {
-          // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
-          // Set the default title
           addOrReplace(
             result,
             keyToIndex,
@@ -220,7 +223,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         }
 
         if (isAbsoluteTitle(titleValue)) {
-          // Absolute title bypasses any template
           addOrReplace(
             result,
             keyToIndex,
@@ -230,9 +232,12 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           continue;
         }
 
-        // String title - apply template if one exists
+        // Insert the title literally. String.prototype.replace treats the
+        // replacement string specially ($&, $`, $', $$, $n), so a title like
+        // "Save $5" or one containing "$&" would be mangled. split/join inserts
+        // the raw value with no special-character interpretation.
         const finalTitle = titleTemplate
-          ? titleTemplate.replace("%s", titleValue as string)
+          ? titleTemplate.split("%s").join(titleValue as string)
           : titleValue;
         addOrReplace(
           result,
@@ -243,7 +248,6 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle all other descriptors
       const key = getMetaKey(descriptor);
       addOrReplace(result, keyToIndex, descriptor, key);
     }
@@ -257,6 +261,13 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  *
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
+ *
+ * Deduplication and title-templating apply only to SYNCHRONOUS descriptors.
+ * A Promise descriptor (`Promise<MetaDescriptorBase>`) is appended verbatim —
+ * its content is not known until it resolves in `<MetaTags>`, so it cannot be
+ * keyed for dedup nor receive a parent title template. If you need a child title
+ * to participate in a layout's `%s` template, push the resolved string title
+ * synchronously rather than a `Promise<{ title }>`.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,

package/src/handles/script.ts

@@ -0,0 +1,244 @@
+/**
+ * Built-in Script handle for injecting <script> tags into the document from
+ * route/layout handlers.
+ *
+ * Push from a SERVER handler with `ctx.use(Script)(config)`; render with the
+ * `<Scripts />` component (from `@rangojs/router/client`) placed in the Document
+ * `<head>` (and optionally a second `<Scripts position="body" />` at the top of
+ * `<body>`). This mirrors the Meta / <MetaTags> pair.
+ *
+ * The request CSP nonce is applied AUTOMATICALLY by <Scripts> to document-rendered
+ * scripts; consumers never pass a nonce. (An async script first loaded on a soft
+ * navigation is injected client-side without a nonce — it relies on
+ * 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT below and the
+ * /scripts skill.) A ScriptConfig is fully serializable (it crosses the
+ * server -> client handle-collection boundary), so callbacks like onLoad are NOT
+ * supported — a consumer needing them renders their own "use client" script.
+ *
+ * EXECUTION CONTRACT (see the /scripts skill for the full story):
+ * - Inline (`children`) and ordered external (`src`, optional `defer`) scripts
+ *   are DOCUMENT-LOAD scripts: they execute only when present in the initial HTML
+ *   response. <Scripts> freezes them after hydration, so a later client (soft)
+ *   navigation never inserts an inert copy — React creates client-mounted
+ *   <script> elements via innerHTML, which the HTML spec makes non-executing.
+ * - Async external scripts (`src` + `async: true`) are React RESOURCES: they load
+ *   once when first encountered, including after a soft navigation, deduped by
+ *   `src`. Use this for a vendor that should load on first visit to a route.
+ * - Reusing an `id` shapes the INITIAL document output (last-push-wins); it does
+ *   not re-run a script during navigation. Per-navigation behavior belongs in a
+ *   "use client" component or hook (see the GtmPageViews pattern in the demo).
+ *
+ * @example
+ * ```ts
+ * // External async loader (React resource — loads on first visit, even soft nav):
+ * ctx.use(Script)({ id: "stripe", src: "https://js.stripe.com/v3", async: true });
+ *
+ * // Inline bootstrap that self-injects its loader (GTM/GA4) — keep it inline so
+ * // React cannot hoist a declarative loader above the bootstrap:
+ * ctx.use(Script)({ id: "gtm", children: gtmBootstrap(containerId) });
+ *
+ * // External ordered (defer) with vendor attributes (document-load):
+ * ctx.use(Script)({
+ *   id: "plausible",
+ *   src: "https://plausible.io/js/script.js",
+ *   defer: true,
+ *   attributes: { "data-domain": "example.com" },
+ * });
+ * ```
+ */
+
+import type { ScriptHTMLAttributes } from "react";
+import { createHandle, type Handle } from "../handle.js";
+
+/**
+ * Extra attributes forwarded onto the emitted <script>. Typed by React, so the
+ * casing is React's (`crossOrigin`, not `crossorigin`) and value shapes are
+ * checked at compile time. `data-*` attributes are allowed. Two groups are
+ * excluded: the fields the Script handle manages itself (`id`, `src`, `async`,
+ * `defer`, `type`, `children`, `nonce`, `dangerouslySetInnerHTML` — set those via
+ * the ScriptConfig fields), and ALL `on*` event handlers (`onLoad`, `onError`,
+ * …): a ScriptConfig is serialized across the server -> client handle boundary, so
+ * a function cannot survive it — render your own "use client" script for callbacks.
+ */
+export type ScriptAttributes = Omit<
+  ScriptHTMLAttributes<HTMLScriptElement>,
+  | "id"
+  | "src"
+  | "async"
+  | "defer"
+  | "type"
+  | "children"
+  | "nonce"
+  | "dangerouslySetInnerHTML"
+  | `on${string}`
+> & {
+  [dataAttr: `data-${string}`]: string | number | boolean | undefined;
+};
+
+/** Fields shared by every script shape. */
+interface ScriptConfigBase {
+  /**
+   * Where <Scripts> renders this script.
+   * - "head" (default): the `<head>` <Scripts> site.
+   * - "body": the `<Scripts position="body" />` site at the top of <body>.
+   * Note: an external `async` script is hoisted into <head> by React regardless.
+   */
+  position?: "head" | "body";
+  /**
+   * The `type` attribute, as a free string: "module", "application/ld+json",
+   * "text/partytown", etc. Omitted means a classic script.
+   */
+  type?: string;
+  /** Extra React-cased attributes (`data-*`, `crossOrigin`, `integrity`, ...). */
+  attributes?: ScriptAttributes;
+}
+
+/**
+ * Inline script: a raw JS body rendered in place, escaped against `</script>`
+ * breakout. DOCUMENT-LOAD only (executes when present in the initial HTML;
+ * <Scripts> freezes it after hydration so navigation never inserts an inert
+ * copy). `id` is REQUIRED — inline scripts are never deduped by React, so a
+ * layout and a child pushing the same bootstrap would inject it twice. It is also
+ * rendered as the script's DOM `id`. Forbids `src`/`async`/`defer`. For analytics
+ * vendors (GTM/GA4/Segment) the body should
+ * create+append its own loader, so the loader is never a separate declarative tag
+ * React could hoist out of order.
+ */
+export interface InlineScriptConfig extends ScriptConfigBase {
+  id: string;
+  children: string;
+  src?: never;
+  async?: never;
+  defer?: never;
+}
+
+/**
+ * External async script: a React-hoisted, `src`-deduped RESOURCE (the
+ * fire-and-forget loader case). Loads once when first encountered, including
+ * after a soft navigation. Deduped by `src` (matching React); `id` is optional
+ * and, when set, is rendered as the DOM `id` (not used as the dedup key here).
+ * Forbids `children`/`defer`.
+ */
+export interface AsyncScriptConfig extends ScriptConfigBase {
+  src: string;
+  async: true;
+  id?: string;
+  children?: never;
+  defer?: never;
+}
+
+/**
+ * External ordered script: in-place, optionally `defer`. DOCUMENT-LOAD only
+ * (executes when present in the initial HTML; not re-run on navigation). `id` is
+ * optional (the dedup key falls back to `src`) and, when set, is rendered as the
+ * DOM `id`. Forbids `children`/`async`.
+ */
+export interface OrderedScriptConfig extends ScriptConfigBase {
+  src: string;
+  defer?: boolean;
+  id?: string;
+  children?: never;
+  async?: never;
+}
+
+/**
+ * A single script to inject, as a discriminated union — exactly one of:
+ * inline (`id` + `children`), external async (`src` + `async: true`), or external
+ * ordered (`src`, optional `defer`). Invalid combinations (both `src`+`children`,
+ * `async`+`defer`, inline without `id`) are compile errors. The CSP nonce is
+ * applied by <Scripts>, never here.
+ */
+export type ScriptConfig =
+  | InlineScriptConfig
+  | AsyncScriptConfig
+  | OrderedScriptConfig;
+
+/** A config's runtime view, for validating untyped/serialized input. */
+type LooseScriptConfig = {
+  id?: string;
+  src?: string;
+  children?: string;
+  async?: boolean;
+  defer?: boolean;
+};
+
+/**
+ * Dev-only validation. The discriminated union makes these states unrepresentable
+ * in TypeScript; the runtime checks exist only for untyped JavaScript callers and
+ * malformed serialized input, not as the primary contract.
+ */
+function validateConfigDev(config: ScriptConfig): void {
+  if (process.env.NODE_ENV === "production") return;
+  const c = config as LooseScriptConfig;
+  if (c.src != null && c.children != null) {
+    console.warn(
+      `[Script] A config has both "src" and "children"; they are mutually ` +
+        `exclusive — "src" wins and the inline body is ignored.`,
+    );
+  } else if (c.src == null && c.children == null) {
+    console.warn(
+      `[Script] A config has neither "src" nor "children"; it injects nothing.`,
+    );
+  } else if (c.src == null && c.id == null) {
+    console.warn(
+      `[Script] An inline script was pushed without an "id" and cannot be ` +
+        `deduplicated. Pass an "id" so a layout + child pushing the same script ` +
+        `inject it only once.`,
+    );
+  }
+  if (c.async && c.defer) {
+    console.warn(
+      `[Script] A config has both "async" and "defer"; they are mutually ` +
+        `exclusive.`,
+    );
+  }
+}
+
+/**
+ * Accumulate scripts across matched segments, parent -> child, preserving push
+ * order, last-push-wins per dedup key (mirroring the Meta handle).
+ *
+ * Dedup key:
+ * - async resources key by `src` ONLY — React itself dedups async scripts by src,
+ *   so two async configs with different ids but the same src must collapse to one
+ *   here (last wins) for a single, deterministic winner; otherwise React would
+ *   silently pick one with undefined attribute precedence.
+ * - everything else keys by `id ?? src`.
+ *
+ * An (untyped) inline script with neither `id` nor `src` cannot be deduplicated;
+ * it is kept and validateConfigDev warns.
+ */
+function collectScripts(segments: ScriptConfig[][]): ScriptConfig[] {
+  const result: ScriptConfig[] = [];
+  const keyToIndex = new Map<string, number>();
+
+  for (const configs of segments) {
+    for (const config of configs) {
+      validateConfigDev(config);
+      const isAsyncResource = config.src != null && config.async === true;
+      const key = isAsyncResource ? config.src : (config.id ?? config.src);
+      if (key === undefined) {
+        result.push(config);
+        continue;
+      }
+      const existing = keyToIndex.get(key);
+      if (existing !== undefined) {
+        result[existing] = config;
+      } else {
+        keyToIndex.set(key, result.length);
+        result.push(config);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Built-in handle for injecting scripts. Uses an explicit stable id (built-ins
+ * do not rely on the Vite id-injection plugin, which only covers consumer code).
+ */
+export const Script: Handle<ScriptConfig, ScriptConfig[]> = createHandle<
+  ScriptConfig,
+  ScriptConfig[]
+>(collectScripts, "__rsc_router_script__");

package/src/host/cookie-handler.ts

@@ -1,9 +1,3 @@
-/**
- * Cookie Override Handler
- *
- * Manages cookie-based host override for development environments.
- */
-
 import type { HostOverrideConfig } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import { matchPattern, parseRequest } from "./pattern-matcher.js";
@@ -12,52 +6,21 @@ import {
   InvalidHostnameError,
   HostValidationError,
 } from "./errors.js";
+import { parseCookiesFromHeader } from "../server/cookie-parse.js";
 
-/**
- * Parse cookies from request
- */
 export function parseCookies(request: Request): Record<string, string> {
-  const cookieHeader = request.headers.get("cookie");
-  if (!cookieHeader) {
-    return {};
-  }
-
-  const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
-
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name && rest.length > 0) {
-      const value = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(value);
-      } catch {
-        cookies[name] = value;
-      }
-    }
-  }
-
-  return cookies;
+  return parseCookiesFromHeader(request.headers.get("cookie"));
 }
 
-/**
- * Get cookie value from request
- */
 export function getCookie(request: Request, name: string): string | undefined {
   const cookies = parseCookies(request);
   return cookies[name];
 }
 
-/**
- * Create Set-Cookie header to delete a cookie
- */
 export function createDeleteCookieHeader(name: string): string {
   return `${name}=; Max-Age=0; Path=/; Secure; HttpOnly`;
 }
 
-/**
- * Create error response with cookie deletion
- */
 export function createCookieErrorResponse(
   cookieName: string,
   message: string,
@@ -77,9 +40,6 @@ export function createCookieErrorResponse(
   );
 }
 
-/**
- * Check if current host is allowed to use override
- */
 export function isHostAllowed(
   request: Request,
   allowedHosts: string[],
@@ -95,12 +55,6 @@ export function isHostAllowed(
   return false;
 }
 
-/**
- * Handle cookie override logic
- *
- * Returns overridden hostname if valid, original hostname if no override.
- * Throws errors for invalid overrides.
- */
 export function handleCookieOverride(
   request: Request,
   config: HostOverrideConfig | undefined,
@@ -115,51 +69,46 @@ export function handleCookieOverride(
   const cookieValue = getCookie(request, cookieName);
   const { hostname: originalHostname } = parseRequest(request);
 
-  // No cookie - return original hostname
   if (!cookieValue) {
     return originalHostname;
   }
 
-  // Check if current host is allowed
   const allowed = isHostAllowed(request, allowedHosts);
 
-  // If not allowed, throw error
   if (!allowed) {
     throw new HostOverrideNotAllowedError(originalHostname, cookieName, {
       cause: { cookieValue, currentHost: originalHostname },
     });
   }
 
-  // If allowed and has custom validation, run it
   if (validate) {
     try {
       const validatedHostname = validate(request, cookieValue, input);
       return validatedHostname;
     } catch (error) {
-      // Wrap in HostValidationError
       const message = error instanceof Error ? error.message : String(error);
       throw new HostValidationError(message, error);
     }
   }
 
-  // Default validation - verify it's a valid hostname using URL constructor
+  // URL.hostname ASCII-lowercases the host, so compare the cookie value against
+  // its canonical lowercase form (a mixed-case host is valid) and reject only
+  // when it carries a path/port. Return the canonical host so downstream
+  // matching, which assumes lowercase, sees a consistent value.
   try {
-    // Try to construct a URL with the hostname to validate it
     const testUrl = new URL(`https://${cookieValue}`);
 
-    // Ensure the hostname matches what we provided (URL constructor normalizes it)
-    if (testUrl.hostname !== cookieValue) {
+    if (testUrl.hostname !== cookieValue.toLowerCase()) {
       throw new InvalidHostnameError(cookieValue, {
         cause: { original: cookieValue, normalized: testUrl.hostname },
       });
     }
+
+    return testUrl.hostname;
   } catch (error) {
-    // If URL constructor failed, throw InvalidHostnameError with cause
     if (error instanceof InvalidHostnameError) {
       throw error;
     }
     throw new InvalidHostnameError(cookieValue, { cause: error });
   }
-
-  return cookieValue;
 }

package/src/host/errors.ts

@@ -4,16 +4,10 @@
  * All host router errors extend HostRouterError for easy instance checking.
  */
 
-/**
- * Error options with cause
- */
 interface ErrorOptions {
   cause?: unknown;
 }
 
-/**
- * Base error class for all host router errors
- */
 export class HostRouterError extends Error {
   cause?: unknown;
 
@@ -27,9 +21,6 @@ export class HostRouterError extends Error {
   }
 }
 
-/**
- * Error thrown when pattern validation fails
- */
 export class InvalidPatternError extends HostRouterError {
   constructor(pattern: string, reason: string, options?: ErrorOptions) {
     super(`Invalid pattern "${pattern}": ${reason}`, options);
@@ -38,9 +29,6 @@ export class InvalidPatternError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when cookie override is not allowed
- */
 export class HostOverrideNotAllowedError extends HostRouterError {
   constructor(currentHost: string, cookieName: string, options?: ErrorOptions) {
     super(
@@ -52,9 +40,6 @@ export class HostOverrideNotAllowedError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when cookie hostname is invalid
- */
 export class InvalidHostnameError extends HostRouterError {
   constructor(hostname: string, options?: ErrorOptions) {
     super(`Invalid hostname format: "${hostname}"`, options);
@@ -63,9 +48,6 @@ export class InvalidHostnameError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when custom validation fails
- */
 export class HostValidationError extends HostRouterError {
   constructor(message: string, cause?: unknown) {
     super(message, { cause });
@@ -74,9 +56,6 @@ export class HostValidationError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when no route matches
- */
 export class NoRouteMatchError extends HostRouterError {
   constructor(hostname: string, pathname: string, options?: ErrorOptions) {
     super(`No route matched for ${hostname}${pathname}`, options);
@@ -85,9 +64,6 @@ export class NoRouteMatchError extends HostRouterError {
   }
 }
 
-/**
- * Error thrown when handler type is invalid
- */
 export class InvalidHandlerError extends HostRouterError {
   constructor(handler: unknown, options?: ErrorOptions) {
     super(`Invalid handler type: ${typeof handler}`, options);