@bleedingdev/modern-js-runtime-extensions 3.8.3-ultramodern.6 → 3.9.0-ultramodern.10

package/src/routerState.ts

@@ -0,0 +1,290 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+import { createRuntimeContextExtension } from './contextExtensions';
+import type {
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+export type {
+  BuiltInRouterFramework,
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterFramework,
+  RouterLifecyclePhase,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+/**
+ * Router runtime state is shared by every router provider (react-router,
+ * @modern-js/plugin-tanstack, ...) and consumed by the SSR pipeline. It lives
+ * in the runtime-context extension slot instead of ad-hoc fields on
+ * `TInternalRuntimeContext`.
+ */
+const routerRuntimeStateExtension =
+  createRuntimeContextExtension<InternalRouterRuntimeState>(
+    '@modern-js/runtime:router-runtime-state',
+  );
+
+/**
+ * The server snapshot is tracked separately: a later
+ * `applyRouterRuntimeState` call without a snapshot must not clear a
+ * previously captured one.
+ */
+const routerServerSnapshotExtension =
+  createRuntimeContextExtension<InternalRouterServerSnapshot>(
+    '@modern-js/runtime:router-server-snapshot',
+  );
+
+export function getRouterRuntimeState(
+  runtimeContext: object,
+): InternalRouterRuntimeState | undefined {
+  return routerRuntimeStateExtension.get(runtimeContext);
+}
+
+export function getRouterServerSnapshot(
+  runtimeContext: object,
+): InternalRouterServerSnapshot | undefined {
+  return routerServerSnapshotExtension.get(runtimeContext);
+}
+
+type RouterSnapshotLike = Partial<InternalRouterServerSnapshot>;
+
+function toHydrationScripts(state: {
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+}) {
+  if (state.hydrationScripts?.length) {
+    return state.hydrationScripts;
+  }
+
+  return state.hydrationScript ? [state.hydrationScript] : undefined;
+}
+
+function getMatchedRouteIdsFromMatches(matches?: RouterRouteMatchSnapshot[]) {
+  const routeIds = matches
+    ?.map(match => match.assetRouteId ?? match.routeId)
+    .filter((routeId): routeId is string => typeof routeId === 'string');
+
+  return routeIds?.length ? routeIds : undefined;
+}
+
+export function createRouterServerSnapshot(
+  state: RouterSnapshotLike,
+): InternalRouterServerSnapshot {
+  const hydrationScripts = toHydrationScripts(state);
+  const matchedRouteIds =
+    state.matchedRouteIds ?? getMatchedRouteIdsFromMatches(state.matches);
+
+  return {
+    ...state,
+    ...(hydrationScripts?.length
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          hydrationScripts,
+        }
+      : {}),
+    ...(matchedRouteIds ? { matchedRouteIds } : {}),
+  };
+}
+
+export function createRouterRuntimeState(
+  state: InternalRouterRuntimeState,
+): InternalRouterRuntimeState {
+  const hasSnapshotState =
+    Boolean(state.serverSnapshot) ||
+    Boolean(state.hydrationScript) ||
+    Boolean(state.hydrationScripts?.length) ||
+    Boolean(state.matchedRouteIds?.length) ||
+    Boolean(state.matches?.length);
+  const serverSnapshot = state.serverSnapshot
+    ? createRouterServerSnapshot({
+        ...state.serverSnapshot,
+        framework: state.serverSnapshot.framework ?? state.framework,
+        basename: state.serverSnapshot.basename ?? state.basename,
+        hydrationScript:
+          state.serverSnapshot.hydrationScript ?? state.hydrationScript,
+        hydrationScripts:
+          state.serverSnapshot.hydrationScripts ?? state.hydrationScripts,
+        matchedRouteIds:
+          state.serverSnapshot.matchedRouteIds ?? state.matchedRouteIds,
+        matches: state.serverSnapshot.matches ?? state.matches,
+      })
+    : hasSnapshotState
+      ? createRouterServerSnapshot({
+          framework: state.framework,
+          basename: state.basename,
+          hydrationScript: state.hydrationScript,
+          hydrationScripts: state.hydrationScripts,
+          matchedRouteIds: state.matchedRouteIds,
+          matches: state.matches,
+        })
+      : undefined;
+  const hydrationScripts = toHydrationScripts({
+    hydrationScript: state.hydrationScript ?? serverSnapshot?.hydrationScript,
+    hydrationScripts:
+      state.hydrationScripts ?? serverSnapshot?.hydrationScripts,
+  });
+  const matchedRouteIds =
+    state.matchedRouteIds ??
+    serverSnapshot?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(state.matches);
+
+  return {
+    ...state,
+    ...(hydrationScripts?.length
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          hydrationScripts,
+        }
+      : {}),
+    ...(matchedRouteIds ? { matchedRouteIds } : {}),
+    ...(serverSnapshot ? { serverSnapshot } : {}),
+  };
+}
+
+/**
+ * Listeners per runtime context, so a consumer can react to the slot being
+ * filled in. A router provider publishes its instance during render - TanStack
+ * installs it when `RouterWrapper` renders - which is after anything that
+ * wraps the app has already evaluated. Without a notification those wrappers
+ * would hold a routerless view of the app for the rest of the session.
+ *
+ * Keyed weakly: the runtime context outlives neither the app nor this map.
+ */
+const routerRuntimeStateListeners = new WeakMap<object, Set<() => void>>();
+
+/**
+ * Observe the router runtime-state slot for the given runtime context.
+ * Returns an unsubscribe function; safe to call for a context that never
+ * receives a router.
+ */
+export function subscribeRouterRuntimeState(
+  runtimeContext: object,
+  listener: () => void,
+): () => void {
+  if (!runtimeContext || typeof runtimeContext !== 'object') {
+    return () => undefined;
+  }
+  let listeners = routerRuntimeStateListeners.get(runtimeContext);
+  if (!listeners) {
+    listeners = new Set();
+    routerRuntimeStateListeners.set(runtimeContext, listeners);
+  }
+  listeners.add(listener);
+  return () => {
+    listeners?.delete(listener);
+  };
+}
+
+/** Contexts with a notification already scheduled, so a burst coalesces. */
+const pendingRouterRuntimeStateNotifications = new WeakSet<object>();
+
+function notifyRouterRuntimeState(runtimeContext: object) {
+  const listeners = routerRuntimeStateListeners.get(runtimeContext);
+  if (!listeners?.size) {
+    return;
+  }
+  if (pendingRouterRuntimeStateNotifications.has(runtimeContext)) {
+    return;
+  }
+  pendingRouterRuntimeStateNotifications.add(runtimeContext);
+  // Deferred deliberately. A router provider publishes its instance from
+  // inside its own render - `RouterWrapper` does - so calling observers
+  // synchronously would schedule an update on a component that is rendering,
+  // which React reports as "Cannot update a component while rendering a
+  // different component". Delivering after the current render lands keeps the
+  // notification correct and silent.
+  const deliver = () => {
+    pendingRouterRuntimeStateNotifications.delete(runtimeContext);
+    const current = routerRuntimeStateListeners.get(runtimeContext);
+    if (!current?.size) {
+      return;
+    }
+    for (const listener of [...current]) {
+      try {
+        listener();
+      } catch {
+        // One bad observer must not stop the router from being published.
+      }
+    }
+  };
+  if (typeof queueMicrotask === 'function') {
+    queueMicrotask(deliver);
+  } else {
+    setTimeout(deliver, 0);
+  }
+}
+
+export function applyRouterRuntimeState<Context extends object>(
+  runtimeContext: Context,
+  state: InternalRouterRuntimeState,
+) {
+  const previous = routerRuntimeStateExtension.get(runtimeContext);
+  const normalized = createRouterRuntimeState(state);
+  routerRuntimeStateExtension.set(runtimeContext, normalized);
+  if (normalized.serverSnapshot) {
+    routerServerSnapshotExtension.set(
+      runtimeContext,
+      normalized.serverSnapshot,
+    );
+  }
+  // Only a change of identity is worth a re-render; `RouterWrapper` reapplies
+  // the same instance on every render of the app.
+  if (
+    previous?.instance !== normalized.instance ||
+    previous?.framework !== normalized.framework
+  ) {
+    notifyRouterRuntimeState(runtimeContext);
+  }
+
+  return runtimeContext;
+}
+
+export function applyRouterServerPrepareResult<Context extends object>(
+  runtimeContext: Context,
+  result: RouterServerPrepareResult,
+) {
+  const state = createRouterRuntimeState({
+    ...result.state,
+    cleanup: result.cleanup ?? result.state.cleanup,
+    serverSnapshot: result.snapshot ?? result.state.serverSnapshot,
+  });
+  applyRouterRuntimeState(runtimeContext, state);
+  return runtimeContext;
+}
+
+export function getRouterHydrationScripts(runtimeContext: object) {
+  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
+  const runtimeState = getRouterRuntimeState(runtimeContext);
+  return (
+    serverSnapshot?.hydrationScripts ??
+    toHydrationScripts({
+      hydrationScript: serverSnapshot?.hydrationScript,
+    }) ??
+    runtimeState?.hydrationScripts ??
+    toHydrationScripts({
+      hydrationScript: runtimeState?.hydrationScript,
+    }) ??
+    []
+  );
+}
+
+export function getRouterMatchedRouteIds(runtimeContext: object) {
+  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
+  const runtimeState = getRouterRuntimeState(runtimeContext);
+  return (
+    serverSnapshot?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(serverSnapshot?.matches) ??
+    runtimeState?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(runtimeState?.matches)
+  );
+}
+
+export async function cleanupRouterRuntimeState(runtimeContext: object) {
+  try {
+    await getRouterRuntimeState(runtimeContext)?.cleanup?.();
+  } catch {}
+}

