@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.26

package/src/search-params.ts

@@ -55,14 +55,22 @@ type Simplify<T> = { [K in keyof T]: T[K] };
 /**
  * Resolve a SearchSchema to its typed object.
  *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
  * @example
  * type S = { q: "string"; page: "number?"; sort: "string?" };
  * type R = ResolveSearchSchema<S>;
- * // { q: string; page?: number; sort?: string }
+ * // { q: string | undefined; page?: number; sort?: string }
  */
 export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
   {
-    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
   } & {
     [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
   }
@@ -166,7 +174,9 @@ type ExtractParamsFromPattern<T extends string> =
  * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
- * Missing required params are set to their zero value (empty string / 0 / false).
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
  */
 export function parseSearchParams<T extends SearchSchema>(
   searchParams: URLSearchParams,
@@ -180,13 +190,7 @@ export function parseSearchParams<T extends SearchSchema>(
     const raw = searchParams.get(key);
 
     if (raw === null) {
-      if (!isOptional) {
-        // Required param missing: use zero value
-        if (baseType === "string") result[key] = "";
-        else if (baseType === "number") result[key] = 0;
-        else if (baseType === "boolean") result[key] = false;
-      }
-      // Optional params are omitted (undefined)
+      // Missing params are omitted (undefined) regardless of required/optional
       continue;
     }
 
@@ -194,11 +198,10 @@ export function parseSearchParams<T extends SearchSchema>(
       result[key] = raw;
     } else if (baseType === "number") {
       const num = Number(raw);
-      if (Number.isNaN(num)) {
-        if (!isOptional) result[key] = 0;
-      } else {
+      if (!Number.isNaN(num)) {
         result[key] = num;
       }
+      // NaN treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }

package/src/types/route-config.ts

@@ -24,17 +24,26 @@ type ParseConstraint<T extends string> =
  * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
  */
 type ExtractParamInfo<T extends string> =
-  // Optional + constrained: :param(a|b)?
-  T extends `${infer Name}(${infer Constraint})?`
+  // Optional + constrained (with optional suffix): :param(a|b)?suffix
+  T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
-    : // Constrained only: :param(a|b)
-      T extends `${infer Name}(${infer Constraint})`
+    : // Constrained (with optional suffix): :param(a|b)suffix
+      T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : // Optional only: :param?
-        T extends `${infer Name}?`
+      : // Optional (with optional suffix): :param?suffix
+        T extends `${infer Name}?${string}`
         ? { name: Name; optional: true; type: string }
-        : // Required: :param
-          { name: T; optional: false; type: string };
+        : // Param with dot-suffix: :param.html
+          T extends `${infer Name}.${string}`
+          ? { name: Name; optional: false; type: string }
+          : // Param with dash-suffix: :param-slug
+            T extends `${infer Name}-${string}`
+            ? { name: Name; optional: false; type: string }
+            : // Param with tilde-suffix: :param~v2
+              T extends `${infer Name}~${string}`
+              ? { name: Name; optional: false; type: string }
+              : // Required: :param (no suffix)
+                { name: T; optional: false; type: string };
 
 /**
  * Build param object from info

package/src/types/segments.ts

@@ -124,11 +124,6 @@ export interface MatchResult {
    * Used by ctx.reverse() for local name resolution.
    */
   routeName?: string;
-  /**
-   * Server-Timing header value (only present when debugPerformance is enabled)
-   * Can be added to response headers for DevTools integration
-   */
-  serverTiming?: string;
   /**
    * State of named slots for this route match
    * Key is slot name (e.g., "@modal"), value is slot state

package/src/vite/index.ts

@@ -1,12 +1,13 @@
 /**
  * Public API for @rangojs/router/vite
  *
- * Only the rango() plugin factory and its option types are part of the
- * public API. All other utilities are internal implementation details
- * consumed via direct imports within the package.
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
  */
 
 export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
 
 export type {
   RangoNodeOptions,

package/src/vite/plugins/refresh-cmd.ts

@@ -0,0 +1,65 @@
+import type { Plugin } from "vite";
+
+/**
+ * Vite plugin that triggers a full browser reload when Ctrl+R is pressed
+ * in the terminal running the dev server.
+ *
+ * Usage:
+ * ```ts
+ * import { poke } from "@rangojs/router/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [rango(), poke()],
+ * });
+ * ```
+ */
+export function poke(): Plugin {
+  return {
+    name: "vite-plugin-poke",
+    apply: "serve",
+
+    configureServer(server) {
+      const stdin = process.stdin;
+
+      // Raw mode delivers individual keystrokes as immediate single-byte
+      // events instead of waiting for Enter (cooked/line-buffered mode).
+      // Without it, Ctrl+R (0x12) is never delivered as a discrete byte.
+      // When stdin is a pipe (CI, spawned process) setRawMode is unavailable
+      // but data already arrives unbuffered, so the isTTY guard suffices.
+      const previousRawMode = stdin.isTTY ? stdin.isRaw : null;
+      if (stdin.isTTY) {
+        stdin.setRawMode(true);
+      }
+
+      const onData = (data: Buffer) => {
+        if (data.length !== 1) return;
+
+        // Ctrl+C (0x03) — defensive fallback. This plugin enables raw mode
+        // before Vite's internal stdin handler is registered (user plugins
+        // run first), so there is a brief window where Ctrl+C would be
+        // swallowed. Re-emit SIGINT so the process exits as expected.
+        if (data[0] === 0x03) {
+          process.emit("SIGINT", "SIGINT");
+          return;
+        }
+
+        // Ctrl+R = 0x12 in raw mode
+        if (data[0] === 0x12) {
+          server.hot.send({ type: "full-reload", path: "*" });
+          server.config.logger.info("  browser reload (ctrl+r)", {
+            timestamp: true,
+          });
+        }
+      };
+
+      stdin.on("data", onData);
+
+      server.httpServer?.on("close", () => {
+        stdin.off("data", onData);
+        if (stdin.isTTY && previousRawMode !== null) {
+          stdin.setRawMode(previousRawMode);
+        }
+      });
+    },
+  };
+}