react-router 0.0.0-experimental-2a6c7bc → 0.0.0-experimental-e89ad3012

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

@@ -227,27 +227,117 @@ type Submission = {
     json: undefined;
     text: string;
 };
+/**
+ * A context instance used as the key for the `get`/`set` methods of a
+ * {@link unstable_RouterContextProvider}. Accepts an optional default
+ * value to be returned if no value has been set.
+ */
 interface unstable_RouterContext<T = unknown> {
     defaultValue?: T;
 }
 /**
- * Creates a context object that may be used to store and retrieve arbitrary values.
+ * Creates a type-safe context object that can be used to store and retrieve
+ * values in middleware, [loaders](../../start/framework/route-module#loader),
+ * and [actions](../../start/framework/route-module#action). Similar to React's
+ * [`createContext`](https://react.dev/reference/react/createContext), but
+ * designed for React Router's request/response lifecycle.
+ *
+ * If a `defaultValue` is provided, it will be returned from `context.get()` when
+ * no value has been set for the context. Otherwise reading this context when no
+ * value has been set will throw an error.
  *
- * If a `defaultValue` is provided, it will be returned from `context.get()` when no value has been
- * set for the context. Otherwise reading this context when no value has been set will throw an
- * error.
+ * ```tsx filename=app/context.ts
+ * import { unstable_createContext } from "react-router";
+ *
+ * // Create a context for user data
+ * export const userContext =
+ *   unstable_createContext<User | null>(null);
+ * ```
+ *
+ * ```tsx filename=app/middleware/auth.ts
+ * import { userContext } from "~/context";
+ * import { getUserFromSession } from "~/auth.server";
+ *
+ * export const authMiddleware = async ({
+ *   request,
+ *   context,
+ * }) => {
+ *   const user = await getUserFromSession(request);
+ *   context.set(userContext, user);
+ * };
+ * ```
  *
- * @param defaultValue The default value for the context
- * @returns A context object
+ * ```tsx filename=app/routes/profile.tsx
+ * import { userContext } from "~/context";
+ *
+ * export async function loader({
+ *   context,
+ * }: Route.LoaderArgs) {
+ *   const user = context.get(userContext);
+ *
+ *   if (!user) {
+ *     throw new Response("Unauthorized", { status: 401 });
+ *   }
+ *
+ *   return { user };
+ * }
+ * ```
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param defaultValue An optional default value for the context. This value will
+ * be returned if no value has been set for this context.
+ * @returns A {@link unstable_RouterContext} object that can be used with
+ * `context.get()` and `context.set()` in middleware, loaders, and actions.
  */
 declare function unstable_createContext<T>(defaultValue?: T): unstable_RouterContext<T>;
 /**
- * Provides methods for writing/reading values in application context in a typesafe way.
+ * Provides methods for writing/reading values in application context in a
+ * type-safe way.  Primarily for usage with [Middleware](../../how-to/middleware).
+ *
+ * @example
+ * import {
+ *   unstable_createContext,
+ *   unstable_RouterContextProvider
+ * } from "react-router";
+ *
+ * const userContext = unstable_createContext<User | null>(null);
+ * const contextProvider = new unstable_RouterContextProvider();
+ * contextProvider.set(userContext, getUser());
+ * const user = contextProvider.get(userContext);
+ * //    ^ User
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
  */
 declare class unstable_RouterContextProvider {
     #private;
+    /**
+     * Create a new `unstable_RouterContextProvider` instance
+     * @param init An optional initial context map to populate the provider with
+     */
     constructor(init?: Map<unstable_RouterContext, unknown>);
+    /**
+     * Access a value from the context. If no value has been set for the
+     * context, it will return the context's `defaultValue` if provided, or throw an
+     * error if no `defaultValue` was set.
+     * @param context The context to get the value for
+     * @returns The value for the context, or the contexts `defaultValue` if no
+     * value was set
+     */
     get<T>(context: unstable_RouterContext<T>): T;
+    /**
+     * Set a value for the context. If the context already has a value set,
+     * this will overwrite it.
+     *
+     * @param context The context to set the value for
+     * @param value The value to set for the context
+     * @returns {void}
+     */
     set<C extends unstable_RouterContext>(context: C, value: C extends unstable_RouterContext<infer T> ? T : never): void;
 }
 type DefaultContext = MiddlewareEnabled extends true ? Readonly<unstable_RouterContextProvider> : any;
@@ -272,7 +362,7 @@ interface DataFunctionArgs<Context> {
      *   params.teamId;
      *   //        ^ string
      * }