package/src/routerStatePlugin.ts

@@ -0,0 +1,86 @@
+import { createRouterPrefetchPolicy } from './routerPrefetchPolicy';
+import {
+  applyRouterRuntimeState,
+  createRouterServerSnapshot,
+} from './routerState';
+
+type ReactRouterServerContext = {
+  statusCode: number;
+  errors?: Record<string, unknown> | null;
+  loaderData: Record<string, unknown>;
+  matches: { route: { id?: string } }[];
+};
+
+type RouterLifecycleEvent = {
+  framework: string;
+  phase: string;
+  runtimeContext: object;
+  basename?: string;
+  router?: unknown;
+};
+
+/** Install fork policy through lifecycle hooks supplied by the native owner. */
+export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
+  registryHooks,
+}: {
+  registryHooks: Hooks;
+}) {
+  return {
+    name: '@modern-js/router-runtime-policy',
+    registryHooks,
+    setup(api: {
+      onBeforeRender: (callback: (context: object) => void) => unknown;
+      onAfterCreateRouter: (
+        callback: (event: RouterLifecycleEvent) => void,
+      ) => unknown;
+    }) {
+      api.onBeforeRender(context => {
+        const runtimeContext = context as {
+          linkPrefetchPolicy?: ReturnType<typeof createRouterPrefetchPolicy>;
+        };
+        runtimeContext.linkPrefetchPolicy ??= createRouterPrefetchPolicy();
+      });
+      api.onAfterCreateRouter(event => {
+        if (event.framework !== 'react-router') {
+          return;
+        }
+        if (event.phase === 'ssr-prepare') {
+          const { routerContext } = event.runtimeContext as {
+            routerContext?: ReactRouterServerContext;
+          };
+          if (!routerContext) {
+            return;
+          }
+          const serverSnapshot = createRouterServerSnapshot({
+            framework: event.framework,
+            basename: event.basename,
+            statusCode: routerContext.statusCode,
+            errors: routerContext.errors ?? undefined,
+            routerData: {
+              loaderData: routerContext.loaderData,
+              errors: routerContext.errors ?? undefined,
+            },
+            matches: routerContext.matches.flatMap(match =>
+              typeof match.route.id === 'string'
+                ? [{ routeId: match.route.id }]
+                : [],
+            ),
+          });
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+            matchedRouteIds: serverSnapshot.matchedRouteIds,
+            serverSnapshot,
+          });
+        } else if (event.phase === 'client-create') {
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+          });
+        }
+      });
+    },
+  };
+}

