@rangojs/router 0.0.0-experimental.2

package/skills/typesafety/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: typesafety
+description: Set up type-safe routes, params, and environment types in rsc-router
+argument-hint: [setup]
+---
+
+# Type Safety Setup
+
+rsc-router provides end-to-end type safety for routes, parameters, and environment.
+
+## Route Type Registration
+
+Register route types globally for type-safe `href()` and params:
+
+```typescript
+// router.tsx
+import { createRSCRouter } from "rsc-router/server";
+import { homeRoutes } from "./routes/home";
+import { shopRoutes } from "./routes/shop";
+
+const _router = createRSCRouter<AppEnv>({ document: Document })
+  .routes(homeRoutes)
+  .map(() => import("./handlers/home"))
+  .routes("/shop", shopRoutes)
+  .map(() => import("./handlers/shop"));
+
+// Extract accumulated route types
+type AppRoutes = typeof _router.routeMap;
+
+// Register globally via module augmentation
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends AppRoutes {}
+  }
+}
+
+export default _router;
+export const href = _router.href;
+```
+
+## Route Definition with Type-Safe Keys
+
+```typescript
+// routes/shop.ts
+import { route } from "rsc-router";
+
+export const shopRoutes = route({
+  "shop.index": "/",
+  "shop.products": "/products",
+  "shop.product": "/products/:slug",
+  "shop.cart": "/cart",
+  "shop.checkout": "/checkout/:step?",
+});
+
+// Type is inferred:
+// {
+//   "shop.index": "/",
+//   "shop.products": "/products",
+//   "shop.product": "/products/:slug",
+//   ...
+// }
+```
+
+## Type-Safe href()
+
+After registration, `href()` has full autocomplete:
+
+```typescript
+import { href } from "./router";
+
+// Autocomplete shows all registered routes
+href("shop.index");                          // "/shop"
+href("shop.products");                       // "/shop/products"
+href("shop.product", { slug: "widget" });    // "/shop/products/widget"
+
+// TypeScript errors for:
+href("invalid.route");                       // Error: not a valid route
+href("shop.product");                        // Error: missing required param 'slug'
+href("shop.product", { wrong: "param" });    // Error: 'wrong' not in params
+```
+
+## Type-Safe Params in Handlers
+
+Params are automatically typed based on route patterns:
+
+```typescript
+// handlers/shop.tsx
+import { map } from "rsc-router/server";
+import type { shopRoutes } from "../routes/shop";
+
+export default map<typeof shopRoutes>(({ route }) => [
+  // ctx.params is typed as { slug: string }
+  route("shop.product", (ctx) => {
+    const { slug } = ctx.params;  // TypeScript knows slug exists
+    return <ProductPage slug={slug} />;
+  }),
+
+  // ctx.params is typed as { step?: string }
+  route("shop.checkout", (ctx) => {
+    const step = ctx.params.step ?? "shipping";  // Optional param
+    return <CheckoutPage step={step} />;
+  }),
+]);
+```
+
+## Environment Type Setup
+
+Define your app's environment for type-safe bindings and variables:
+
+```typescript
+// env.ts
+import type { RouterEnv } from "rsc-router/server";
+
+// Cloudflare bindings
+interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+  CACHE: KVNamespace;
+  AI: Ai;
+}
+
+// Variables set by middleware (ctx.set/ctx.get)
+interface AppVariables {
+  user?: { id: string; email: string; role: string };
+  requestId?: string;
+  permissions?: string[];
+}
+
+// Combined environment type
+export type AppEnv = RouterEnv<AppBindings, AppVariables>;
+```
+
+### Using Environment Types
+
+```typescript
+// router.tsx
+import type { AppEnv } from "./env";
+
+const router = createRSCRouter<AppEnv>({ document: Document })
+  // ...
+
+// middleware - typed ctx.set/ctx.get
+const authMiddleware = async (ctx: MiddlewareContext<AppEnv>, next) => {
+  ctx.set("user", { id: "123", email: "user@example.com", role: "admin" });
+  await next();
+};
+
+// handlers - typed access
+route("dashboard", (ctx) => {
+  const user = ctx.get("user");  // { id: string; email: string; role: string } | undefined
+  const db = ctx.env.Bindings.DB;  // D1Database
+  return <Dashboard user={user} />;
+});
+
+// loaders - typed context
+export const UserLoader = createLoader<AppEnv>(async (ctx) => {
+  const db = ctx.env.Bindings.DB;
+  const userId = ctx.get("user")?.id;
+  return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
+});
+```
+
+## Global Type Registration
+
+Register environment types globally for implicit typing:
+
+```typescript
+// router.tsx
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends AppRoutes {}
+    interface Env extends AppEnv {}
+  }
+}
+```
+
+Now handlers have typed context without explicit imports:
+
+```typescript
+// handlers/dashboard.tsx - no type imports needed
+export default map(({ route }) => [
+  route("dashboard", (ctx) => {
+    // ctx.get("user") is typed from global Env
+    // ctx.params is typed from global RegisteredRoutes
+    const user = ctx.get("user");
+    return <Dashboard user={user} />;
+  }),
+]);
+```
+
+## Route Key Conflict Detection
+
+TypeScript detects duplicate keys with different URL patterns:
+
+```typescript
+// This causes a type error:
+const router = createRSCRouter<AppEnv>({ document: Document })
+  .routes({ index: "/" })
+  .map(() => import("./home"))
+  .routes({ index: "/other" })  // Error! 'index' already exists with different pattern
+  .map(() => import("./other"));
+
+// Error message:
+// Property 'map' does not exist on type '{
+//   __error: "Route key conflict! Keys [index] already exist with different URL patterns.";
+//   hint: "Use unique key names for each route definition.";
+// }'
+```
+
+### Avoiding Conflicts
+
+Use namespaced keys:
+
+```typescript
+// Good - unique keys
+export const homeRoutes = route({ "home.index": "/" });
+export const blogRoutes = route({ "blog.index": "/", "blog.post": "/:slug" });
+
+// router.tsx
+.routes(homeRoutes)
+.map(() => import("./home"))
+.routes("/blog", blogRoutes)  // Keys stay: blog.index, blog.post
+.map(() => import("./blog"))  // URLs become: /blog/, /blog/:slug
+```
+
+## Loader Type Safety
+
+Loaders have typed return values:
+
+```typescript
+// loaders/product.ts
+export const ProductLoader = createLoader(async (ctx) => {
+  return {
+    id: ctx.params.slug,
+    name: "Widget",
+    price: 99,
+  };
+});
+
+// In handler - type is inferred
+route("shop.product", async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  // product: { id: string; name: string; price: number }
+  return <ProductPage product={product} />;
+});
+
+// In client component - same type
+function ProductPrice() {
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  return <span>${data.price}</span>;
+}
+```
+
+## Handle Type Safety
+
+Handles have typed data:
+
+```typescript
+// handles/breadcrumbs.ts
+import { createHandle } from "rsc-router";
+
+export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+
+// In handler - typed push
+route("shop.product", (ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Products", href: "/shop/products" });  // Typed
+  push({ wrong: "data" });  // Error!
+  return <ProductPage />;
+});
+
+// In client - typed array
+function BreadcrumbNav() {
+  const crumbs = useHandle(Breadcrumbs);
+  // crumbs: Array<{ label: string; href: string }>
+}
+```
+
+## Location State Type Safety
+
+```typescript
+// location-states.ts
+import { createLocationState } from "rsc-router";
+
+export const ProductPreview = createLocationState<{
+  name: string;
+  price: number;
+  image: string;
+}>();
+
+// Passing state through Link
+<Link
+  to={href("shop.product", { slug: "widget" })}
+  state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
+>
+  View Product
+</Link>
+
+// Reading state in component
+function ProductHeader() {
+  const preview = useLocationState(ProductPreview);
+  // preview: { name: string; price: number; image: string } | undefined
+
+  if (preview) {
+    return <h1>{preview.name} - ${preview.price}</h1>;
+  }
+  return <h1>Loading...</h1>;
+}
+```
+
+## Complete Type-Safe Setup
+
+```typescript
+// 1. env.ts - Environment types
+export type AppEnv = RouterEnv<AppBindings, AppVariables>;
+
+// 2. routes/*.ts - Route definitions
+export const shopRoutes = route({
+  "shop.index": "/",
+  "shop.product": "/products/:slug",
+});
+
+// 3. router.tsx - Registration
+const _router = createRSCRouter<AppEnv>({ document: Document })
+  .routes(shopRoutes)
+  .map(() => import("./handlers/shop"));
+
+type AppRoutes = typeof _router.routeMap;
+
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends AppRoutes {}
+    interface Env extends AppEnv {}
+  }
+}
+
+export default _router;
+export const href = _router.href;
+
+// 4. handlers/*.tsx - Type-safe handlers
+export default map<typeof shopRoutes>(({ route }) => [
+  route("shop.product", (ctx) => {
+    // ctx.params: { slug: string }
+    // ctx.get("user"): User | undefined
+    // ctx.env.Bindings.DB: D1Database
+  }),
+]);
+
+// 5. components/*.tsx - Type-safe client code
+<Link to={href("shop.product", { slug: "widget" })}>Widget</Link>
+```

