@rangojs/router 0.24.2 → 0.24.4

package/src/server/context.ts

@@ -445,6 +445,53 @@ function bumpCounter(store: HelperContext, key: string): number {
   return store.counters[key]++;
 }
 
+type ShortCodeType = "layout" | "parallel" | "route" | "loader" | "cache";
+
+/**
+ * The next shortCode of `type` under the store's parent, which `take`
+ * consumes; a peek may look `ahead` past it. A root entry is prefixed with the
+ * mount index and counted per mount. A child is counted per parent with
+ * includeScope appended: while a lazy include's direct children evaluate,
+ * includeScope is a per-include token like "I0" / "I1I0" that partitions the
+ * parent's counter namespace so routes inside one include cannot collide with
+ * siblings declared outside it.
+ */
+function nextShortCode(
+  store: HelperContext,
+  type: ShortCodeType,
+  take: boolean,
+  ahead = 0,
+): string {
+  const parent = store.parent;
+  const prefix = SHORT_CODE_PREFIX[type];
+  const mountPrefix =
+    store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
+  const includeScope = store.includeScope ?? "";
+  const counterKey = parent
+    ? `${parent.shortCode}${includeScope}_${type}`
+    : mountPrefix
+      ? `${mountPrefix}_root_${type}`
+      : `root_${type}`;
+  const index = take
+    ? bumpCounter(store, counterKey)
+    : (store.counters[counterKey] ?? 0) + ahead;
+  return parent
+    ? `${parent.shortCode}${includeScope}${prefix}${index}`
+    : `${mountPrefix}${prefix}${index}`;
+}
+
+/**
+ * The shortCode the `ahead`-th next `getShortCode(type)` call in this DSL
+ * context returns, without taking it. clientUrls() materialization reads the
+ * code of every group route this way, including the routes an evaluation for
+ * another route skips (client-urls/layout-loader-copies.ts).
+ */
+export function peekShortCode(type: ShortCodeType, ahead: number): string {
+  const store = RangoContext.getStore();
+  invariant(store, "No context RangoContext available");
+  return nextShortCode(store, type, false, ahead);
+}
+
 export const getContext = (): {
   context: AsyncLocalStorage<HelperContext>;
   getStore: () => HelperContext;
@@ -522,29 +569,7 @@ export const getContext = (): {
     ) => {
       const store = context.getStore();
       invariant(store, "No context RangoContext available");
-
-      const parent = store.parent;
-      const prefix = SHORT_CODE_PREFIX[type];
-      const mountPrefix =
-        store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
-
-      const includeScope = store.includeScope ?? "";
-
-      if (!parent) {
-        // Root entry: prefix with mount index and use mount-scoped counter
-        const counterKey = mountPrefix
-          ? `${mountPrefix}_root_${type}`
-          : `root_${type}`;
-        return `${mountPrefix}${prefix}${bumpCounter(store, counterKey)}`;
-      } else {
-        // Child entry: use parent-scoped counter with includeScope appended.
-        // When we're evaluating a lazy include's direct children, includeScope
-        // is a per-include token like "I0" / "I1I0" that partitions the
-        // parent's counter namespace so routes inside one include cannot
-        // collide with siblings declared outside it.
-        const counterKey = `${parent.shortCode}${includeScope}_${type}`;
-        return `${parent.shortCode}${includeScope}${prefix}${bumpCounter(store, counterKey)}`;
-      }
+      return nextShortCode(store, type, true);
     },
     runWithStore: <T>(
       store: HelperContext,

package/src/ssr/index.tsx

@@ -403,6 +403,62 @@ function trackDocumentClientLoads<T>(decode: () => T): {
   };
 }
 
+/**
+ * Cap on settleSsrFalseFirstFlush's turns. Each turn retries one generation of
+ * tasks parked on thenables that settle in microtasks. A useActionState form
+ * is one generation (the Flight client caches the encoding, so the retry
+ * encodes synchronously); a formAction button inside it renders on that retry
+ * and is a second; the same form behind `lazy()` adds a third. ssr-handler
+ * tests pin all three. A deeper chain flushes its fallback as before.
+ */
+const SSR_FALSE_FIRST_FLUSH_TURNS = 3;
+
+/**
+ * True when the matched chain has a `loader(Def, { ssr: false })` entry: its
+ * payload segments carry `awaitBeforeFlush` (fresh.ts).
+ */
+function hasAwaitBeforeFlush(payload: {
+  metadata?: { segments?: readonly { awaitBeforeFlush?: true }[] };
+}): boolean {
+  return payload.metadata?.segments?.some((s) => s.awaitBeforeFlush) === true;
+}
+
+/**
+ * ssr: false documents only: before the first flush, give Fizz the turns a
+ * task waiting on an already-settling thenable needs, so a boundary that
+ * waits on nothing else completes in place (#1138).
+ *
+ * Fizz's useActionState binds its state onto the action, and the
+ * `<form action>` encode of that bound server reference throws the Flight
+ * client's encodeFormData thenable once (defaultEncodeFormAction). It settles
+ * in microtasks, but once the request has left its opening status, Fizz's
+ * pingTask retries the task on a setTimeout(0) turn. renderToReadableStream
+ * resolves at shell-ready, so the first read would flush the boundary's
+ * fallback before that turn, which a browser without JavaScript keeps (the
+ * form lands in `<div hidden id="S:n">`).
+ *
+ * A document already whole (allReady settled) returns with no macrotask.
+ * Otherwise one setTimeout(0) at a time until allReady, at most
+ * SSR_FALSE_FIRST_FLUSH_TURNS: a timer set after Fizz's ping fires after it.
+ * A boundary waiting on I/O (an unflagged loader, a streamed promise) still
+ * streams its fallback, after at most that many turns.
+ */
+async function settleSsrFalseFirstFlush(
+  allReady: Promise<void>,
+): Promise<void> {
+  let whole = false;
+  const settle = (): void => {
+    whole = true;
+  };
+  // Promise.resolve: a stub renderer's stream may carry no allReady.
+  Promise.resolve(allReady).then(settle, settle);
+  // A settled allReady's reaction was queued before this continuation's.
+  await Promise.resolve();
+  for (let turn = 0; !whole && turn < SSR_FALSE_FIRST_FLUSH_TURNS; turn++) {
+    await macrotask();
+  }
+}
+
 /**
  * Route an SSR error through the deps.onError notification callback with the
  * "rendering" phase. Swallows callback failures so a broken reporter never
@@ -832,13 +888,10 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
       // <html> until this same promise settles. A rejection lands in the
       // catch below — the same reportRenderError path a shell error takes.
-      let progressiveChunkSize = deps.progressiveChunkSize;
-      if (progressiveChunkSize === undefined) {
-        const resolved = await payload;
-        if (resolved.metadata?.segments?.some((s) => s.awaitBeforeFlush)) {
-          progressiveChunkSize = Number.MAX_SAFE_INTEGER;
-        }
-      }
+      const awaitsBeforeFlush = hasAwaitBeforeFlush(await payload);
+      const progressiveChunkSize =
+        deps.progressiveChunkSize ??
+        (awaitsBeforeFlush ? Number.MAX_SAFE_INTEGER : undefined);
 
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
@@ -870,6 +923,9 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // cannot process streamed HTML.
       if (streamMode === "allReady") {
         await htmlStream.allReady;
+      } else if (awaitsBeforeFlush) {
+        // The shell rendered from the payload, so it has settled.
+        await settleSsrFalseFirstFlush(htmlStream.allReady);
       }
 
       // The entry's Fizz hint at default priority, after the head chunk

package/src/urls/path-helper.ts

@@ -54,6 +54,21 @@ function applyNamePrefix(prefix: string | undefined, name: string): string {
   return `${prefix}.${name}`;
 }
 
+/**
+ * The key path() registers a route under: its name, or a `$path_` name built
+ * from its pattern, behind the include's name prefix.
+ */
+export function routeKeyOf(
+  namePrefix: string | undefined,
+  pattern: string,
+  name: string | undefined,
+): string {
+  return applyNamePrefix(
+    namePrefix,
+    name || `$path_${pattern.replace(/[/:*?]/g, "_")}`,
+  );
+}
+
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
@@ -143,12 +158,10 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
 
     const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
 
-    const localName =
-      options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    const routeName = applyNamePrefix(namePrefix, localName);
+    const routeName = routeKeyOf(namePrefix, pattern, options?.name);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;