@rangojs/router 0.10.1 → 0.12.0

package/src/client-urls/types.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactNode } from "react";
 import type {
+  IsActionFn,
   LoaderDefinition,
   LoaderOptions,
   TransitionConfig,
@@ -54,7 +55,8 @@ export type ClientLayoutFn = <const TItems extends ClientUrlItems>(
  * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
  * BROWSER (it is declared in a "use client" module and never crosses the
  * projection boundary); only its decision is sent to the server. There is no
- * `context` — no server handler context exists where this executes.
+ * `context` — no server handler context exists where this executes. `isAction`
+ * is the same callable matcher as on the server, not a boolean.
  */
 export interface ClientRevalidateArgs {
   /** Full URL of the page being navigated away from (current location). */
@@ -66,21 +68,46 @@ export interface ClientRevalidateArgs {
   /** Route params for the navigation target (definition-local match). */
   readonly nextParams: Record<string, string>;
   /**
-   * The locked default decision for this loader, computed client-side with
-   * the same rules the server would apply: `true` on actions and when
-   * params/search changed, `false` otherwise. Return it for default behavior
-   * plus your own conditions.
+   * The current default decision for this loader, computed client-side with
+   * the same rules the server applies to the request the decisions ride on:
+   * `true` when they ride the action POST itself, otherwise `true` when
+   * params/search changed. (An action-triggered refetch GET gets navigation
+   * defaults — matching the server — even though `isAction()` is true.)
+   * Earlier predicates' `{ defaultShouldRevalidate }` verdicts thread into
+   * this value, exactly like the server chain. Return it for default
+   * behavior plus your own conditions.
    */
   readonly defaultShouldRevalidate: boolean;
   /** True when this is a stale history-entry background revalidation. */
   readonly stale: boolean;
-  /** True when revalidation is triggered by a server action. */
-  readonly isAction: boolean;
-  /** The triggering server action's id, when isAction. */
+  /**
+   * Same {@link IsActionFn} the server `revalidate()` predicate receives.
+   * In the browser the match is against the action stub's hashed `$$id`
+   * (the id the action request carries) — not the RSC file-path `$id`.
+   */
+  readonly isAction: IsActionFn;
+  /**
+   * The triggering server action's id, when this is an action. In the
+   * browser this is the hashed `hash#export` form (`$$id`), not the RSC
+   * file-path `src/...#export`. Prefer `isAction(ref)` — a substring of
+   * `path#export` will not match here in production.
+   */
   readonly actionId?: string;
 }
 
-export type ClientRevalidateFn = (args: ClientRevalidateArgs) => boolean;
+/**
+ * Client-run per-loader predicate, with the same chain semantics as the
+ * server's `revalidate()` (src/router/revalidation.ts): a boolean is a HARD
+ * decision that short-circuits the rest of the chain; a
+ * `{ defaultShouldRevalidate }` object updates the running suggestion, which
+ * later predicates receive as their `defaultShouldRevalidate`; `void` /
+ * `null` / `undefined` defers to the current suggestion — so
+ * `isAction(CartActions) || undefined` defers to the locked default.
+ * Predicates must be synchronous; the object form requires a boolean value.
+ */
+export type ClientRevalidateFn = (
+  args: ClientRevalidateArgs,
+) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 export interface ClientUrlLoaderRecord {
   readonly loader: LoaderDefinition<any, any>;
@@ -158,10 +185,11 @@ export interface ClientUrlHelpers {
   readonly loading: (component: ReactNode) => ClientUrlItem;
   /**
    * Per-loader revalidation predicate, valid inside a loader() use callback
-   * only. Runs IN THE BROWSER with client-computable args; return true to
-   * re-run the loader, false to keep held data. Absent predicates (and
-   * requests that carry no decisions: no-JS, PE, prefetch, document loads)
-   * follow the locked server defaults.
+   * only. Runs IN THE BROWSER with client-computable args (including the
+   * callable `isAction(...refs)` matcher); return true to re-run the loader,
+   * false to keep held data. Absent predicates (and requests that carry no
+   * decisions: no-JS, PE, prefetch, document loads) follow the locked server
+   * defaults.
    */
   readonly revalidate: (fn: ClientRevalidateFn) => ClientUrlItem;
   /**

package/src/client.tsx

@@ -470,3 +470,8 @@ export { useReverse } from "./browser/react/use-reverse.js";
 export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 export type { LoaderDefinition } from "./types.js";
+export type { ActionRef, IsActionFn } from "./types.js";
+export type {
+  ClientRevalidateArgs,
+  ClientRevalidateFn,
+} from "./client-urls/types.js";

package/src/deps/rsc-client.ts

@@ -0,0 +1,8 @@
+/// <reference types="@vitejs/plugin-rsc/types" />
+// RSC-environment *client* protocol (deserialize / encodeReply). Kept as its
+// own module so a server-only importer of `./rsc.ts` does not pull this side.
+export {
+  createFromReadableStream,
+  encodeReply,
+  createClientTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/rsc/client";

package/src/deps/rsc.ts

@@ -1,5 +1,7 @@
 /// <reference types="@vitejs/plugin-rsc/types" />
-// Re-export @vitejs/plugin-rsc/rsc for internal use by virtual entries
+// Re-export the RSC-environment *server* runtime for virtual entries.
+// Prefer `@vitejs/plugin-rsc/rsc/server` over the combined `/rsc` barrel so
+// Vite can skip bundling the unused `react-server-dom` client protocol.
 export {
   renderToReadableStream,
   decodeReply,
@@ -7,4 +9,4 @@ export {
   loadServerAction,
   decodeAction,
   decodeFormState,
-} from "@vitejs/plugin-rsc/rsc";
+} from "@vitejs/plugin-rsc/rsc/server";

package/src/deps/ssr.ts

@@ -1,4 +1,5 @@
 export {
   createFromReadableStream,
   setOnClientReference,
+  getClientEntryUrl,
 } from "@vitejs/plugin-rsc/ssr";

package/src/index.rsc.ts

@@ -45,6 +45,7 @@ export type {
   RevalidateParams,
   Revalidate,
   ActionRef,
+  IsActionFn,
   RouteKeys,
   // Loader types
   LoaderDefinition,

package/src/index.ts

@@ -45,6 +45,7 @@ export type {
   RevalidateParams,
   Revalidate,
   ActionRef,
+  IsActionFn,
   RouteKeys,
   // Loader types
   LoaderDefinition,

package/src/router/is-action.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared `isAction()` matcher for revalidate predicates (server + clientUrls).
+ *
+ * Action identity is `actionId`. The helper resolves an imported reference the
+ * same way the action boundary derives that id (`$id ?? $$id`), so a
+ * rename-safe `isAction(fn)` / `isAction(namespace)` match works in both the
+ * RSC environment (file-path `$id`) and the browser (hashed `$$id`).
+ */
+
+import type { ActionRef, IsActionFn } from "../types.js";
+
+// Bind preservation is per-reference, in expose-action-id.ts. Do not patch
+// Function.prototype.bind here (rsc+ssr share a realm; global wrap stacks).
+
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+export function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
+
+/**
+ * Depth cap for the object walk. The supported shapes need at most two
+ * object levels — a namespace (values are functions) and a grouped-namespace
+ * literal (`{ Cart: CartActions }`, values are namespaces). The cap keeps an
+ * accidentally passed arbitrary object (a ctx, a data blob — it type-checks
+ * as Record<string, unknown>) from triggering a full deep traversal on every
+ * predicate call.
+ */
+const MAX_ACTION_REF_DEPTH = 3;
+
+function matchesActionRef(
+  ref: unknown,
+  currentActionId: string,
+  seen: Set<object>,
+  depth: number,
+): boolean {
+  if (ref == null) return false;
+  if (typeof ref === "function") {
+    return resolveActionRefId(ref) === currentActionId;
+  }
+  if (typeof ref !== "object") return false;
+  if (depth >= MAX_ACTION_REF_DEPTH) return false;
+  if (seen.has(ref)) return false;
+  seen.add(ref);
+  // Namespace, object literal, or grouped namespaces
+  // (`{ Cart: CartActions, Order: OrderActions }`): walk every value.
+  // Object.values invokes getters; a throwing getter must not abort the
+  // predicate into the fail-open path, so treat it as "no match here".
+  let values: unknown[];
+  try {
+    values = Object.values(ref);
+  } catch {
+    return false;
+  }
+  for (const value of values) {
+    if (matchesActionRef(value, currentActionId, seen, depth + 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build the `isAction()` helper bound to the current action. Called with no
+ * arguments it answers "is this request an action at all?" — `true` during
+ * action handling (including action-triggered refetches that carry no id
+ * yet), `false` on plain navigation. Called with one or more action
+ * references it narrows to those: a single imported action, several
+ * (variadic), a namespace import (`import * as Mod`), an object literal of
+ * actions (`{ addToCart, removeFromCart }`), or a grouped namespace object.
+ * Returns `false` when there is no action or nothing matches.
+ *
+ * `inAction` is the request kind. It defaults to "an id is present" so
+ * existing server call sites stay a single argument. The client passes the
+ * explicit flag so a refetch terminal with `isAction: true` still answers
+ * bare `isAction()` even if `actionId` was not threaded.
+ */
+export function makeIsAction(
+  currentActionId: string | undefined,
+  inAction: boolean = currentActionId !== undefined,
+): IsActionFn {
+  return (...actions: ActionRef[]): boolean => {
+    if (!inAction) return false;
+    if (actions.length === 0) return true;
+    if (!currentActionId) return false;
+    const seen = new Set<object>();
+    for (const action of actions) {
+      if (matchesActionRef(action, currentActionId, seen, 0)) return true;
+    }
+    return false;
+  };
+}

package/src/router/revalidation.ts

@@ -4,7 +4,7 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
+import type { ResolvedSegment, HandlerContext } from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -15,52 +15,7 @@ import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { paramsEqual } from "./params-util.js";
-
-/**
- * Resolve a server-action reference's stable id, mirroring how the action
- * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
- * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
- * production RSC build when present, otherwise React's `$$id`. Resolving both
- * the incoming `actionId` and the reference with the same precedence makes
- * `isAction()` form-agnostic across dev and production.
- */
-function resolveActionRefId(ref: unknown): string | undefined {
-  if (ref == null) return undefined;
-  const r = ref as { $id?: unknown; $$id?: unknown };
-  if (typeof r.$id === "string") return r.$id;
-  if (typeof r.$$id === "string") return r.$$id;
-  return undefined;
-}
-
-/**
- * Build the `isAction()` helper bound to the current action's id. Called with no
- * arguments it answers "is this request an action at all?" (any action) — `true`
- * during action handling, `false` on plain navigation. Called with one or more
- * action references it narrows to those: a single imported action, several
- * (variadic), or any export of a namespace import (`import * as Mod`). Returns
- * `false` when there is no action (plain navigation) or nothing matches.
- */
-function makeIsAction(
-  currentActionId: string | undefined,
-): (...actions: ActionRef[]) => boolean {
-  return (...actions: ActionRef[]): boolean => {
-    if (!currentActionId) return false;
-    // Bare isAction(): an action is in flight (currentActionId is set) and the
-    // caller did not narrow to a specific action, so this is "any action".
-    if (actions.length === 0) return true;
-    for (const action of actions) {
-      if (typeof action === "function") {
-        if (resolveActionRefId(action) === currentActionId) return true;
-      } else if (action && typeof action === "object") {
-        // Namespace import: match any export of the module.
-        for (const value of Object.values(action)) {
-          if (resolveActionRefId(value) === currentActionId) return true;
-        }
-      }
-    }
-    return false;
-  };
-}
+import { makeIsAction } from "./is-action.js";
 
 /**
  * Options for revalidation evaluation
@@ -249,6 +204,8 @@ export async function evaluateRevalidation<TEnv>(
       ? prevRouteKey
       : undefined;
 
+  const isActionFn = makeIsAction(actionContext?.actionId);
+
   for (const { name, fn } of revalidations) {
     let result: any;
     try {
@@ -265,7 +222,7 @@ export async function evaluateRevalidation<TEnv>(
         slotName: segment.slot,
         // Action context (only populated when triggered by server action)
         actionId: actionContext?.actionId,
-        isAction: makeIsAction(actionContext?.actionId),
+        isAction: isActionFn,
         actionUrl: actionContext?.actionUrl,
         actionResult: actionContext?.actionResult,
         formData: actionContext?.formData,

package/src/rsc/handler.ts

@@ -16,7 +16,7 @@ import {
   _getRequestContext,
   createRequestContext,
 } from "../server/request-context.js";
-import * as rscDeps from "@vitejs/plugin-rsc/rsc";
+import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
   RscPayload,
   CreateRSCHandlerOptions,
@@ -137,7 +137,7 @@ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
  * @example With custom deps (advanced)
  * ```tsx
  * import { createRSCHandler } from "@rangojs/router/rsc";
- * import * as rsc from "@vitejs/plugin-rsc/rsc";
+ * import * as rsc from "@vitejs/plugin-rsc/rsc/server";
  * import { router } from "./router.js";
  *
  * export default createRSCHandler({
@@ -176,7 +176,7 @@ export function createRSCHandler<
   // stores not covered by the app-level ctx._cacheStore.
   const explicitTaggedStores = new Set<SegmentCacheStore>();
 
-  // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
+  // Use provided deps or default to @vitejs/plugin-rsc/rsc/server exports
   const deps = options.deps ?? rscDeps;
   const {
     renderToReadableStream,

package/src/rsc/server-action.ts

@@ -20,6 +20,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
 import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload } from "./types.js";
@@ -302,10 +303,7 @@ export async function executeServerAction<TEnv>(
   }
 
   // Build continuation for the revalidation phase
-  const actionMeta = loadedAction as
-    | { $id?: string; $$id?: string }
-    | undefined;
-  const resolvedActionId = actionMeta?.$id ?? actionMeta?.$$id ?? actionId;
+  const resolvedActionId = resolveActionRefId(loadedAction) ?? actionId;
 
   return {
     returnValue,

package/src/rsc/types.ts

@@ -103,11 +103,11 @@ export interface RscPayload {
 export type ReactFormState = unknown;
 
 /**
- * RSC dependencies from @vitejs/plugin-rsc/rsc
+ * RSC dependencies from @vitejs/plugin-rsc/rsc/server
  */
 export interface RSCDependencies {
   /**
-   * renderToReadableStream from @vitejs/plugin-rsc/rsc
+   * renderToReadableStream from @vitejs/plugin-rsc/rsc/server
    */
   renderToReadableStream: <T>(
     payload: T,
@@ -118,7 +118,7 @@ export interface RSCDependencies {
   ) => ReadableStream<Uint8Array>;
 
   /**
-   * decodeReply from @vitejs/plugin-rsc/rsc
+   * decodeReply from @vitejs/plugin-rsc/rsc/server
    */
   decodeReply: (
     body: FormData | string,
@@ -126,23 +126,23 @@ export interface RSCDependencies {
   ) => Promise<unknown[]>;
 
   /**
-   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc/server
    */
   createTemporaryReferenceSet: () => unknown;
 
   /**
-   * loadServerAction from @vitejs/plugin-rsc/rsc
+   * loadServerAction from @vitejs/plugin-rsc/rsc/server
    */
   loadServerAction: (actionId: string) => Promise<Function>;
 
   /**
-   * decodeAction from @vitejs/plugin-rsc/rsc
+   * decodeAction from @vitejs/plugin-rsc/rsc/server
    * Decodes a FormData into a bound action function (for useActionState forms)
    */
   decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
 
   /**
-   * decodeFormState from @vitejs/plugin-rsc/rsc
+   * decodeFormState from @vitejs/plugin-rsc/rsc/server
    * Decodes the action result into a ReactFormState for useActionState progressive enhancement
    */
   decodeFormState: (
@@ -300,8 +300,8 @@ export interface CreateRSCHandlerOptions<
   router: RangoInternal<TEnv, TRoutes>;
 
   /**
-   * RSC dependencies from @vitejs/plugin-rsc/rsc.
-   * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+   * RSC dependencies from @vitejs/plugin-rsc/rsc/server.
+   * Defaults to the exports from @vitejs/plugin-rsc/rsc/server.
    */
   deps?: RSCDependencies;