package/src/routerStateTypes.ts

@@ -0,0 +1,46 @@
+export type BuiltInRouterFramework = 'react-router' | 'tanstack';
+
+export type RouterFramework = BuiltInRouterFramework | (string & {});
+
+export interface RouterRouteMatchSnapshot {
+  routeId: string;
+  assetRouteId?: string;
+  pathname?: string;
+  params?: Record<string, string>;
+}
+
+export interface InternalRouterServerSnapshot {
+  framework?: RouterFramework;
+  basename?: string;
+  statusCode?: number;
+  errors?: Record<string, unknown>;
+  routerData?: {
+    loaderData?: Record<string, unknown>;
+    errors?: Record<string, unknown>;
+  };
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+}
+
+export interface InternalRouterRuntimeState {
+  framework: RouterFramework;
+  basename?: string;
+  instance?: unknown;
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+  serverSnapshot?: InternalRouterServerSnapshot;
+  cleanup?: () => void | Promise<void>;
+}
+
+export interface RouterServerPrepareResult {
+  state: InternalRouterRuntimeState;
+  snapshot?: InternalRouterServerSnapshot;
+  redirect?: Response;
+  cleanup?: () => void | Promise<void>;
+}
+
+export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';

package/src/rsc-disabled/rscDisabledClientBrowserRuntime.ts