package/src/__mocks__/version.ts

@@ -0,0 +1,6 @@
+/**
+ * Mock for rsc-router:version virtual module.
+ * Used by vitest since the virtual module is only available at build time.
+ * Empty string disables version path in URLs for simpler test assertions.
+ */
+export const VERSION = "";

package/src/__tests__/component-utils.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { isClientComponent, assertClientComponent } from "../component-utils";
+
+describe("component-utils", () => {
+  describe("isClientComponent", () => {
+    it("should return false for regular functions", () => {
+      const ServerComponent = () => null;
+      expect(isClientComponent(ServerComponent)).toBe(false);
+    });
+
+    it("should return false for non-functions", () => {
+      expect(isClientComponent(null)).toBe(false);
+      expect(isClientComponent(undefined)).toBe(false);
+      expect(isClientComponent("string")).toBe(false);
+      expect(isClientComponent(123)).toBe(false);
+      expect(isClientComponent({})).toBe(false);
+    });
+
+    it("should return true for functions with client reference marker", () => {
+      const ClientComponent = () => null;
+      // Simulate what the bundler does for "use client" components
+      (ClientComponent as any).$$typeof = Symbol.for("react.client.reference");
+      (ClientComponent as any).$$id = "src/components/MyComponent.tsx#default";
+
+      expect(isClientComponent(ClientComponent)).toBe(true);
+    });
+
+    it("should return false for functions with wrong $$typeof symbol", () => {
+      const Component = () => null;
+      (Component as any).$$typeof = Symbol.for("react.element");
+
+      expect(isClientComponent(Component)).toBe(false);
+    });
+  });
+
+  describe("assertClientComponent", () => {
+    it("should throw for non-function values", () => {
+      expect(() => assertClientComponent(null, "document")).toThrow(
+        'document must be a client component function with "use client" directive'
+      );
+
+      expect(() => assertClientComponent({}, "document")).toThrow(
+        'document must be a client component function with "use client" directive'
+      );
+    });
+
+    it("should throw for server components (no client marker)", () => {
+      const ServerComponent = () => null;
+
+      expect(() => assertClientComponent(ServerComponent, "document")).toThrow(
+        'document must be a client component with "use client" directive'
+      );
+      expect(() => assertClientComponent(ServerComponent, "document")).toThrow(
+        "cannot be serialized in the RSC payload"
+      );
+    });
+
+    it("should not throw for client components", () => {
+      const ClientComponent = () => null;
+      (ClientComponent as any).$$typeof = Symbol.for("react.client.reference");
+      (ClientComponent as any).$$id = "src/document.tsx#default";
+
+      expect(() =>
+        assertClientComponent(ClientComponent, "document")
+      ).not.toThrow();
+    });
+
+    it("should include component name in error message", () => {
+      const ServerComponent = () => null;
+
+      expect(() => assertClientComponent(ServerComponent, "myLayout")).toThrow(
+        "myLayout must be a client component"
+      );
+    });
+  });
+});

