@oomfware/stacker 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -0
- package/dist/index.d.mts +14 -2
- package/dist/index.mjs +123 -20
- package/dist/testing.d.mts +1 -1
- package/dist/testing.mjs +7 -4
- package/dist/{types-Dj7Al7f8.d.mts → types-KOb6CZ7N.d.mts} +8 -6
- package/dist/{url-CoOVqRk_.mjs → url-gf-m_-s3.mjs} +9 -1
- package/package.json +5 -10
- package/src/build.ts +0 -53
- package/src/cache.ts +0 -53
- package/src/codec.ts +0 -182
- package/src/history/memory.ts +0 -155
- package/src/history/navigation.ts +0 -213
- package/src/history/types.ts +0 -133
- package/src/index.ts +0 -52
- package/src/keys.ts +0 -41
- package/src/match.ts +0 -180
- package/src/react/context.ts +0 -18
- package/src/react/hooks.ts +0 -178
- package/src/react/link.tsx +0 -61
- package/src/react/outlet.tsx +0 -18
- package/src/react/router-view.tsx +0 -79
- package/src/router.ts +0 -397
- package/src/routes.ts +0 -325
- package/src/testing.ts +0 -2
- package/src/url.ts +0 -41
- package/src/view-model.ts +0 -78
package/src/router.ts
DELETED
|
@@ -1,397 +0,0 @@
|
|
|
1
|
-
import { SimpleEventEmitter } from '@mary-ext/simple-event-emitter';
|
|
2
|
-
import type { ComponentType, ReactNode } from 'react';
|
|
3
|
-
|
|
4
|
-
import { Builder } from './build.ts';
|
|
5
|
-
import type { BuildArgs } from './build.ts';
|
|
6
|
-
import type { CacheEntryRef } from './cache.ts';
|
|
7
|
-
import { computeCachedKeys } from './cache.ts';
|
|
8
|
-
import type { History, HistoryLocation } from './history/types.ts';
|
|
9
|
-
import { Matcher } from './match.ts';
|
|
10
|
-
import type { RouteMatch } from './match.ts';
|
|
11
|
-
import type { ResolvedLeaf, ResolvedNode, RouteLeaf, RouteName, RouteRegistry } from './routes.ts';
|
|
12
|
-
import { createPath, parsePath } from './url.ts';
|
|
13
|
-
import { computeView } from './view-model.ts';
|
|
14
|
-
import type { PoolEntry, View } from './view-model.ts';
|
|
15
|
-
|
|
16
|
-
/** options for the router constructor. */
|
|
17
|
-
export interface RouterOptions<R extends RouteRegistry<unknown>> {
|
|
18
|
-
/** default fallback component shown during lazy chunk loading. */
|
|
19
|
-
readonly defaultFallback?: ReactNode;
|
|
20
|
-
/** backing history instance. */
|
|
21
|
-
readonly history: History;
|
|
22
|
-
/** maximum number of backward entries to keep warm. */
|
|
23
|
-
readonly max?: number;
|
|
24
|
-
/** component rendered when no route matches. */
|
|
25
|
-
readonly notFound?: ComponentType;
|
|
26
|
-
/** route names of pathless singleton routes to keep warm for the router's lifetime once first visited. */
|
|
27
|
-
readonly pins?: readonly string[];
|
|
28
|
-
/** compiled route registry. */
|
|
29
|
-
readonly routes: R;
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
interface Entry {
|
|
33
|
-
readonly index: number;
|
|
34
|
-
readonly key: string;
|
|
35
|
-
readonly match: RouteMatch;
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
const DefaultNotFound: ComponentType = () => null;
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* manages navigation state, history subscriptions, and active views.
|
|
42
|
-
*
|
|
43
|
-
* this class acts as the store for the React router view, maintaining and caching active matched nodes and
|
|
44
|
-
* coordinates scrolling and focus.
|
|
45
|
-
*/
|
|
46
|
-
export class Router<R extends RouteRegistry<unknown>> {
|
|
47
|
-
readonly #history: History;
|
|
48
|
-
readonly #matcher: Matcher;
|
|
49
|
-
readonly #builder: Builder<R>;
|
|
50
|
-
readonly #routes: R;
|
|
51
|
-
readonly #max: number;
|
|
52
|
-
readonly #defaultFallback: ReactNode;
|
|
53
|
-
readonly #notFound: { leaf: ResolvedLeaf; node: ResolvedNode };
|
|
54
|
-
readonly #pins: ReadonlyMap<string, PoolEntry>;
|
|
55
|
-
readonly #updates = new SimpleEventEmitter<[]>();
|
|
56
|
-
readonly #unlisten: () => void;
|
|
57
|
-
|
|
58
|
-
#activePins = new Set<PoolEntry>();
|
|
59
|
-
#entries = new Map<string, Entry>();
|
|
60
|
-
#activeKey: string;
|
|
61
|
-
#recency: string[] = [];
|
|
62
|
-
#view: View;
|
|
63
|
-
#commitWaiters: (() => void)[] = [];
|
|
64
|
-
#viewAttached = false;
|
|
65
|
-
|
|
66
|
-
constructor(options: RouterOptions<R>) {
|
|
67
|
-
this.#history = options.history;
|
|
68
|
-
this.#routes = options.routes;
|
|
69
|
-
this.#matcher = new Matcher(options.routes);
|
|
70
|
-
this.#builder = new Builder(options.routes);
|
|
71
|
-
this.#max = options.max ?? 5;
|
|
72
|
-
this.#defaultFallback = options.defaultFallback;
|
|
73
|
-
this.#notFound = makeNotFound(options.notFound ?? DefaultNotFound);
|
|
74
|
-
this.#pins = new Map((options.pins ?? []).map((name) => [name, this.#makePin(name)]));
|
|
75
|
-
|
|
76
|
-
const location = this.#history.location;
|
|
77
|
-
this.#activeKey = location.key;
|
|
78
|
-
this.#record(location);
|
|
79
|
-
this.#view = this.#recompute();
|
|
80
|
-
|
|
81
|
-
this.#unlisten = this.#history.listen(async ({ location: next }) => {
|
|
82
|
-
this.#prune();
|
|
83
|
-
this.#record(next);
|
|
84
|
-
this.#activeKey = next.key;
|
|
85
|
-
this.#view = this.#recompute();
|
|
86
|
-
// register before notifying because subscribers may render synchronously.
|
|
87
|
-
const committed = this.#awaitCommit();
|
|
88
|
-
this.#updates.emit();
|
|
89
|
-
await committed;
|
|
90
|
-
});
|
|
91
|
-
}
|
|
92
|
-
|
|
93
|
-
/** current view structure. */
|
|
94
|
-
get view(): View {
|
|
95
|
-
return this.#view;
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
/** active history location. */
|
|
99
|
-
get location(): HistoryLocation {
|
|
100
|
-
return this.#history.location;
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
/** active route match details. */
|
|
104
|
-
get route(): RouteMatch {
|
|
105
|
-
return this.#active().match;
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
/** whether backward history is available. */
|
|
109
|
-
get canGoBack(): boolean {
|
|
110
|
-
return this.#history.canGoBack;
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
/** whether forward history is available. */
|
|
114
|
-
get canGoForward(): boolean {
|
|
115
|
-
return this.#history.canGoForward;
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
/** default suspense fallback component. */
|
|
119
|
-
get defaultFallback(): ReactNode {
|
|
120
|
-
return this.#defaultFallback;
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
/** the compiled registry this router was constructed with. */
|
|
124
|
-
get routes(): R {
|
|
125
|
-
return this.#routes;
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/**
|
|
129
|
-
* subscribes to view updates.
|
|
130
|
-
*
|
|
131
|
-
* bound to the instance, so it keeps one identity for the router's lifetime and can be handed straight to
|
|
132
|
-
* `useSyncExternalStore` — which re-subscribes whenever the function it is given changes.
|
|
133
|
-
*
|
|
134
|
-
* @param listener change callback
|
|
135
|
-
* @returns unsubscribe function
|
|
136
|
-
*/
|
|
137
|
-
readonly subscribe = (listener: () => void): (() => void) => {
|
|
138
|
-
return this.#updates.subscribe(listener);
|
|
139
|
-
};
|
|
140
|
-
|
|
141
|
-
/** pushes a new location onto the history stack. */
|
|
142
|
-
push(to: string): void {
|
|
143
|
-
this.#history.push(to);
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
/** replaces the current location on the history stack. */
|
|
147
|
-
replace(to: string): void {
|
|
148
|
-
this.#history.replace(to);
|
|
149
|
-
}
|
|
150
|
-
|
|
151
|
-
/**
|
|
152
|
-
* generates a URL for a route.
|
|
153
|
-
*
|
|
154
|
-
* @param name route name
|
|
155
|
-
* @param args route parameters
|
|
156
|
-
* @returns relative URL
|
|
157
|
-
*/
|
|
158
|
-
build<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): string {
|
|
159
|
-
return this.#builder.build(name, ...args);
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
/**
|
|
163
|
-
* navigates to a route.
|
|
164
|
-
*
|
|
165
|
-
* @param name route name
|
|
166
|
-
* @param args route parameters
|
|
167
|
-
*/
|
|
168
|
-
navigate<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): void {
|
|
169
|
-
this.push(this.#builder.build(name, ...args));
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
/**
|
|
173
|
-
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
174
|
-
*
|
|
175
|
-
* @param name route name
|
|
176
|
-
* @param args route parameters
|
|
177
|
-
*/
|
|
178
|
-
popTo<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): void {
|
|
179
|
-
const url = this.#builder.build(name, ...args);
|
|
180
|
-
const { hash, pathname, search } = parsePath(url);
|
|
181
|
-
const target = this.#matcher.match(pathname, search, hash);
|
|
182
|
-
if (target !== undefined) {
|
|
183
|
-
const wanted = this.#canonical(target);
|
|
184
|
-
const entries = this.#history.entries();
|
|
185
|
-
for (let i = this.#history.location.index; i >= 0; i--) {
|
|
186
|
-
const entry = entries[i];
|
|
187
|
-
if (entry === undefined || !entry.sameDocument || entry.url === null) {
|
|
188
|
-
break;
|
|
189
|
-
}
|
|
190
|
-
const parts = parsePath(entry.url);
|
|
191
|
-
const match = this.#matcher.match(parts.pathname, parts.search, parts.hash);
|
|
192
|
-
if (match !== undefined && match.name === target.name && this.#canonical(match) === wanted) {
|
|
193
|
-
this.#history.traverseTo(entry.key);
|
|
194
|
-
return;
|
|
195
|
-
}
|
|
196
|
-
}
|
|
197
|
-
}
|
|
198
|
-
this.push(url);
|
|
199
|
-
}
|
|
200
|
-
|
|
201
|
-
/**
|
|
202
|
-
* updates query parameters in-place without pushing a new entry.
|
|
203
|
-
*
|
|
204
|
-
* @param patch query parameter changes
|
|
205
|
-
*/
|
|
206
|
-
setParams(patch: Readonly<Record<string, unknown>>): void {
|
|
207
|
-
const active = this.#entries.get(this.#activeKey);
|
|
208
|
-
const leaf = active === undefined ? undefined : this.#routes.leaves.get(active.match.name);
|
|
209
|
-
if (leaf === undefined) {
|
|
210
|
-
return;
|
|
211
|
-
}
|
|
212
|
-
const location = this.#history.location;
|
|
213
|
-
const search = new URLSearchParams(location.search);
|
|
214
|
-
for (const [name, value] of Object.entries(patch)) {
|
|
215
|
-
const codec = leaf.query[name];
|
|
216
|
-
if (codec === undefined) {
|
|
217
|
-
continue;
|
|
218
|
-
}
|
|
219
|
-
if (value === undefined) {
|
|
220
|
-
search.delete(name);
|
|
221
|
-
} else {
|
|
222
|
-
search.set(name, codec.encode(value));
|
|
223
|
-
}
|
|
224
|
-
}
|
|
225
|
-
const query = search.toString();
|
|
226
|
-
const to = createPath({
|
|
227
|
-
hash: location.hash,
|
|
228
|
-
pathname: location.pathname,
|
|
229
|
-
search: query ? `?${query}` : '',
|
|
230
|
-
});
|
|
231
|
-
this.#history.replace(to, { scroll: 'preserve', state: location.state });
|
|
232
|
-
}
|
|
233
|
-
|
|
234
|
-
/** navigates back one entry. */
|
|
235
|
-
back(): void {
|
|
236
|
-
this.#history.back();
|
|
237
|
-
}
|
|
238
|
-
|
|
239
|
-
/** navigates forward one entry. */
|
|
240
|
-
forward(): void {
|
|
241
|
-
this.#history.forward();
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
/** navigates by a delta offset on the stack. */
|
|
245
|
-
go(delta: number): void {
|
|
246
|
-
this.#history.go(delta);
|
|
247
|
-
}
|
|
248
|
-
|
|
249
|
-
/**
|
|
250
|
-
* attaches a router view to coordinate transition commits.
|
|
251
|
-
*
|
|
252
|
-
* @returns detach function
|
|
253
|
-
*/
|
|
254
|
-
attachView(): () => void {
|
|
255
|
-
this.#viewAttached = true;
|
|
256
|
-
return () => {
|
|
257
|
-
this.#viewAttached = false;
|
|
258
|
-
this.notifyCommit();
|
|
259
|
-
};
|
|
260
|
-
}
|
|
261
|
-
|
|
262
|
-
/** resolves pending navigation transitions after a view commits. */
|
|
263
|
-
notifyCommit(): void {
|
|
264
|
-
for (const resolve of this.#commitWaiters.splice(0)) {
|
|
265
|
-
resolve();
|
|
266
|
-
}
|
|
267
|
-
}
|
|
268
|
-
|
|
269
|
-
/** detaches history listeners and disposes resources. */
|
|
270
|
-
dispose(): void {
|
|
271
|
-
this.#unlisten();
|
|
272
|
-
this.#history.dispose();
|
|
273
|
-
// release transitions waiting on a view that has been disposed.
|
|
274
|
-
this.notifyCommit();
|
|
275
|
-
}
|
|
276
|
-
|
|
277
|
-
#active(): Entry {
|
|
278
|
-
const active = this.#entries.get(this.#activeKey);
|
|
279
|
-
if (active === undefined) {
|
|
280
|
-
throw new Error(`stacker: no warm entry for the active key '${this.#activeKey}'`);
|
|
281
|
-
}
|
|
282
|
-
return active;
|
|
283
|
-
}
|
|
284
|
-
|
|
285
|
-
#match(location: HistoryLocation): RouteMatch {
|
|
286
|
-
return this.#matcher.match(location.pathname, location.search, location.hash) ?? this.#notFoundMatch();
|
|
287
|
-
}
|
|
288
|
-
|
|
289
|
-
// rebuilding normalizes values that codecs decode into fresh object identities.
|
|
290
|
-
#canonical(match: RouteMatch): string {
|
|
291
|
-
return this.#builder.buildPath(match.name, match.params);
|
|
292
|
-
}
|
|
293
|
-
|
|
294
|
-
#awaitCommit(): Promise<void> {
|
|
295
|
-
if (!this.#viewAttached) {
|
|
296
|
-
return Promise.resolve();
|
|
297
|
-
}
|
|
298
|
-
return new Promise((resolve) => {
|
|
299
|
-
this.#commitWaiters.push(resolve);
|
|
300
|
-
});
|
|
301
|
-
}
|
|
302
|
-
|
|
303
|
-
#prune(): void {
|
|
304
|
-
const live = new Set(this.#history.entries().map((entry) => entry.key));
|
|
305
|
-
for (const key of this.#entries.keys()) {
|
|
306
|
-
if (!live.has(key)) {
|
|
307
|
-
this.#entries.delete(key);
|
|
308
|
-
}
|
|
309
|
-
}
|
|
310
|
-
}
|
|
311
|
-
|
|
312
|
-
#record(location: HistoryLocation): void {
|
|
313
|
-
const entry: Entry = { index: location.index, key: location.key, match: this.#match(location) };
|
|
314
|
-
this.#entries.set(location.key, entry);
|
|
315
|
-
this.#recency = [entry.key, ...this.#recency.filter((key) => key !== entry.key)];
|
|
316
|
-
const pin = this.#pins.get(entry.match.name);
|
|
317
|
-
if (pin !== undefined) {
|
|
318
|
-
this.#activePins.add(pin);
|
|
319
|
-
}
|
|
320
|
-
}
|
|
321
|
-
|
|
322
|
-
#recompute(): View {
|
|
323
|
-
const active = this.#active();
|
|
324
|
-
const refs: CacheEntryRef[] = [...this.#entries.values()].map((entry) => ({
|
|
325
|
-
index: entry.index,
|
|
326
|
-
key: entry.key,
|
|
327
|
-
}));
|
|
328
|
-
const cachedKeys = computeCachedKeys(refs, active.index, this.#recency, { max: this.#max });
|
|
329
|
-
|
|
330
|
-
const cached: PoolEntry[] = [];
|
|
331
|
-
for (const entry of this.#entries.values()) {
|
|
332
|
-
if (cachedKeys.has(entry.key)) {
|
|
333
|
-
cached.push({ key: entry.key, match: entry.match });
|
|
334
|
-
}
|
|
335
|
-
}
|
|
336
|
-
const view = computeView(cached, [...this.#activePins], active.key);
|
|
337
|
-
|
|
338
|
-
for (const [key, entry] of this.#entries) {
|
|
339
|
-
if (!cachedKeys.has(entry.key)) {
|
|
340
|
-
this.#entries.delete(key);
|
|
341
|
-
}
|
|
342
|
-
}
|
|
343
|
-
this.#recency = this.#recency.filter((key) => this.#entries.has(key));
|
|
344
|
-
|
|
345
|
-
return view;
|
|
346
|
-
}
|
|
347
|
-
|
|
348
|
-
#makePin(name: string): PoolEntry {
|
|
349
|
-
const leaf = this.#routes.leaves.get(name);
|
|
350
|
-
if (leaf === undefined) {
|
|
351
|
-
throw new Error(`stacker: pinned route '${name}' is not in the registry`);
|
|
352
|
-
}
|
|
353
|
-
// pins must resolve to one instance shared with active visits.
|
|
354
|
-
if ((leaf.leaf.type ?? 'page') !== 'singleton') {
|
|
355
|
-
throw new Error(`stacker: pinned route '${name}' must be a singleton`);
|
|
356
|
-
}
|
|
357
|
-
if (Object.keys(leaf.params).length > 0) {
|
|
358
|
-
throw new Error(`stacker: pinned route '${name}' must have no path params`);
|
|
359
|
-
}
|
|
360
|
-
const { hash, pathname, search } = parsePath(leaf.path);
|
|
361
|
-
const match = this.#matcher.match(pathname, search, hash);
|
|
362
|
-
if (match === undefined) {
|
|
363
|
-
throw new Error(`stacker: pinned route '${name}' (path '${leaf.path}') did not match`);
|
|
364
|
-
}
|
|
365
|
-
return { key: `pin:${name}`, match };
|
|
366
|
-
}
|
|
367
|
-
|
|
368
|
-
#notFoundMatch(): RouteMatch {
|
|
369
|
-
return {
|
|
370
|
-
chain: [{ node: this.#notFound.node, params: {} }],
|
|
371
|
-
leaf: this.#notFound.leaf,
|
|
372
|
-
name: this.#notFound.leaf.name,
|
|
373
|
-
params: {},
|
|
374
|
-
};
|
|
375
|
-
}
|
|
376
|
-
}
|
|
377
|
-
|
|
378
|
-
const makeNotFound = (component: ComponentType): { leaf: ResolvedLeaf; node: ResolvedNode } => {
|
|
379
|
-
const leafNode: RouteLeaf = { component, kind: 'route', params: {}, path: '*', query: {}, type: 'page' };
|
|
380
|
-
const node: ResolvedNode = {
|
|
381
|
-
id: ' notFound',
|
|
382
|
-
key: ' notFound',
|
|
383
|
-
kind: 'route',
|
|
384
|
-
node: leafNode,
|
|
385
|
-
params: {},
|
|
386
|
-
path: '*',
|
|
387
|
-
};
|
|
388
|
-
const leaf: ResolvedLeaf = {
|
|
389
|
-
chain: [node],
|
|
390
|
-
leaf: leafNode,
|
|
391
|
-
name: ' notFound',
|
|
392
|
-
params: {},
|
|
393
|
-
path: '*',
|
|
394
|
-
query: {},
|
|
395
|
-
};
|
|
396
|
-
return { leaf, node };
|
|
397
|
-
};
|