@@ -0,0 +1,10 @@
+import { disabledRscRuntime } from './rscDisabledRuntimeError';
+
+export const createFromFetch = disabledRscRuntime;
+export const createFromReadableStream = disabledRscRuntime;
+export const createServerReference = disabledRscRuntime;
+export const createTemporaryReferenceSet = disabledRscRuntime;
+export const encodeReply = disabledRscRuntime;
+export const registerServerReference = disabledRscRuntime;
+export const setFindSourceMapURLCallback = disabledRscRuntime;
+export const setServerCallback = disabledRscRuntime;

package/src/rsc-disabled/rscDisabledClientEdgeRuntime.ts

@@ -0,0 +1,8 @@
+import { disabledRscRuntime } from './rscDisabledRuntimeError';
+
+export const createFromFetch = disabledRscRuntime;
+export const createFromReadableStream = disabledRscRuntime;
+export const createServerReference = disabledRscRuntime;
+export const createTemporaryReferenceSet = disabledRscRuntime;
+export const encodeReply = disabledRscRuntime;
+export const registerServerReference = disabledRscRuntime;

package/src/rsc-disabled/rscDisabledClientNodeRuntime.ts

@@ -0,0 +1,9 @@
+import { disabledRscRuntime } from './rscDisabledRuntimeError';
+
+export const createFromFetch = disabledRscRuntime;
+export const createFromNodeStream = disabledRscRuntime;
+export const createFromReadableStream = disabledRscRuntime;
+export const createServerReference = disabledRscRuntime;
+export const createTemporaryReferenceSet = disabledRscRuntime;
+export const encodeReply = disabledRscRuntime;
+export const registerServerReference = disabledRscRuntime;

package/src/rsc-disabled/rscDisabledRuntimeError.ts

@@ -0,0 +1,3 @@
+export function disabledRscRuntime(): never {
+  throw new Error('React Server Components are disabled for this build.');
+}

package/src/rsc-disabled/rscDisabledServerEdgeRuntime.ts

@@ -0,0 +1,16 @@
+import { disabledRscRuntime } from './rscDisabledRuntimeError';
+
+export const createServerEntry = disabledRscRuntime;
+export const createTemporaryReferenceSet = disabledRscRuntime;
+export const decodeAction = disabledRscRuntime;
+export const decodeFormState = disabledRscRuntime;
+export const decodeReply = disabledRscRuntime;
+export const decodeReplyFromAsyncIterable = disabledRscRuntime;
+export const decryptServerActionBoundArgs = disabledRscRuntime;
+export const encryptServerActionBoundArgs = disabledRscRuntime;
+export const ensureServerActions = disabledRscRuntime;
+export const loadServerAction = disabledRscRuntime;
+export const registerClientReference = disabledRscRuntime;
+export const registerServerReference = disabledRscRuntime;
+export const renderToReadableStream = disabledRscRuntime;
+export const setServerActionBoundArgsEncryption = disabledRscRuntime;

