@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/src/routerState.ts

@@ -0,0 +1,220 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+import { createRuntimeContextExtension } from './contextExtensions';
+import type {
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+export type {
+  BuiltInRouterFramework,
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterFramework,
+  RouterLifecyclePhase,
+  RouterLinkTarget,
+  RouterNavigationCapability,
+  RouterNavigationSnapshot,
+  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);
+}
+
+/** Capture prepared metadata once; live router updates cannot rewrite it. */
+export function createRouterServerSnapshot(
+  snapshot: InternalRouterServerSnapshot,
+): InternalRouterServerSnapshot {
+  const matches = snapshot.matches?.map(match =>
+    Object.freeze({
+      ...match,
+      ...(match.params ? { params: Object.freeze({ ...match.params }) } : {}),
+    }),
+  );
+  const matchedRouteIds =
+    snapshot.matchedRouteIds ??
+    matches?.map(match => match.assetRouteId ?? match.routeId);
+  return Object.freeze({
+    ...snapshot,
+    ...(snapshot.hydrationScripts
+      ? { hydrationScripts: Object.freeze([...snapshot.hydrationScripts]) }
+      : {}),
+    ...(matchedRouteIds
+      ? { matchedRouteIds: Object.freeze([...matchedRouteIds]) }
+      : {}),
+    ...(matches ? { matches: Object.freeze(matches) } : {}),
+    ...(snapshot.errors
+      ? { errors: Object.freeze({ ...snapshot.errors }) }
+      : {}),
+    ...(snapshot.routerData
+      ? {
+          routerData: Object.freeze({
+            ...snapshot.routerData,
+            ...(snapshot.routerData.loaderData
+              ? {
+                  loaderData: Object.freeze({
+                    ...snapshot.routerData.loaderData,
+                  }),
+                }
+              : {}),
+            ...(snapshot.routerData.errors
+              ? { errors: Object.freeze({ ...snapshot.routerData.errors }) }
+              : {}),
+          }),
+        }
+      : {}),
+  });
+}
+
+/**
+ * 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);
+  routerRuntimeStateExtension.set(runtimeContext, state);
+  // Only a change of identity is worth a re-render; `RouterWrapper` reapplies
+  // the same instance on every render of the app.
+  if (
+    previous?.instance !== state.instance ||
+    previous?.framework !== state.framework ||
+    previous?.navigation !== state.navigation
+  ) {
+    notifyRouterRuntimeState(runtimeContext);
+  }
+
+  return runtimeContext;
+}
+
+export function applyRouterServerPrepareResult<Context extends object>(
+  runtimeContext: Context,
+  result: RouterServerPrepareResult,
+) {
+  if (result.snapshot) {
+    routerServerSnapshotExtension.set(
+      runtimeContext,
+      createRouterServerSnapshot(result.snapshot),
+    );
+  }
+  return applyRouterRuntimeState(runtimeContext, {
+    ...result.state,
+    cleanup: result.cleanup ?? result.state.cleanup,
+  });
+}
+
+export function getRouterHydrationScripts(runtimeContext: object) {
+  return getRouterServerSnapshot(runtimeContext)?.hydrationScripts ?? [];
+}
+
+export function getRouterMatchedRouteIds(runtimeContext: object) {
+  return getRouterServerSnapshot(runtimeContext)?.matchedRouteIds;
+}
+
+export async function cleanupRouterRuntimeState(runtimeContext: object) {
+  try {
+    await getRouterRuntimeState(runtimeContext)?.cleanup?.();
+  } catch {}
+}

package/src/routerStatePlugin.ts

@@ -0,0 +1,125 @@
+import type { createMemoryRouter } from '@modern-js/runtime-utils/router';
+import { createRouterPrefetchPolicy } from './routerPrefetchPolicy';
+import {
+  applyRouterRuntimeState,
+  applyRouterServerPrepareResult,
+} from './routerState';
+import type {
+  RouterNavigationCapability,
+  RouterNavigationSnapshot,
+} from './routerStateTypes';
+
+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;
+};
+
+function createReactRouterNavigation(
+  router: ReturnType<typeof createMemoryRouter>,
+  Link: RouterNavigationCapability['Link'],
+): RouterNavigationCapability {
+  let state: typeof router.state | undefined;
+  let snapshot: RouterNavigationSnapshot;
+  return {
+    Link,
+    getSnapshot() {
+      if (state !== router.state) {
+        state = router.state;
+        snapshot = {
+          location: state.location,
+          params: Object.assign(
+            {},
+            ...state.matches.map(match => match.params),
+          ),
+        };
+      }
+      return snapshot;
+    },
+    subscribe: listener => router.subscribe(listener),
+    navigate: (href, options) => router.navigate(href, options),
+  };
+}
+
+/** 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 snapshot = {
+            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 }]
+                : [],
+            ),
+          };
+          applyRouterServerPrepareResult(event.runtimeContext, {
+            snapshot,
+            state: {
+              framework: event.framework,
+              basename: event.basename,
+              instance: event.router,
+            },
+          });
+        } else if (event.phase === 'client-create') {
+          const router = event.router as ReturnType<typeof createMemoryRouter>;
+          const { router: api } = event.runtimeContext as {
+            router?: { Link?: RouterNavigationCapability['Link'] };
+          };
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: router,
+            ...(api?.Link
+              ? { navigation: createReactRouterNavigation(router, api.Link) }
+              : {}),
+          });
+        }
+      });
+    },
+  };
+}

package/src/routerStateTypes.ts

@@ -0,0 +1,76 @@
+import type React from 'react';
+
+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 {
+  readonly framework?: RouterFramework;
+  readonly basename?: string;
+  readonly statusCode?: number;
+  readonly errors?: Record<string, unknown>;
+  readonly routerData?: {
+    readonly loaderData?: Record<string, unknown>;
+    readonly errors?: Record<string, unknown>;
+  };
+  readonly hydrationScripts?: readonly string[];
+  readonly matchedRouteIds?: readonly string[];
+  readonly matches?: readonly RouterRouteMatchSnapshot[];
+}
+
+export interface InternalRouterRuntimeState {
+  framework: RouterFramework;
+  basename?: string;
+  instance?: unknown;
+  navigation?: RouterNavigationCapability;
+  cleanup?: () => void | Promise<void>;
+}
+
+export interface RouterServerPrepareResult {
+  state: InternalRouterRuntimeState;
+  snapshot?: InternalRouterServerSnapshot;
+  cleanup?: () => void | Promise<void>;
+}
+
+export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';
+
+/** Provider-owned browser navigation. Consumers never inspect router internals. */
+export interface RouterNavigationSnapshot {
+  location: { pathname: string; search: string; hash: string };
+  params: Record<string, string>;
+}
+
+export interface RouterLinkTarget {
+  pathname: string;
+  href: string;
+  search?: Record<string, unknown>;
+  hash?: string;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  preload?: unknown;
+}
+
+export interface RouterNavigationCapability {
+  getSnapshot: () => RouterNavigationSnapshot;
+  subscribe: (listener: () => void) => () => void;
+  navigate: (
+    href: string,
+    options?: { replace?: boolean; state?: unknown },
+  ) => void | Promise<void>;
+  Link: React.ComponentType<{
+    to: string;
+    children?: React.ReactNode;
+    [key: string]: unknown;
+  }>;
+  createLinkProps?: (target: RouterLinkTarget) => {
+    to: string;
+    [key: string]: unknown;
+  };
+}

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 };
+}