pastoria 1.1.0 → 1.2.1

package/templates/router.tsx

@@ -5,7 +5,7 @@ import {
   RouterOps,
 } from 'pastoria-runtime';
 import {createRouter} from 'radix3';
-import {
+import React, {
   AnchorHTMLAttributes,
   createContext,
   PropsWithChildren,
@@ -16,6 +16,7 @@ import {
   useEffect,
   useMemo,
   useState,
+  useTransition,
 } from 'react';
 import {preinit, preloadModule} from 'react-dom';
 import {
@@ -25,12 +26,17 @@ import {
   RelayEnvironmentProvider,
   useEntryPointLoader,
 } from 'react-relay/hooks';
+import {PreloadableQueryRegistry} from 'relay-runtime';
 import * as z from 'zod/v4-mini';
 
 type RouterConf = typeof ROUTER_CONF;
+type AnyRouteParams = z.infer<RouterConf[keyof RouterConf]['schema']>;
+type AnyRouteEntryPoint = RouterConf[keyof RouterConf]['entrypoint'];
+type LoadEntryPointFn = (params: {params: AnyRouteParams}) => void;
+
 const ROUTER_CONF = {
   noop: {
-    entrypoint: null! as EntryPoint<any>,
+    entrypoint: null! as EntryPoint<any, any>,
     schema: z.object({}),
   },
 } as const;
@@ -39,12 +45,77 @@ export type RouteId = keyof RouterConf;
 export type NavigationDirection = string | URL | ((nextUrl: URL) => void);
 
 export interface EntryPointParams<R extends RouteId> {
-  params: Record<string, any>;
-  schema: RouterConf[R]['schema'];
+  params: z.infer<RouterConf[R]['schema']>;
+  queries: QueryHelpersForRoute<R>;
+  entryPoints: EntryPointHelpersForRoute<R>;
 }
 
+/**
+ * Load a route entry point with proper typing.
+ *
+ * This wrapper exists because TypeScript struggles with union type inference
+ * when calling loadEntryPoint with a union of entry point types. All route
+ * entry points accept {params: Record<string, unknown>}, so this is safe.
+ */
+function loadRouteEntryPoint(
+  provider: EnvironmentProvider,
+  entrypoint: AnyRouteEntryPoint,
+  params: {params: AnyRouteParams},
+) {
+  // Cast needed because Relay's loadEntryPoint infers params from the entry point type.
+  // When entrypoint is a union, the inferred params become an intersection (contravariance),
+  // which resolves to `never`. Our entry points all accept the same params shape, so this is safe.
+  return loadEntryPoint(
+    provider,
+    entrypoint as unknown as EntryPoint<unknown, {params: AnyRouteParams}>,
+    params,
+  );
+}
+
+// Convert bracket format [param] to colon format :param for radix3 router
+function bracketToColon(path: string): string {
+  // Convert required params [param] to :param
+  // Note: optional params [[param]] are handled separately by expandOptionalRoutes
+  return path.replace(/\[([^\]]+)\]/g, ':$1');
+}
+
+// Expand routes with optional params into multiple routes
+// e.g., /greet/[[name]] becomes ['/greet', '/greet/:name']
+function expandOptionalRoutes(
+  routePath: string,
+  config: RouterConf[keyof RouterConf],
+): Array<[string, RouterConf[keyof RouterConf]]> {
+  // Check if route has optional params
+  const optionalMatch = routePath.match(/\/\[\[([^\]]+)\]\]/g);
+  if (!optionalMatch) {
+    // No optional params, just convert brackets to colons
+    return [[bracketToColon(routePath), config]];
+  }
+
+  // For routes with optional params, create two routes:
+  // 1. Without the optional segment (e.g., /greet)
+  // 2. With the optional segment as required (e.g., /greet/:name)
+  const withoutOptional = routePath.replace(/\/\[\[([^\]]+)\]\]/g, '');
+  const withOptional = routePath.replace(/\[\[([^\]]+)\]\]/g, '[$1]');
+
+  const routes: Array<[string, RouterConf[keyof RouterConf]]> = [];
+
+  // Add the route without optional param (handles /greet)
+  const pathWithout = bracketToColon(withoutOptional) || '/';
+  routes.push([pathWithout, config]);
+
+  // Add the route with optional param as required (handles /greet/:name)
+  routes.push([bracketToColon(withOptional), config]);
+
+  return routes;
+}
+
+// Create radix3 router with colon-format paths (radix3 uses :param syntax)
+// Routes with optional params are expanded into multiple routes
 const ROUTER = createRouter<RouterConf[keyof RouterConf]>({
-  routes: ROUTER_CONF,
+  routes: Object.fromEntries(
+    Object.entries(ROUTER_CONF).flatMap(([k, v]) => expandOptionalRoutes(k, v)),
+  ) as Record<string, RouterConf[keyof RouterConf]>,
 });
 
 class RouterLocation {
@@ -66,7 +137,7 @@ class RouterLocation {
     return ROUTER.lookup(this.pathname);
   }
 
-  params() {
+  params(): AnyRouteParams {
     const matchedRoute = this.route();
     const params = {
       ...matchedRoute?.params,
@@ -76,7 +147,7 @@ class RouterLocation {
     if (matchedRoute?.schema) {
       return matchedRoute.schema.parse(params);
     } else {
-      return params;
+      return params as AnyRouteParams;
     }
   }
 
@@ -127,6 +198,15 @@ export function router__hydrateStore(provider: EnvironmentProvider) {
   if ('__router_ops' in window) {
     const ops = (window as any).__router_ops as RouterOps;
     for (const [op, payload] of ops) {
+      // Register the ConcreteRequest with PreloadableQueryRegistry so that
+      // loadQuery can find it and check store availability instead of
+      // immediately fetching. This is critical for nested entry points whose
+      // query modules haven't been loaded yet.
+      const concreteRequest = op.request?.node;
+      const queryId = concreteRequest?.params?.id;
+      if (queryId && concreteRequest) {
+        PreloadableQueryRegistry.set(queryId, concreteRequest);
+      }
       env.commitPayload(op, payload);
     }
   }
@@ -142,10 +222,32 @@ export async function router__loadEntryPoint(
   if (!initialRoute) return null;
 
   await initialRoute.entrypoint?.root.load();
-  return loadEntryPoint(provider, initialRoute.entrypoint, {
+  const ep = loadRouteEntryPoint(provider, initialRoute.entrypoint, {
     params: initialLocation.params(),
-    schema: initialRoute.schema,
   });
+
+  // Recursively load all nested entry point modules.
+  // This ensures their queries get registered in PreloadableQueryRegistry
+  // before the server tries to serialize them.
+  await loadNestedEntryPointModules(ep);
+
+  return ep;
+}
+
+/**
+ * Recursively load all nested entry point modules so their queries
+ * get registered in PreloadableQueryRegistry.
+ */
+async function loadNestedEntryPointModules(
+  entryPoint: AnyPreloadedEntryPoint | null,
+): Promise<void> {
+  if (!entryPoint) return;
+  for (const nestedEntry of Object.values(entryPoint.entryPoints ?? {})) {
+    if (nestedEntry.rootModuleID) {
+      await JSResource.fromModuleId(nestedEntry.rootModuleID as any).load();
+    }
+    await loadNestedEntryPointModules(nestedEntry);
+  }
 }
 
 interface RouterContextValue {
@@ -229,13 +331,11 @@ export function router__createAppFromEntryPoint(
       location.route()?.entrypoint,
     );
 
-    useEffect(() => {
-      const schema = location.route()?.schema;
-      if (schema) {
-        loadEntryPointRef({
-          params: location.params(),
-          schema,
-        });
+    useMemo(() => {
+      const route = location.route();
+      if (route) {
+        // Cast needed for same reason as loadRouteEntryPoint - see that function's docs
+        (loadEntryPointRef as LoadEntryPointFn)({params: location.params()});
       }
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [location]);
@@ -296,7 +396,7 @@ export function useRouteParams<R extends RouteId>(
 
 function router__createPathForRoute(
   routeId: RouteId,
-  inputParams: Record<string, any>,
+  inputParams: Record<string, unknown>,
 ): string {
   const schema = ROUTER_CONF[routeId].schema;
   const params = schema.parse(inputParams);
@@ -305,19 +405,47 @@ function router__createPathForRoute(
   const searchParams = new URLSearchParams();
 
   Object.entries(params).forEach(([key, value]) => {
-    if (value != null) {
-      const paramPattern = `:${key}`;
-      if (pathname.includes(paramPattern)) {
+    // Check for optional param pattern first: [[key]]
+    const optionalPattern = `[[${key}]]`;
+    if (pathname.includes(optionalPattern)) {
+      if (value != null) {
         pathname = pathname.replace(
-          paramPattern,
+          optionalPattern,
           encodeURIComponent(String(value)),
         );
       } else {
-        searchParams.set(key, String(value));
+        // Remove the optional segment entirely (including the preceding slash if present)
+        pathname = pathname.replace(`/${optionalPattern}`, '');
+        pathname = pathname.replace(optionalPattern, '');
       }
+      return;
+    }
+
+    // Check for required param pattern: [key]
+    const paramPattern = `[${key}]`;
+    if (pathname.includes(paramPattern)) {
+      if (value != null) {
+        pathname = pathname.replace(
+          paramPattern,
+          encodeURIComponent(String(value)),
+        );
+      }
+      return;
+    }
+
+    // Not a path param, add to search params if non-null
+    if (value != null) {
+      searchParams.set(key, String(value));
     }
   });
 
+  // Clean up any double slashes that might result
+  pathname = pathname.replace(/\/+/g, '/');
+  // Ensure we don't end up with empty path
+  if (pathname === '') {
+    pathname = '/';
+  }
+
   if (searchParams.size > 0) {
     return pathname + '?' + searchParams.toString();
   } else {
@@ -349,49 +477,64 @@ function router__evaluateNavigationDirection(nav: NavigationDirection) {
 
 export function useNavigation() {
   const {setLocation} = useContext(RouterContext);
+  const [isPending, startTransition] = useTransition();
 
   return useMemo(() => {
     function push(nav: NavigationDirection) {
-      setLocation(
-        RouterLocation.parse(router__evaluateNavigationDirection(nav), 'push'),
-      );
+      startTransition(() => {
+        setLocation(
+          RouterLocation.parse(
+            router__evaluateNavigationDirection(nav),
+            'push',
+          ),
+        );
+      });
     }
 
     function replace(nav: NavigationDirection) {
-      setLocation(
-        RouterLocation.parse(
-          router__evaluateNavigationDirection(nav),
-          'replace',
-        ),
-      );
+      startTransition(() => {
+        setLocation(
+          RouterLocation.parse(
+            router__evaluateNavigationDirection(nav),
+            'replace',
+          ),
+        );
+      });
     }
 
     function pushRoute<R extends RouteId>(
       routeId: R,
       params: z.input<RouterConf[R]['schema']>,
     ) {
-      setLocation(
-        RouterLocation.parse(
-          router__createPathForRoute(routeId, params),
-          'push',
-        ),
-      );
+      startTransition(() => {
+        setLocation(
+          RouterLocation.parse(
+            router__createPathForRoute(routeId, params),
+            'push',
+          ),
+        );
+      });
     }
 
     function replaceRoute<R extends RouteId>(
       routeId: R,
       params: z.input<RouterConf[R]['schema']>,
     ) {
-      setLocation((prevLoc) =>
-        RouterLocation.parse(
-          router__createPathForRoute(routeId, {...prevLoc.params(), ...params}),
-          'replace',
-        ),
-      );
+      startTransition(() => {
+        setLocation((prevLoc) =>
+          RouterLocation.parse(
+            router__createPathForRoute(routeId, {
+              ...prevLoc.params(),
+              ...params,
+            }),
+            'replace',
+          ),
+        );
+      });
     }
 
-    return {push, replace, pushRoute, replaceRoute} as const;
-  }, [setLocation]);
+    return {push, replace, pushRoute, replaceRoute, isPending} as const;
+  }, [setLocation, isPending]);
 }
 
 export function Link({

package/justfile

@@ -1,41 +0,0 @@
-# Generate schema, relay, and router code.
-[no-cd]
-default: router
-
-# Generate GraphQL schema using Grats
-[no-cd]
-[private]
-grats:
-    pnpm exec grats
-
-# Compile Relay queries with persisted queries
-[no-cd]
-[private]
-relay: grats
-    pnpm exec relay-compiler --repersist
-
-# Generate Pastoria router artifacts (app_root, context, router, resources, handlers)
-[no-cd]
-[private]
-router: relay
-    pnpm exec pastoria gen
-
-# Build client bundle
-[no-cd]
-_client: router
-    pnpm exec pastoria build client
-
-# Build server bundle
-[no-cd]
-_server: router
-    pnpm exec pastoria build server
-
-# Build both client and server for production
-[no-cd]
-[parallel]
-release: _client _server
-
-# Start development server
-[no-cd]
-dev:
-    pnpm exec pastoria dev