package/src/rsc-disabled/rscDisabledServerNodeRuntime.ts

@@ -0,0 +1,18 @@
+import { disabledRscRuntime } from './rscDisabledRuntimeError';
+
+export const createServerEntry = disabledRscRuntime;
+export const createTemporaryReferenceSet = disabledRscRuntime;
+export const decodeAction = disabledRscRuntime;
+export const decodeFormState = disabledRscRuntime;
+export const decodeReply = disabledRscRuntime;
+export const decodeReplyFromAsyncIterable = disabledRscRuntime;
+export const decodeReplyFromBusboy = disabledRscRuntime;
+export const decryptServerActionBoundArgs = disabledRscRuntime;
+export const encryptServerActionBoundArgs = disabledRscRuntime;
+export const ensureServerActions = disabledRscRuntime;
+export const loadServerAction = disabledRscRuntime;
+export const registerClientReference = disabledRscRuntime;
+export const registerServerReference = disabledRscRuntime;
+export const renderToPipeableStream = disabledRscRuntime;
+export const renderToReadableStream = disabledRscRuntime;
+export const setServerActionBoundArgsEncryption = disabledRscRuntime;

package/src/runtimeContextProjection.ts

@@ -0,0 +1,105 @@
+import { stripRuntimeContextExtensions } from './contextExtensions';
+
+// Only the transport fields consumed by this projection are required. This
+// policy module does not depend on the native runtime or plugin API types.
+interface ProjectionContext {
+  isBrowser?: boolean;
+  ssrContext?: {
+    request: {
+      url?: unknown;
+      userAgent?: unknown;
+      cookie?: unknown;
+      pathname?: unknown;
+      query?: object;
+      params?: object;
+      headers?: object;
+      host?: unknown;
+      referer?: unknown;
+    };
+    response: { locals?: unknown };
+  };
+}
+
+function createRscSafeRequestContext(
+  ssrContext: ProjectionContext['ssrContext'],
+) {
+  const requestContext = {
+    request: {
+      params: {},
+      pathname: '',
+      query: {},
+      headers: {},
+      host: '',
+      url: '',
+    },
+    response: {
+      setHeader() {},
+      status() {},
+      locals: {} as unknown,
+    },
+  };
+  Object.defineProperty(requestContext.response, 'setHeader', {
+    enumerable: false,
+  });
+  Object.defineProperty(requestContext.response, 'status', {
+    enumerable: false,
+  });
+
+  if (ssrContext === undefined) {
+    return requestContext;
+  }
+
+  const { request, response } = ssrContext;
+  return {
+    request: {
+      url: request.url,
+      userAgent: request.userAgent,
+      cookie: request.cookie,
+      pathname: request.pathname,
+      query: { ...request.query },
+      params: { ...request.params },
+      headers: { ...request.headers },
+      host: request.host,
+      referer: request.referer,
+    },
+    response: Object.assign(requestContext.response, {
+      locals: response.locals ?? {},
+    }),
+  };
+}
+
+export function projectRuntimeContext<
+  InternalContext extends ProjectionContext,
+  PublicContext extends ProjectionContext,
+>(
+  projection: {
+    internalContext: InternalContext;
+    publicContext: PublicContext;
+  },
+  options: { context: InternalContext; isRsc: boolean },
+) {
+  let internalContext = projection.internalContext;
+  let publicContext = { ...projection.publicContext };
+  // Enumerable symbol slots deliberately survive internal SSR copies. Remove
+  // them only from the public projection, never from the original request.
+  stripRuntimeContextExtensions(publicContext);
+
+  if (options.isRsc && options.context.isBrowser === false) {
+    const requestContext = createRscSafeRequestContext(
+      options.context.ssrContext,
+    );
+    internalContext = {
+      ...internalContext,
+      context: requestContext,
+      requestContext,
+    };
+    delete internalContext.ssrContext;
+    publicContext = {
+      ...publicContext,
+      context: requestContext,
+      requestContext,
+    };
+  }
+
+  return { internalContext, publicContext };
+}