-     **/
+     */
     params: Params;
     /**
      * This is the context passed in to your server adapter's getLoadContext() function.
@@ -587,7 +677,27 @@ interface AgnosticDataRouteMatch extends AgnosticRouteMatch<string, AgnosticData
 /**
  * Matches the given routes to a location and returns the match data.
  *
+ * @example
+ * import { matchRoutes } from "react-router";
+ *
+ * let routes = [{
+ *   path: "/",
+ *   Component: Root,
+ *   children: [{
+ *     path: "dashboard",
+ *     Component: Dashboard,
+ *   }]
+ * }];
+ *
+ * matchRoutes(routes, "/dashboard"); // [rootMatch, dashboardMatch]
+ *
+ * @public
  * @category Utils
+ * @param routes The array of route objects to match against.
+ * @param locationArg The location to match against, either a string path or a
+ * partial {@link Location} object
+ * @param basename Optional base path to strip from the location before matching.
+ * @returns An array of matched routes, or `null` if no matches were found.
  */
 declare function matchRoutes<RouteObjectType extends AgnosticRouteObject = AgnosticRouteObject>(routes: RouteObjectType[], locationArg: Partial<Location> | string, basename?: string): AgnosticRouteMatch<string, RouteObjectType>[] | null;
 interface UIMatch<Data = unknown, Handle = unknown> {
@@ -595,7 +705,7 @@ interface UIMatch<Data = unknown, Handle = unknown> {
     pathname: string;
     /**
      * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the matched route.
-     **/
+     */
     params: AgnosticRouteMatch["params"];
     /**
      * The return value from the matched route's loader or clientLoader
@@ -616,9 +726,29 @@ declare class DataWithResponseInit<D> {
 }
 /**
  * Create "responses" that contain `status`/`headers` without forcing
- * serialization into an actual `Response` - used by Remix single fetch
+ * serialization into an actual `Response`
  *
+ * @example
+ * import { data } from "react-router";
+ *
+ * export async function action({ request }) {
+ *   let formData = await request.formData();
+ *   let item = await createItem(formData);
+ *   return data(item, {
+ *     status: 201,
+ *     headers: { "X-Custom-Header": "value" }
+ *   });
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param data The data to be included in the response.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `DataWithResponseInit` instance containing the data and response
+ * init.
  */
 declare function data<D>(data: D, init?: number | ResponseInit): DataWithResponseInit<D>;
 type RedirectFunction = (url: string, init?: number | ResponseInit) => Response;
@@ -626,7 +756,25 @@ type RedirectFunction = (url: string, init?: number | ResponseInit) => Response;
  * A redirect response. Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * import { redirect } from "react-router";
+ *
+ * export function loader({ request }) {
+ *   if (!isLoggedIn(request))
+ *     throw redirect("/login");
+ *   }
+ *
+ *   // ...
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const redirect$1: RedirectFunction;
 /**
@@ -634,7 +782,26 @@ declare const redirect$1: RedirectFunction;
  * Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * // routes/logout.tsx
+ * import { redirectDocument } from "react-router";
+ * import { destroySession } from "../sessions.server";
+ *
+ * export async function action({ request }) {
+ *   let session = await getSession(request.headers.get("Cookie"));
+ *   return redirectDocument("/", {
+ *     headers: { "Set-Cookie": await destroySession(session) }
+ *   });
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const redirectDocument$1: RedirectFunction;
 /**
@@ -643,7 +810,21 @@ declare const redirectDocument$1: RedirectFunction;
  * Sets the status code and the `Location` header.
  * Defaults to "302 Found".
  *
+ * @example
+ * import { replace } from "react-router";
+ *
+ * export function loader() {
+ *   return replace("/new-location");
+ * }
+ *
+ * @public
  * @category Utils
+ * @mode framework
+ * @mode data
+ * @param url The URL to redirect to.
+ * @param init The status code or a `ResponseInit` object to be included in the
+ * response.
+ * @returns A `Response` object with the redirect status and `Location` header.
  */
 declare const replace$1: RedirectFunction;
 
@@ -956,15 +1137,13 @@ interface StaticHandler {
         skipLoaderErrorBubbling?: boolean;
         skipRevalidation?: boolean;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_respond?: (staticContext: StaticHandlerContext) => MaybePromise<Response>;
-        unstable_stream?: (context: unstable_RouterContextProvider, query: (r: Request) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
+        unstable_generateMiddlewareResponse?: (query: (r: Request) => Promise<StaticHandlerContext | Response>) => MaybePromise<Response>;
     }): Promise<StaticHandlerContext | Response>;
     queryRoute(request: Request, opts?: {
         routeId?: string;
         requestContext?: unknown;
         dataStrategy?: DataStrategyFunction<unknown>;
-        unstable_respond?: (res: Response) => MaybePromise<Response>;
-        unstable_stream?: (context: unstable_RouterContextProvider, queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
+        unstable_generateMiddlewareResponse?: (queryRoute: (r: Request) => Promise<Response>) => MaybePromise<Response>;
     }): Promise<any>;
 }
 type ViewTransitionOpts = {