@@ -123,15 +123,17 @@ export interface unstable_RouterContext<T = unknown> {
123
123
}
124
124
125
125
/**
126
- * Creates a type-safe context object that can be used to store and retrieve
127
- * values in middleware, [loaders ](../../start/framework/route-module#loader) ,
128
- * and [actions ](../../start/framework/route-module#action). Similar to React's
129
- * [`createContext`](https://react.dev/reference/react/createContext), but
130
- * designed for React Router's request/response lifecycle.
126
+ * Creates a type-safe { @link unstable_RouterContext} object that can be used to
127
+ * * store and retrieve arbitrary values in [`action` ](../../start/framework/route-module#action)s ,
128
+ * * [`loader` ](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
129
+ * * Similar to React's [`createContext`](https://react.dev/reference/react/createContext),
130
+ * * but specifically designed for React Router's request/response lifecycle.
131
131
*
132
- * If a `defaultValue` is provided, it will be returned from `context.get()` when
133
- * no value has been set for the context. Otherwise reading this context when no
134
- * value has been set will throw an error.
132
+ * <docs-warning>Enable this API with the `future.unstable_middleware` flag.</docs-warning>
133
+ *
134
+ * If a `defaultValue` is provided, it will be returned from `context.get()`
135
+ * when no value has been set for the context. Otherwise, reading this context
136
+ * when no value has been set will throw an error.
135
137
*
136
138
* ```tsx filename=app/context.ts
137
139
* import { unstable_createContext } from "react-router";
@@ -142,12 +144,12 @@ export interface unstable_RouterContext<T = unknown> {
142
144
* ```
143
145
*
144
146
* ```tsx filename=app/middleware/auth.ts
145
- * import { userContext } from "~/context";
146
147
* import { getUserFromSession } from "~/auth.server";
148
+ * import { userContext } from "~/context";
147
149
*
148
150
* export const authMiddleware = async ({
149
- * request,
150
151
* context,
152
+ * request,
151
153
* }) => {
152
154
* const user = await getUserFromSession(request);
153
155
* context.set(userContext, user);
@@ -174,10 +176,11 @@ export interface unstable_RouterContext<T = unknown> {
174
176
* @category Utils
175
177
* @mode framework
176
178
* @mode data
177
- * @param defaultValue An optional default value for the context. This value will
178
- * be returned if no value has been set for this context.
179
+ * @param defaultValue An optional default value for the context. This value
180
+ * will be returned if no value has been set for this context.
179
181
* @returns A {@link unstable_RouterContext} object that can be used with
180
- * `context.get()` and `context.set()` in middleware, loaders, and actions.
182
+ * `context.get()` and `context.set()` in [`action`](../../start/framework/route-module#action)s,
183
+ * [`loader`](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
181
184
*/
182
185
export function unstable_createContext < T > (
183
186
defaultValue ?: T ,
@@ -187,7 +190,7 @@ export function unstable_createContext<T>(
187
190
188
191
/**
189
192
* Provides methods for writing/reading values in application context in a
190
- * type-safe way. Primarily for usage with [Middleware ](../../how-to/middleware).
193
+ * type-safe way. Primarily for usage with [middleware ](../../how-to/middleware).
191
194
*
192
195
* @example
193
196
* import {
@@ -222,11 +225,11 @@ export class unstable_RouterContextProvider {
222
225
}
223
226
224
227
/**
225
- * Access a value from the context. If no value has been set for the
226
- * context, it will return the context's `defaultValue` if provided, or throw an
227
- * error if no `defaultValue` was set.
228
+ * Access a value from the context. If no value has been set for the context,
229
+ * it will return the context's `defaultValue` if provided, or throw an error
230
+ * if no `defaultValue` was set.
228
231
* @param context The context to get the value for
229
- * @returns The value for the context, or the contexts `defaultValue` if no
232
+ * @returns The value for the context, or the context's `defaultValue` if no
230
233
* value was set
231
234
*/
232
235
get < T > ( context : unstable_RouterContext < T > ) : T {
@@ -242,8 +245,8 @@ export class unstable_RouterContextProvider {
242
245
}
243
246
244
247
/**
245
- * Set a value for the context. If the context already has a value set,
246
- * this will overwrite it.
248
+ * Set a value for the context. If the context already has a value set, this
249
+ * will overwrite it.
247
250
*
248
251
* @param context The context to set the value for
249
252
* @param value The value to set for the context
@@ -860,6 +863,7 @@ export function convertRoutesToDataRoutes(
860
863
* @param locationArg The location to match against, either a string path or a
861
864
* partial {@link Location} object
862
865
* @param basename Optional base path to strip from the location before matching.
866
+ * Defaults to `/`.
863
867
* @returns An array of matched routes, or `null` if no matches were found.
864
868
*/
865
869
export function matchRoutes <
@@ -1290,13 +1294,13 @@ export function generatePath<Path extends string>(
1290
1294
}
1291
1295
1292
1296
/**
1293
- * A PathPattern is used to match on some portion of a URL pathname.
1297
+ * Used to match on some portion of a URL pathname.
1294
1298
*/
1295
1299
export interface PathPattern < Path extends string = string > {
1296
1300
/**
1297
1301
* A string to match against a URL pathname. May contain `:id`-style segments
1298
- * to indicate placeholders for dynamic parameters. May also end with `/*` to
1299
- * indicate matching the rest of the URL pathname.
1302
+ * to indicate placeholders for dynamic parameters. It May also end with `/*`
1303
+ * to indicate matching the rest of the URL pathname.
1300
1304
*/
1301
1305
path : Path ;
1302
1306
/**
@@ -1311,7 +1315,7 @@ export interface PathPattern<Path extends string = string> {
1311
1315
}
1312
1316
1313
1317
/**
1314
- * A PathMatch contains info about how a PathPattern matched on a URL pathname.
1318
+ * Contains info about how a { @link PathPattern} matched on a URL pathname.
1315
1319
*/
1316
1320
export interface PathMatch < ParamKey extends string = string > {
1317
1321
/**
@@ -1343,9 +1347,9 @@ type Mutable<T> = {
1343
1347
* @public
1344
1348
* @category Utils
1345
1349
* @param pattern The pattern to match against the URL pathname. This can be a
1346
- * string or a {@link PathPattern} object. If a string is provided, it will
1347
- * be treated as a pattern with `caseSensitive` set to `false` and `end
1348
- * set to `true`.
1350
+ * string or a {@link PathPattern} object. If a string is provided, it will be
1351
+ * treated as a pattern with `caseSensitive` set to `false` and `end` set to
1352
+ * `true`.
1349
1353
* @param pathname The URL pathname to match against the pattern.
1350
1354
* @returns A path match object if the pattern matches the pathname,
1351
1355
* or `null` if it does not match.
@@ -1516,11 +1520,12 @@ export function prependBasename({
1516
1520
}
1517
1521
1518
1522
/**
1519
- * Returns a resolved path object relative to the given pathname.
1523
+ * Returns a resolved { @link Path} object relative to the given pathname.
1520
1524
*
1521
1525
* @public
1522
1526
* @category Utils
1523
- * @param to The path to resolve, either a string or a partial {@link Path} object.
1527
+ * @param to The path to resolve, either a string or a partial {@link Path}
1528
+ * object.
1524
1529
* @param fromPathname The pathname to resolve the path from. Defaults to `/`.
1525
1530
* @returns A {@link Path} object with the resolved pathname, search, and hash.
1526
1531
*/
@@ -1733,18 +1738,18 @@ export class DataWithResponseInit<D> {
1733
1738
}
1734
1739
1735
1740
/**
1736
- * Create "responses" that contain `status `/`headers ` without forcing
1737
- * serialization into an actual `Response`
1741
+ * Create "responses" that contain `headers `/`status ` without forcing
1742
+ * serialization into an actual [ `Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1738
1743
*
1739
1744
* @example
1740
1745
* import { data } from "react-router";
1741
1746
*
1742
- * export async function action({ request }) {
1747
+ * export async function action({ request }: Route.ActionArgs ) {
1743
1748
* let formData = await request.formData();
1744
1749
* let item = await createItem(formData);
1745
1750
* return data(item, {
1746
- * status: 201,
1747
1751
* headers: { "X-Custom-Header": "value" }
1752
+ * status: 201,
1748
1753
* });
1749
1754
* }
1750
1755
*
@@ -1755,8 +1760,8 @@ export class DataWithResponseInit<D> {
1755
1760
* @param data The data to be included in the response.
1756
1761
* @param init The status code or a `ResponseInit` object to be included in the
1757
1762
* response.
1758
- * @returns A ` DataWithResponseInit` instance containing the data and response
1759
- * init.
1763
+ * @returns A { @link DataWithResponseInit} instance containing the data and
1764
+ * response init.
1760
1765
*/
1761
1766
export function data < D > ( data : D , init ?: number | ResponseInit ) {
1762
1767
return new DataWithResponseInit (
@@ -1779,13 +1784,14 @@ export type RedirectFunction = (
1779
1784
) => Response ;
1780
1785
1781
1786
/**
1782
- * A redirect response. Sets the status code and the `Location` header.
1783
- * Defaults to "302 Found".
1787
+ * A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
1788
+ * Sets the status code and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1789
+ * header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
1784
1790
*
1785
1791
* @example
1786
1792
* import { redirect } from "react-router";
1787
1793
*
1788
- * export function loader({ request }) {
1794
+ * export async function loader({ request }: Route.LoaderArgs ) {
1789
1795
* if (!isLoggedIn(request))
1790
1796
* throw redirect("/login");
1791
1797
* }
@@ -1800,7 +1806,9 @@ export type RedirectFunction = (
1800
1806
* @param url The URL to redirect to.
1801
1807
* @param init The status code or a `ResponseInit` object to be included in the
1802
1808
* response.
1803
- * @returns A `Response` object with the redirect status and `Location` header.
1809
+ * @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1810
+ * object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1811
+ * header.
1804
1812
*/
1805
1813
export const redirect : RedirectFunction = ( url , init = 302 ) => {
1806
1814
let responseInit = init ;
@@ -1817,21 +1825,23 @@ export const redirect: RedirectFunction = (url, init = 302) => {
1817
1825
} ;
1818
1826
1819
1827
/**
1820
- * A redirect response that will force a document reload to the new location.
1821
- * Sets the status code and the `Location` header.
1822
- * Defaults to "302 Found".
1828
+ * A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1829
+ * that will force a document reload to the new location. Sets the status code
1830
+ * and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1831
+ * header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
1823
1832
*
1824
- * @example
1825
- * // routes/logout.tsx
1833
+ * ```tsx filename=routes/logout.tsx
1826
1834
* import { redirectDocument } from "react-router";
1835
+ *
1827
1836
* import { destroySession } from "../sessions.server";
1828
1837
*
1829
- * export async function action({ request }) {
1838
+ * export async function action({ request }: Route.ActionArgs ) {
1830
1839
* let session = await getSession(request.headers.get("Cookie"));
1831
1840
* return redirectDocument("/", {
1832
1841
* headers: { "Set-Cookie": await destroySession(session) }
1833
1842
* });
1834
1843
* }
1844
+ * ```
1835
1845
*
1836
1846
* @public
1837
1847
* @category Utils
@@ -1840,7 +1850,9 @@ export const redirect: RedirectFunction = (url, init = 302) => {
1840
1850
* @param url The URL to redirect to.
1841
1851
* @param init The status code or a `ResponseInit` object to be included in the
1842
1852
* response.
1843
- * @returns A `Response` object with the redirect status and `Location` header.
1853
+ * @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1854
+ * object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1855
+ * header.
1844
1856
*/
1845
1857
export const redirectDocument : RedirectFunction = ( url , init ) => {
1846
1858
let response = redirect ( url , init ) ;
@@ -1849,15 +1861,16 @@ export const redirectDocument: RedirectFunction = (url, init) => {
1849
1861
} ;
1850
1862
1851
1863
/**
1852
- * A redirect response that will perform a `history.replaceState` instead of a
1853
- * `history.pushState` for client-side navigation redirects.
1854
- * Sets the status code and the `Location` header.
1855
- * Defaults to "302 Found".
1864
+ * A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1865
+ * that will perform a [`history.replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState)
1866
+ * instead of a [`history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState)
1867
+ * for client-side navigation redirects. Sets the status code and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1868
+ * header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
1856
1869
*
1857
1870
* @example
1858
1871
* import { replace } from "react-router";
1859
1872
*
1860
- * export function loader() {
1873
+ * export async function loader() {
1861
1874
* return replace("/new-location");
1862
1875
* }
1863
1876
*
@@ -1868,7 +1881,9 @@ export const redirectDocument: RedirectFunction = (url, init) => {
1868
1881
* @param url The URL to redirect to.
1869
1882
* @param init The status code or a `ResponseInit` object to be included in the
1870
1883
* response.
1871
- * @returns A `Response` object with the redirect status and `Location` header.
1884
+ * @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1885
+ * object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1886
+ * header.
1872
1887
*/
1873
1888
export const replace : RedirectFunction = ( url , init ) => {
1874
1889
let response = redirect ( url , init ) ;
@@ -1915,8 +1930,9 @@ export class ErrorResponseImpl implements ErrorResponse {
1915
1930
}
1916
1931
1917
1932
/**
1918
- * Check if the given error is an ErrorResponse generated from a 4xx/5xx
1919
- * Response thrown from an action/loader
1933
+ * Check if the given error is an {@link ErrorResponse} generated from a 4xx/5xx
1934
+ * [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1935
+ * thrown from an [`action`](../../start/framework/route-module#action)/[`loader`](../../start/framework/route-module#loader)
1920
1936
*
1921
1937
* @example
1922
1938
* import { isRouteErrorResponse } from "react-router";
@@ -1925,7 +1941,7 @@ export class ErrorResponseImpl implements ErrorResponse {
1925
1941
* if (isRouteErrorResponse(error)) {
1926
1942
* return (
1927
1943
* <>
1928
- * <p>Error: {{ error.status}: {error.statusText}} </p>
1944
+ * <p>Error: `${ error.status}: $ {error.statusText}` </p>
1929
1945
* <p>{error.data}</p>
1930
1946
* </>
1931
1947
* );
@@ -1941,7 +1957,7 @@ export class ErrorResponseImpl implements ErrorResponse {
1941
1957
* @mode framework
1942
1958
* @mode data
1943
1959
* @param error The error to check.
1944
- * @returns `true` if the error is an ` ErrorResponse` , `false` otherwise.
1960
+ * @returns `true` if the error is an { @link ErrorResponse} , `false` otherwise.
1945
1961
*
1946
1962
*/
1947
1963
export function isRouteErrorResponse ( error : any ) : error is ErrorResponse {
0 commit comments