package/src/__tests__/route-definition.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { route } from "../route-definition";
+
+describe("route()", () => {
+  describe("with nested RouteConfig objects", () => {
+    it("should flatten nested RouteConfig with trailing slash config", () => {
+      const routes = route({
+        index: "/",
+        trailingSlash: {
+          ignore: { path: "/ts-ignore", trailingSlash: "ignore" },
+          always: { path: "/ts-always", trailingSlash: "always" },
+          never: { path: "/ts-never", trailingSlash: "never" },
+        },
+      }) as any;
+
+      // Check routes are flattened correctly
+      expect(routes.index).toBe("/");
+      expect(routes["trailingSlash.ignore"]).toBe("/ts-ignore");
+      expect(routes["trailingSlash.always"]).toBe("/ts-always");
+      expect(routes["trailingSlash.never"]).toBe("/ts-never");
+
+      // Check trailing slash config is attached
+      expect(routes.__trailingSlash).toBeDefined();
+      expect(routes.__trailingSlash["trailingSlash.ignore"]).toBe("ignore");
+      expect(routes.__trailingSlash["trailingSlash.always"]).toBe("always");
+      expect(routes.__trailingSlash["trailingSlash.never"]).toBe("never");
+    });
+
+    it("should be enumerable for Object.entries", () => {
+      const routes = route({
+        index: "/",
+        trailingSlash: {
+          ignore: { path: "/ts-ignore", trailingSlash: "ignore" },
+        },
+      });
+
+      const entries = Object.entries(routes);
+      expect(entries).toContainEqual(["index", "/"]);
+      expect(entries).toContainEqual(["trailingSlash.ignore", "/ts-ignore"]);
+    });
+
+    it("should apply global default to string routes", () => {
+      const routes = route({
+        blog: "/blog",
+        about: "/about",
+      }, { trailingSlash: "never" }) as any;
+
+      expect(routes.__trailingSlash).toBeDefined();
+      expect(routes.__trailingSlash.blog).toBe("never");
+      expect(routes.__trailingSlash.about).toBe("never");
+    });
+
+    it("should let per-route config override global default", () => {
+      const routes = route({
+        blog: "/blog",
+        api: { path: "/api", trailingSlash: "ignore" },
+      }, { trailingSlash: "never" }) as any;
+
+      expect(routes.__trailingSlash.blog).toBe("never");
+      expect(routes.__trailingSlash.api).toBe("ignore");
+    });
+  });
+});