react-router 0.0.0-experimental-abd9fc79b → 0.0.0-experimental-2a01b6fd8

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # `react-router`
 
+## v8.3.0
+
+### Patch Changes
+
+- Encode path params in `href`/`generatePath` per RFC 3986 path-segment rules instead of `encodeURIComponent` ([#15310](https://github.com/remix-run/react-router/pull/15310))
+  - Characters that are valid literally in a path segment (`$ & + , ; = : @` — RFC 3986 `pchar`) are no longer percent-encoded, so values like a semver build `1.0.0+1` interpolate unchanged instead of becoming `1.0.0%2B1`
+  - Structural/unsafe characters (`/ ? # %`, whitespace, non-ASCII) are still escaped exactly as before
+- Use `crypto.randomUUID()` for `createMemorySessionStorage` session ids ([#15302](https://github.com/remix-run/react-router/pull/15302))
+  - `createMemorySessionStorage` is only intended for local development and testing - sessions are lost when the server restarts
+- Fix `NavLink` not applying its `pending` state when `to` has a trailing slash ([#15300](https://github.com/remix-run/react-router/pull/15300))
+- Preserve RSC route component metadata so routes with a `clientLoader` can skip unnecessary server requests once their components have rendered while still fetching missing server-rendered elements ([#15323](https://github.com/remix-run/react-router/pull/15323))
+- Harden RSC CSRF code paths ([#15311](https://github.com/remix-run/react-router/pull/15311))
+- Fix server crash (`TypeError: Invalid state: Unable to enqueue`) when a request is aborted while the RSC HTML stream has a pending flush ([#15286](https://github.com/remix-run/react-router/pull/15286))
+  - Handle cancellation of the `injectRSCPayload` readable side, clear the pending flush, and cancel the underlying RSC payload stream
+
+### Unstable Changes
+
+⚠️ _[Unstable features](https://reactrouter.com/community/api-development-strategy#unstable-flags) are not recommended for production use_
+
+- Detect stale RSC clients during lazy route discovery and reload the destination document ([#15318](https://github.com/remix-run/react-router/pull/15318))
+
+  #### Migration
+
+  Apps using the default RSC Framework entry do not need to make any changes. Apps with a custom `entry.rsc.tsx` should import the generated client version and pass it to `unstable_matchRSCServerRequest`:
+
+  ```tsx
+  import clientVersion from "virtual:react-router/unstable_rsc/client-version";
+
+  return unstable_matchRSCServerRequest({
+    // ...
+    clientVersion,
+  });
+  ```
+
+- Add CSP nonce support to RSC document rendering ([#15320](https://github.com/remix-run/react-router/pull/15320))
+  - Add `nonce` options to `unstable_routeRSCServerRequest` and `unstable_RSCStaticRouter`
+  - Forward the nonce to the HTML renderer and apply it to injected RSC payload scripts and nonce-aware framework components
+
+  To adopt nonce-based CSP, update your `entry.ssr.tsx` (run `react-router reveal entry.ssr` first in RSC Framework Mode) to generate a fresh nonce for each request. Pass it to `routeRSCServerRequest`, spread the `renderHTML` options into React's HTML renderer, pass `options.nonce` to `RSCStaticRouter`, and use the same nonce in the `Content-Security-Policy` response header:
+
+  ```tsx
+  const nonce = crypto.randomUUID();
+  const response = await routeRSCServerRequest({
+    request,
+    serverResponse,
+    createFromReadableStream,
+    nonce,
+    async renderHTML(getPayload, options) {
+      const payload = getPayload();
+      return renderHTMLToReadableStream(
+        <RSCStaticRouter getPayload={getPayload} nonce={options.nonce} />,
+        {
+          ...options,
+          bootstrapScriptContent,
+          formState: await payload.formState,
+          signal: request.signal,
+        },
+      );
+    },
+  });
+  response.headers.set(
+    "Content-Security-Policy",
+    `script-src 'self' 'nonce-${nonce}'`,
+  );
+  ```
+
+## v8.2.0
+
+### Patch Changes
+
+- Fix `href()` to properly stringify and URL-encode param values, matching `generatePath()` ([#15277](https://github.com/remix-run/react-router/pull/15277))
+  - splat params preserve path separators while encoding each segment individually
+- Fix dynamic param extraction for routes with optional static segments ([#15200](https://github.com/remix-run/react-router/pull/15200))
+  - When a route path contains optional static segments (e.g. `/school?/user/:id`), the internal regex's incorrectly shifted parameter indices resulting in incorrect parameter extraction
+  - Consecutive optional static segments (e.g. `/one?/two?`) were only partially handled
+- Preserve navigation blocker state through a revalidation ([#15246](https://github.com/remix-run/react-router/pull/15246))
+- Fix route ranking for dynamic parameters with static extension suffixes ([#15273](https://github.com/remix-run/react-router/pull/15273))
+  - These were not being detected as dynamic param segments and instead got incorrectly scored higher as a static segment
+  - This meant they could potentially tie truly static routes like `/sitemap.xml` and outrank them based on definition order
+  - These are now correctly identified as dynamic parameter segments and scored correctly
+- Use ReactFormState types instead of unknown ([#15263](https://github.com/remix-run/react-router/pull/15263))
+
+## v8.1.0
+
+### Minor Changes
+
+- Return route metadata from server request, client navigation, and client fetcher instrumentations ([#15235](https://github.com/remix-run/react-router/pull/15235))
+  - Adds result metadata after instrumented calls complete, including the URL, matched route pattern, and params
+  - Adds known HTTP status codes to server request handler instrumentation results
+
 ## v8.0.1
 
 ### Patch Changes

package/dist/development/dom-export.js

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-abd9fc79b
+ * react-router v0.0.0-experimental-2a01b6fd8
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/development/index-react-server-client.js

@@ -1,5 +1,5 @@
 /**
- * react-router v0.0.0-experimental-abd9fc79b
+ * react-router v0.0.0-experimental-2a01b6fd8
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/development/index-react-server.d.ts

@@ -2,6 +2,7 @@
 import * as React from "react";
 import { CookieParseOptions, CookieParseOptions as CookieParseOptions$1, CookieSerializeOptions, CookieSerializeOptions as CookieSerializeOptions$1 } from "cookie-es";
 import { BrowserRouter, Form, HashRouter, Link, Links, MemoryRouter, Meta, NavLink, Navigate, Outlet, Route, Router, RouterProvider, Routes, ScrollRestoration, StaticRouter, StaticRouterProvider, unstable_HistoryRouter } from "react-router/internal/react-server-client";
+import { ReactFormState } from "react-dom/client";
 
 //#region lib/router/history.d.ts
 /**
@@ -49,7 +50,7 @@ interface Path {
  * An entry in a history stack. A location contains information about the
  * URL path, as well as possibly some arbitrary state and a key.
  */
-interface Location<State = any> extends Path {
+interface Location$1<State = any> extends Path {
   /**
    * A value of arbitrary data associated with this location.
    */
@@ -78,7 +79,7 @@ interface Update {
   /**
    * The new location.
    */
-  location: Location;
+  location: Location$1;
   /**
    * The delta between this location and the former location in the history stack
    */
@@ -112,7 +113,7 @@ interface History {
   /**
    * The current location. This value is mutable.
    */
-  readonly location: Location;
+  readonly location: Location$1;
   /**
    * Returns a valid href for the given `to` value that may be used as
    * the value of an <a href> attribute.
@@ -487,6 +488,9 @@ interface ShouldRevalidateFunctionArgs {
 interface ShouldRevalidateFunction {
   (args: ShouldRevalidateFunctionArgs): boolean;
 }
+interface UnstableValidateParamsFunction {
+  (params: Params): boolean;
+}
 interface DataStrategyMatch extends RouteMatch<string, DataRouteObject> {
   /**
    * @private
@@ -596,7 +600,7 @@ interface MapRoutePropertiesFunction {
  * onto the route. Either they're meaningful to the router, or they'll get
  * ignored.
  */
-type UnsupportedLazyRouteObjectKey = "lazy" | "caseSensitive" | "path" | "id" | "index" | "children";
+type UnsupportedLazyRouteObjectKey = "lazy" | "caseSensitive" | "path" | "id" | "index" | "children" | "unstable_validateParams";
 /**
  * Keys we cannot change from within a lazy() function. We spread all other keys
  * onto the route. Either they're meaningful to the router, or they'll get
@@ -654,6 +658,10 @@ type BaseRouteObject = {
    * See [`shouldRevalidate`](../../start/data/route-object#shouldRevalidate).
    */
   shouldRevalidate?: ShouldRevalidateFunction;
+  /**
+   * Validate route params after a route-pattern match.
+   */
+  unstable_validateParams?: UnstableValidateParamsFunction;
   /**
    * The route handle.
    */
@@ -790,7 +798,7 @@ interface DataRouteMatch extends RouteMatch<string, DataRouteObject> {}
  * Defaults to `/`.
  * @returns An array of matched routes, or `null` if no matches were found.
  */
-declare function matchRoutes<RouteObjectType extends RouteObject = RouteObject>(routes: RouteObjectType[], locationArg: Partial<Location> | string, basename?: string): RouteMatch<string, RouteObjectType>[] | null;
+declare function matchRoutes<RouteObjectType extends RouteObject = RouteObject>(routes: RouteObjectType[], locationArg: Partial<Location$1> | string, basename?: string): RouteMatch<string, RouteObjectType>[] | null;
 interface UIMatch<Data = unknown, Handle = unknown> {
   id: string;
   pathname: string;
@@ -1009,6 +1017,19 @@ type ClientInstrumentation = {
 type InstrumentRequestHandlerFunction = (handler: InstrumentableRequestHandler) => void;
 type InstrumentRouterFunction = (router: InstrumentableRouter) => void;
 type InstrumentRouteFunction = (route: InstrumentableRoute) => void;
+/**
+ * Route metadata available after React Router has matched an instrumented
+ * request, navigation, or fetcher call.
+ */
+type InstrumentationResultMeta = {
+  url: LoaderFunctionArgs["url"];
+  pattern: string;
+  params: LoaderFunctionArgs["params"];
+};
+/**
+ * Result returned by route-level instrumented handler calls, such as
+ * instrumented loaders, actions, middleware, and lazy route functions.
+ */
 type InstrumentationHandlerResult = {
   status: "success";
   error: undefined;
@@ -1016,7 +1037,21 @@ type InstrumentationHandlerResult = {
   status: "error";
   error: Error;
 };
-type InstrumentFunction<T> = (handler: () => Promise<InstrumentationHandlerResult>, info: T) => Promise<void>;
+/**
+ * Result returned by client-side router instrumented navigation and fetcher
+ * calls.
+ */
+type InstrumentationClientRouterResult = InstrumentationHandlerResult & {
+  meta: InstrumentationResultMeta | undefined;
+};
+/**
+ * Result returned by server request handler instrumentation.
+ */
+type InstrumentationServerHandlerResult = InstrumentationHandlerResult & {
+  statusCode: number;
+  meta: InstrumentationResultMeta | undefined;
+};
+type InstrumentFunction<T, TInnerResult = InstrumentationHandlerResult> = (handler: () => Promise<TInnerResult>, info: T) => Promise<void>;
 type ReadonlyRequest = {
   method: string;
   url: string;
@@ -1039,18 +1074,16 @@ type RouteInstrumentations = {
   action?: InstrumentFunction<RouteHandlerInstrumentationInfo>;
 };
 type RouteLazyInstrumentationInfo = undefined;
-type RouteHandlerInstrumentationInfo = Readonly<{
+type RouteHandlerInstrumentationInfo = Readonly<Omit<LoaderFunctionArgs, "request" | "context"> & {
   request: ReadonlyRequest;
-  params: LoaderFunctionArgs["params"];
-  pattern: string;
   context: ReadonlyContext;
 }>;
 type InstrumentableRouter = {
   instrument(instrumentations: RouterInstrumentations): void;
 };
 type RouterInstrumentations = {
-  navigate?: InstrumentFunction<RouterNavigationInstrumentationInfo>;
-  fetch?: InstrumentFunction<RouterFetchInstrumentationInfo>;
+  navigate?: InstrumentFunction<RouterNavigationInstrumentationInfo, InstrumentationClientRouterResult>;
+  fetch?: InstrumentFunction<RouterFetchInstrumentationInfo, InstrumentationClientRouterResult>;
 };
 type RouterNavigationInstrumentationInfo = Readonly<{
   to: string | number;
@@ -1073,7 +1106,7 @@ type InstrumentableRequestHandler = {
   instrument(instrumentations: RequestHandlerInstrumentations): void;
 };
 type RequestHandlerInstrumentations = {
-  request?: InstrumentFunction<RequestHandlerInstrumentationInfo>;
+  request?: InstrumentFunction<RequestHandlerInstrumentationInfo, InstrumentationServerHandlerResult>;
 };
 type RequestHandlerInstrumentationInfo = Readonly<{
   request: ReadonlyRequest;
@@ -1117,9 +1150,10 @@ interface Router$1 {
    * @private
    * PRIVATE - DO NOT USE
    *
-   * Return the route branches for this router instance
+   * Match routes against a location using the router's configured route
+   * matching implementation.
    */
-  get branches(): RouteBranch<DataRouteObject>[] | undefined;
+  match(locationArg: Partial<Location$1> | string): DataRouteMatch[] | null;
   /**
    * @private
    * PRIVATE - DO NOT USE
@@ -1204,7 +1238,7 @@ interface Router$1 {
    * Utility function to create an href for the given location
    * @param location
    */
-  createHref(location: Location | URL): string;
+  createHref(location: Location$1 | URL): string;
   /**
    * @private
    * PRIVATE - DO NOT USE
@@ -1312,7 +1346,7 @@ interface RouterState {
   /**
    * The current location reflected by the router
    */
-  location: Location;
+  location: Location$1;
   /**
    * The current set of route matches
    */
@@ -1373,7 +1407,9 @@ type HydrationState = Partial<Pick<RouterState, "loaderData" | "actionData" | "e
 /**
  * Future flags to toggle new feature behavior
  */
-interface FutureConfig {}
+interface FutureConfig {
+  unstable_routePatternMatching?: boolean;
+}
 /**
  * Initialization options for createRouter
  */
@@ -1469,8 +1505,8 @@ interface StaticHandler {
   }): Promise<any>;
 }
 type ViewTransitionOpts = {
-  currentLocation: Location;
-  nextLocation: Location;
+  currentLocation: Location$1;
+  nextLocation: Location$1;
 };
 /**
  * Subscriber function signature for changes to router state
@@ -1488,7 +1524,7 @@ interface RouterSubscriber {
  * for a given location
  */
 interface GetScrollRestorationKeyFunction {
-  (location: Location, matches: UIMatch[]): string | null;
+  (location: Location$1, matches: UIMatch[]): string | null;
 }
 /**
  * Function signature for determining the current scroll position
@@ -1570,7 +1606,7 @@ type NavigationStates = {
   };
   Loading: {
     state: "loading";
-    location: Location;
+    location: Location$1;
     matches: DataRouteMatch[];
     historyAction: Action;
     formMethod: Submission["formMethod"] | undefined;
@@ -1582,7 +1618,7 @@ type NavigationStates = {
   };
   Submitting: {
     state: "submitting";
-    location: Location;
+    location: Location$1;
     matches: DataRouteMatch[];
     historyAction: Action;
     formMethod: Submission["formMethod"];
@@ -1672,7 +1708,7 @@ interface BlockerBlocked {
   state: "blocked";
   reset: () => void;
   proceed: () => void;
-  location: Location;
+  location: Location$1;
 }
 interface BlockerUnblocked {
   state: "unblocked";
@@ -1684,12 +1720,12 @@ interface BlockerProceeding {
   state: "proceeding";
   reset: undefined;
   proceed: undefined;
-  location: Location;
+  location: Location$1;
 }
 type Blocker = BlockerUnblocked | BlockerBlocked | BlockerProceeding;
 type BlockerFunction = (args: {
-  currentLocation: Location;
-  nextLocation: Location;
+  currentLocation: Location$1;
+  nextLocation: Location$1;
   historyAction: Action;
 }) => boolean;
 interface CreateStaticHandlerOptions {
@@ -1974,7 +2010,7 @@ type MetaMatches<MatchLoaders extends Record<string, LoaderFunction | ClientLoad
 interface MetaArgs<Loader extends LoaderFunction | ClientLoaderFunction | unknown = unknown, MatchLoaders extends Record<string, LoaderFunction | ClientLoaderFunction | unknown> = Record<string, unknown>> {
   loaderData: (Loader extends LoaderFunction | ClientLoaderFunction ? SerializeFrom<Loader> : unknown) | undefined;
   params: Params;
-  location: Location;
+  location: Location$1;
   matches: MetaMatches<MatchLoaders>;
   error?: unknown;
 }
@@ -2292,14 +2328,14 @@ type RSCRenderPayload = {
   type: "render";
   actionData: Record<string, any> | null;
   basename: string | undefined;
+  clientVersion?: string;
   errors: Record<string, any> | null;
   loaderData: Record<string, any>;
-  location: Location;
+  location: Location$1;
   routeDiscovery: RouteDiscovery;
   matches: RSCRouteMatch[];
   patches?: Promise<RSCRouteManifest[]>;
-  nonce?: string;
-  formState?: unknown;
+  formState?: ReactFormState;
 };
 type RSCManifestPayload = {
   type: "manifest";
@@ -2325,7 +2361,7 @@ type RSCMatch = {
   payload: RSCPayload;
 };
 type DecodeActionFunction = (formData: FormData) => Promise<() => Promise<unknown>>;
-type DecodeFormStateFunction = (result: unknown, formData: FormData) => unknown;
+type DecodeFormStateFunction = (result: unknown, formData: FormData) => Promise<ReactFormState | undefined>;
 type DecodeReplyFunction = (reply: FormData | string, options: {
   temporaryReferences: unknown;
 }) => Promise<unknown[]>;
@@ -2395,6 +2431,8 @@ type RouteDiscovery = {
  * encoding the {@link unstable_RSCPayload}.
  * @param opts.loadServerAction Your `react-server-dom-xyz/server`'s
  * `loadServerAction` function, used to load a server action by ID.
+ * @param opts.clientVersion A version derived from the client build output used
+ * to detect stale clients during lazy route discovery.
  * @param opts.onError An optional error handler that will be called with any
  * errors that occur during the request processing.
  * @param opts.request The [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
@@ -2418,6 +2456,7 @@ declare function matchRSCServerRequest({
   loadServerAction,
   decodeAction,
   decodeFormState,
+  clientVersion,
   onError,
   request,
   routes,
@@ -2431,6 +2470,7 @@ declare function matchRSCServerRequest({
   decodeFormState?: DecodeFormStateFunction;
   requestContext?: RouterContextProvider;
   loadServerAction?: LoadServerActionFunction;
+  clientVersion?: string;
   onError?: (error: unknown) => void;
   request: Request;
   routes: RSCRouteConfigEntry[];
@@ -2464,14 +2504,30 @@ type Pages = Register extends {
 type Args = { [K in keyof Pages]: ToArgs<Pages[K]["params"]> };
 type ToArgs<Params extends Record<string, string | undefined>> = Equal<Params, {}> extends true ? [] : Partial<Params> extends Params ? [Params] | [] : [Params];
 /**
-  Returns a resolved URL path for the specified route.
-
-  ```tsx
-  const h = href("/:lang?/about", { lang: "en" })
-  // -> `/en/about`
-
-  <Link to={href("/products/:id", { id: "abc123" })} />
-  ```
+ * Returns a resolved URL path for the specified route.
+ *
+ * Param values are percent-encoded for use in a path segment: characters that
+ * would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+ * are escaped, while characters that RFC 3986 allows literally in a path
+ * segment (`$ & + , ; = : @`) are kept as-is. Note this differs from query-string
+ * encoding (`encodeURIComponent`/`URLSearchParams`), where those characters are
+ * delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+ * preserving `/` separators.
+ *
+ * See [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
+ *
+ * @example
+ * const h = href("/:lang?/about", { lang: "en" })
+ * // -> `/en/about`
+ *
+ * <Link to={href("/products/:id", { id: "abc123" })} />
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @param path The route path to resolve
+ * @param args The route params to use when resolving the path
+ * @returns The resolved URL path
  */
 declare function href<Path extends keyof Args>(path: Path, ...args: Args[Path]): string;
 //#endregion
@@ -2527,13 +2583,39 @@ interface Cookie {
 }
 /**
  * Creates a logical container for managing a browser cookie from the server.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param name The name of the cookie.
+ * @param cookieOptions Options for parsing and serializing the cookie.
+ * @returns A {@link Cookie} object for parsing and serializing the cookie.
  */
 declare const createCookie: (name: string, cookieOptions?: CookieOptions) => Cookie;
+/**
+ * A function that determines whether a value is a React Router {@link Cookie}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
+ */
 type IsCookieFunction = (object: any) => object is Cookie;
 /**
- * Returns true if an object is a Remix cookie container.
+ * Returns `true` if a value is a React Router {@link Cookie} object.
  *
- * @see https://remix.run/utils/cookies#iscookie
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
  */
 declare const isCookie: IsCookieFunction;
 //#endregion
@@ -2595,13 +2677,37 @@ type CreateSessionFunction = <Data = SessionData, FlashData = Data>(initialData?
  *
  * Note: This function is typically not invoked directly by application code.
  * Instead, use a `SessionStorage` object's `getSession` method.
+ *
+ * @category Utils
+ * @param initialData The initial data for the session.
+ * @param id The identifier for the session. Defaults to an empty string for a
+ * new session.
+ * @returns A new {@link Session} object.
  */
 declare const createSession: CreateSessionFunction;
+/**
+ * A function that determines whether a value is a React Router {@link Session}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
+ */
 type IsSessionFunction = (object: any) => object is Session;
 /**
- * Returns true if an object is a React Router session.
+ * Returns `true` if a value is a React Router {@link Session} object.
  *
- * @see https://reactrouter.com/api/utils/isSession
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
  */
 declare const isSession: IsSessionFunction;
 /**
@@ -2668,6 +2774,11 @@ interface SessionIdStorageStrategy<Data = SessionData, FlashData = Data> {
  *
  * Note: This is a low-level API that should only be used if none of the
  * existing session storage options meet your requirements.
+ *
+ * @category Utils
+ * @param strategy The strategy used to store session identifiers and data.
+ * @returns A {@link SessionStorage} object that persists session data using the
+ * provided strategy.
  */
 declare function createSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg,
@@ -2693,6 +2804,14 @@ interface CookieSessionStorageOptions {
  * needed, and can help to simplify some load-balanced scenarios. However, it
  * also has the limitation that serialized session data may not exceed the
  * browser's maximum cookie size. Trade-offs!
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the cookie-backed session storage.
+ * @returns A {@link SessionStorage} object that stores all session data in its
+ * cookie.
  */
 declare function createCookieSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg
@@ -2707,11 +2826,17 @@ interface MemorySessionStorageOptions {
   cookie?: SessionIdStorageStrategy["cookie"];
 }
 /**
- * Creates and returns a simple in-memory SessionStorage object, mostly useful
- * for testing and as a reference implementation.
+ * Creates and returns a simple in-memory SessionStorage object.
+ *
+ * Intended for local development and testing. It does not scale beyond a single
+ * process, and all session data is lost when the server process stops/restarts.
  *
- * Note: This storage does not scale beyond a single process, so it is not
- * suitable for most production scenarios.
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the in-memory session storage.
+ * @returns A {@link SessionStorage} object that stores session data in memory.
  */
 declare function createMemorySessionStorage<Data = SessionData, FlashData = Data>({
   cookie