UNPKG

8.26 kBTypeScriptView Raw
1
2//#region lib/router/history.d.ts
3/**
4 * Actions represent the type of change to a location value.
5 */
6declare enum Action {
7 /**
8 * A POP indicates a change to an arbitrary index in the history stack, such
9 * as a back or forward navigation. It does not describe the direction of the
10 * navigation, only that the current index changed.
11 *
12 * Note: This is the default action for newly created history objects.
13 */
14 Pop = "POP",
15 /**
16 * A PUSH indicates a new entry being added to the history stack, such as when
17 * a link is clicked and a new page loads. When this happens, all subsequent
18 * entries in the stack are lost.
19 */
20 Push = "PUSH",
21 /**
22 * A REPLACE indicates the entry at the current index in the history stack
23 * being replaced by a new one.
24 */
25 Replace = "REPLACE"
26}
27/**
28 * The pathname, search, and hash values of a URL.
29 */
30interface Path {
31 /**
32 * A URL pathname, beginning with a /.
33 */
34 pathname: string;
35 /**
36 * A URL search string, beginning with a ?.
37 */
38 search: string;
39 /**
40 * A URL fragment identifier, beginning with a #.
41 */
42 hash: string;
43}
44/**
45 * An entry in a history stack. A location contains information about the
46 * URL path, as well as possibly some arbitrary state and a key.
47 */
48interface Location<State = any> extends Path {
49 /**
50 * A value of arbitrary data associated with this location.
51 */
52 state: State;
53 /**
54 * A unique string associated with this location. May be used to safely store
55 * and retrieve data in some other storage API, like `localStorage`.
56 *
57 * Note: This value is always "default" on the initial location.
58 */
59 key: string;
60 /**
61 * The masked location displayed in the URL bar, which differs from the URL the
62 * router is operating on
63 */
64 mask?: Path;
65}
66/**
67 * A change to the current location.
68 */
69interface Update {
70 /**
71 * The action that triggered the change.
72 */
73 action: Action;
74 /**
75 * The new location.
76 */
77 location: Location;
78 /**
79 * The delta between this location and the former location in the history stack
80 */
81 delta: number | null;
82}
83/**
84 * A function that receives notifications about location changes.
85 */
86interface Listener {
87 (update: Update): void;
88}
89/**
90 * Describes a location that is the destination of some navigation used in
91 * {@link Link}, {@link useNavigate}, etc.
92 */
93type To = string | Partial<Path>;
94/**
95 * A history is an interface to the navigation stack. The history serves as the
96 * source of truth for the current location, as well as provides a set of
97 * methods that may be used to change it.
98 *
99 * It is similar to the DOM's `window.history` object, but with a smaller, more
100 * focused API.
101 */
102interface History {
103 /**
104 * The last action that modified the current location. This will always be
105 * Action.Pop when a history instance is first created. This value is mutable.
106 */
107 readonly action: Action;
108 /**
109 * The current location. This value is mutable.
110 */
111 readonly location: Location;
112 /**
113 * Returns a valid href for the given `to` value that may be used as
114 * the value of an <a href> attribute.
115 *
116 * @param to - The destination URL
117 */
118 createHref(to: To): string;
119 /**
120 * Returns a URL for the given `to` value
121 *
122 * @param to - The destination URL
123 */
124 createURL(to: To): URL;
125 /**
126 * Encode a location the same way window.history would do (no-op for memory
127 * history) so we ensure our PUSH/REPLACE navigations for data routers
128 * behave the same as POP
129 *
130 * @param to Unencoded path
131 */
132 encodeLocation(to: To): Path;
133 /**
134 * Pushes a new location onto the history stack, increasing its length by one.
135 * If there were any entries in the stack after the current one, they are
136 * lost.
137 *
138 * @param to - The new URL
139 * @param state - Data to associate with the new location
140 */
141 push(to: To, state?: any): void;
142 /**
143 * Replaces the current location in the history stack with a new one. The
144 * location that was replaced will no longer be available.
145 *
146 * @param to - The new URL
147 * @param state - Data to associate with the new location
148 */
149 replace(to: To, state?: any): void;
150 /**
151 * Navigates `n` entries backward/forward in the history stack relative to the
152 * current index. For example, a "back" navigation would use go(-1).
153 *
154 * @param delta - The delta in the stack index
155 */
156 go(delta: number): void;
157 /**
158 * Sets up a listener that will be called whenever the current location
159 * changes.
160 *
161 * @param listener - A function that will be called when the location changes
162 * @returns unlisten - A function that may be used to stop listening
163 */
164 listen(listener: Listener): () => void;
165}
166/**
167 * A user-supplied object that describes a location. Used when providing
168 * entries to `createMemoryHistory` via its `initialEntries` option.
169 */
170type InitialEntry = string | Partial<Location>;
171type MemoryHistoryOptions = {
172 initialEntries?: InitialEntry[];
173 initialIndex?: number;
174 v5Compat?: boolean;
175};
176/**
177 * A memory history stores locations in memory. This is useful in stateful
178 * environments where there is no web browser, such as node tests or React
179 * Native.
180 */
181interface MemoryHistory extends History {
182 /**
183 * The current index in the history stack.
184 */
185 readonly index: number;
186}
187/**
188 * Memory history stores the current location in memory. It is designed for use
189 * in stateful non-browser environments like tests and React Native.
190 */
191declare function createMemoryHistory(options?: MemoryHistoryOptions): MemoryHistory;
192/**
193 * A browser history stores the current location in regular URLs in a web
194 * browser environment. This is the standard for most web apps and provides the
195 * cleanest URLs the browser's address bar.
196 *
197 * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#browserhistory
198 */
199interface BrowserHistory extends UrlHistory {}
200type BrowserHistoryOptions = UrlHistoryOptions;
201/**
202 * Browser history stores the location in regular URLs. This is the standard for
203 * most web apps, but it requires some configuration on the server to ensure you
204 * serve the same app at multiple URLs.
205 *
206 * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createbrowserhistory
207 */
208declare function createBrowserHistory(options?: BrowserHistoryOptions): BrowserHistory;
209/**
210 * A hash history stores the current location in the fragment identifier portion
211 * of the URL in a web browser environment.
212 *
213 * This is ideal for apps that do not control the server for some reason
214 * (because the fragment identifier is never sent to the server), including some
215 * shared hosting environments that do not provide fine-grained controls over
216 * which pages are served at which URLs.
217 *
218 * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#hashhistory
219 */
220interface HashHistory extends UrlHistory {}
221type HashHistoryOptions = UrlHistoryOptions;
222/**
223 * Hash history stores the location in window.location.hash. This makes it ideal
224 * for situations where you don't want to send the location to the server for
225 * some reason, either because you do cannot configure it or the URL space is
226 * reserved for something else.
227 *
228 * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createhashhistory
229 */
230declare function createHashHistory(options?: HashHistoryOptions): HashHistory;
231/**
232 * @private
233 */
234declare function invariant(value: boolean, message?: string): asserts value;
235declare function invariant<T>(value: T | null | undefined, message?: string): asserts value is T;
236/**
237 * Creates a string URL path from the given pathname, search, and hash components.
238 *
239 * @category Utils
240 */
241declare function createPath({
242 pathname,
243 search,
244 hash
245}: Partial<Path>): string;
246/**
247 * Parses a string URL path into its separate pathname, search, and hash components.
248 *
249 * @category Utils
250 */
251declare function parsePath(path: string): Partial<Path>;
252interface UrlHistory extends History {}
253type UrlHistoryOptions = {
254 window?: Window;
255 v5Compat?: boolean;
256};
257//#endregion
258export { Action, History, InitialEntry, Location, Path, To, createBrowserHistory, createHashHistory, createMemoryHistory, createPath, invariant, parsePath };
\No newline at end of file