@oomfware/stacker 0.2.1 → 0.2.3

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 CHANGED
@@ -186,6 +186,14 @@ router.replace('Profile', { tab: undefined }); // -> /profile/alice
186
186
  unmentioned params keep their values, undeclared keys are ignored, and naming a route other than the
187
187
  one on screen throws.
188
188
 
189
+ `router.updateState` rewrites the active entry's state without navigating at all, useful for the
190
+ things a URL should not carry, like a draft or a scroll anchor:
191
+
192
+ ```ts
193
+ router.updateState({ draft: 'hello' });
194
+ router.updateState({ ...(router.location.state as State), draft: '' });
195
+ ```
196
+
189
197
  a route target is a discriminated union, so narrowing on `name` narrows the params with it:
190
198
 
191
199
  ```ts
@@ -325,6 +333,16 @@ new NavigationHistory({
325
333
  });
326
334
  ```
327
335
 
336
+ ### failed navigations
337
+
338
+ `NavigationHistory` sends navigation and render errors to `onError`. it defaults to `reportError`:
339
+
340
+ ```ts
341
+ new NavigationHistory({
342
+ onError: (error) => captureException(error),
343
+ });
344
+ ```
345
+
328
346
  ### metadata
329
347
 
330
348
  declare custom route metadata using module augmentation:
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { a as HistoryLocation, c as HistoryUpdate, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryScrollBehavior, t as History } from "./types-KOb6CZ7N.mjs";
1
+ import { a as HistoryLocation, c as HistoryUpdate, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryScrollBehavior, t as History } from "./types-kax-GwM6.mjs";
2
2
  import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
3
3
  //#region src/codec.d.ts
4
4
  /**
@@ -322,6 +322,12 @@ interface NavigationHistoryOptions {
322
322
  * @returns true to leave the navigation to the browser
323
323
  */
324
324
  readonly ignore?: (url: URL) => boolean;
325
+ /**
326
+ * handles navigation and render failures. defaults to `Window.reportError`.
327
+ *
328
+ * @param error failure reason
329
+ */
330
+ readonly onError?: (error: unknown) => void;
325
331
  /** window instance to bind to; defaults to global window. */
326
332
  readonly window?: Window;
327
333
  }
@@ -340,7 +346,8 @@ declare class NavigationHistory implements History {
340
346
  entries(): readonly HistoryEntry[];
341
347
  push(to: string, options?: HistoryNavigateOptions): void;
342
348
  replace(to: string, options?: HistoryNavigateOptions): void;
343
- traverseTo(key: string): void;
349
+ updateState(state: unknown): void;
350
+ traverseTo(key: string): Promise<void>;
344
351
  go(delta: number): void;
345
352
  back(): void;
346
353
  forward(): void;
@@ -477,6 +484,8 @@ declare class Router<R extends RouteRegistry<unknown>> {
477
484
  /**
478
485
  * returns to the nearest existing history entry for a route, or pushes if none exists.
479
486
  *
487
+ * pushes the destination if traversal to a matching entry fails.
488
+ *
480
489
  * @param to route target, or a relative URL resolved against the active location
481
490
  */
482
491
  popTo(to: RouteTarget<R> | string): void;
@@ -491,6 +500,17 @@ declare class Router<R extends RouteRegistry<unknown>> {
491
500
  * @throws when `name` is not the active route
492
501
  */
493
502
  replace<K extends RouteName<R>>(name: K, patch: QueryPatchOf<R, K>): void;
503
+ /**
504
+ * rewrites the active history entry's state, without navigating.
505
+ *
506
+ * the entry keeps its URL and slot, so the screen stays mounted and the viewport does not move. the whole
507
+ * state is replaced, so build the next value from `router.location.state` to keep the parts you still want.
508
+ * readers of `useLocation` re-render with it.
509
+ *
510
+ * @param state state data to store on the entry
511
+ * @throws when the state cannot be structured-cloned, leaving the entry as it was
512
+ */
513
+ updateState(state: unknown): void;
494
514
  /** navigates back one entry. */
495
515
  back(): void;
496
516
  /** navigates forward one entry. */
package/dist/index.mjs CHANGED
@@ -388,10 +388,7 @@ const toAction = (type) => {
388
388
  default: return;
389
389
  }
390
390
  };
391
- const ignore = (result) => {
392
- result.committed?.catch(() => {});
393
- result.finished?.catch(() => {});
394
- };
391
+ const isAbort = (error) => typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
395
392
  /**
396
393
  * history implementation backed by the web navigation API.
397
394
  *
@@ -399,17 +396,24 @@ const ignore = (result) => {
399
396
  * metadata and indices are managed natively by the browser.
400
397
  */
401
398
  var NavigationHistory = class {
402
- #win;
403
- #nav;
404
399
  #ignore;
405
400
  #listeners = /* @__PURE__ */ new Set();
401
+ #nav;
402
+ #onError;
403
+ #win;
404
+ #disposed = false;
406
405
  #location;
407
406
  constructor(options = {}) {
408
407
  this.#win = options.window ?? window;
409
408
  this.#nav = this.#win.navigation;
410
409
  this.#ignore = options.ignore;
410
+ this.#onError = options.onError ?? ((error) => {
411
+ this.#win.reportError(error);
412
+ });
411
413
  this.#location = this.#read();
414
+ this.#nav.addEventListener("currententrychange", this.#onCurrentEntryChange);
412
415
  this.#nav.addEventListener("navigate", this.#onNavigate);
416
+ this.#nav.addEventListener("navigateerror", this.#onNavigateError);
413
417
  this.#win.history.scrollRestoration = "manual";
414
418
  }
415
419
  get location() {
@@ -437,20 +441,23 @@ var NavigationHistory = class {
437
441
  replace(to, options = {}) {
438
442
  this.#navigate(to, "replace", options);
439
443
  }
444
+ updateState(state) {
445
+ this.#nav.updateCurrentEntry({ state });
446
+ }
440
447
  traverseTo(key) {
441
- ignore(this.#nav.traverseTo(key));
448
+ return this.#track(this.#nav.traverseTo(key));
442
449
  }
443
450
  go(delta) {
444
451
  const entries = this.#nav.entries();
445
452
  const target = entries[Math.max(0, Math.min(this.#location.index + delta, entries.length - 1))];
446
453
  if (target === void 0 || target.key === this.#location.key) return;
447
- this.traverseTo(target.key);
454
+ this.#report(this.traverseTo(target.key));
448
455
  }
449
456
  back() {
450
- if (this.#nav.canGoBack) ignore(this.#nav.back());
457
+ if (this.#nav.canGoBack) this.#report(this.#track(this.#nav.back()));
451
458
  }
452
459
  forward() {
453
- if (this.#nav.canGoForward) ignore(this.#nav.forward());
460
+ if (this.#nav.canGoForward) this.#report(this.#track(this.#nav.forward()));
454
461
  }
455
462
  listen(listener) {
456
463
  this.#listeners.add(listener);
@@ -459,9 +466,28 @@ var NavigationHistory = class {
459
466
  };
460
467
  }
461
468
  dispose() {
469
+ this.#disposed = true;
470
+ this.#nav.removeEventListener("currententrychange", this.#onCurrentEntryChange);
462
471
  this.#nav.removeEventListener("navigate", this.#onNavigate);
472
+ this.#nav.removeEventListener("navigateerror", this.#onNavigateError);
463
473
  this.#listeners.clear();
464
474
  }
475
+ #track(result) {
476
+ result.finished?.catch(() => {});
477
+ return result.committed?.then(() => void 0) ?? Promise.resolve();
478
+ }
479
+ #fail(error) {
480
+ if (this.#disposed || isAbort(error)) return;
481
+ this.#onError(error);
482
+ }
483
+ async #notify(update) {
484
+ await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
485
+ }
486
+ #report(work) {
487
+ work.catch((error) => {
488
+ this.#fail(error);
489
+ });
490
+ }
465
491
  #navigate(to, history, options) {
466
492
  const url = new URL(to, this.#win.location.href).href;
467
493
  const envelope = {
@@ -469,11 +495,11 @@ var NavigationHistory = class {
469
495
  info: options.info,
470
496
  scroll: options.scroll ?? "auto"
471
497
  };
472
- ignore(this.#nav.navigate(url, {
498
+ this.#report(this.#track(this.#nav.navigate(url, {
473
499
  history,
474
500
  info: envelope,
475
501
  state: options.state ?? null
476
- }));
502
+ })));
477
503
  }
478
504
  #read() {
479
505
  const entry = this.#nav.currentEntry;
@@ -489,6 +515,16 @@ var NavigationHistory = class {
489
515
  state: entry.getState()
490
516
  };
491
517
  }
518
+ #onCurrentEntryChange = (event) => {
519
+ if (event.navigationType !== null) return;
520
+ this.#location = this.#read();
521
+ this.#report(this.#notify({
522
+ action: "update",
523
+ info: void 0,
524
+ location: this.#location,
525
+ scroll: "preserve"
526
+ }));
527
+ };
492
528
  #onNavigate = (event) => {
493
529
  const action = toAction(event.navigationType);
494
530
  if (action === void 0 || !event.canIntercept) return;
@@ -503,16 +539,19 @@ var NavigationHistory = class {
503
539
  scroll: "manual",
504
540
  handler: async () => {
505
541
  this.#location = this.#read();
506
- const update = {
542
+ await this.#notify({
507
543
  action,
508
544
  info,
509
545
  location: this.#location,
510
546
  scroll
511
- };
512
- await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
547
+ });
513
548
  }
514
549
  });
515
550
  };
551
+ #onNavigateError = (event) => {
552
+ const error = event.error;
553
+ this.#fail(error);
554
+ };
516
555
  };
517
556
  const toRelative = (url) => {
518
557
  if (url === null) return null;
@@ -612,18 +651,14 @@ var Builder = class {
612
651
  };
613
652
  //#endregion
614
653
  //#region src/cache.ts
615
- /**
616
- * computes which history entries to keep warm based on active index and recency.
617
- *
618
- * retains the active entry plus backward entries using an LRU policy. forward entries are dropped.
619
- */
620
- const computeCachedKeys = (entries, activeIndex, recency, policy) => {
654
+ /** selects the active entry and recent backward entries for caching. */
655
+ const computeCachedKeys = (entries, activeKey, recency, policy) => {
621
656
  const cached = /* @__PURE__ */ new Set();
622
- const active = entries.find((entry) => entry.index === activeIndex);
623
- if (active === void 0) throw new Error(`stacker: no history entry at active index ${activeIndex}`);
657
+ const active = entries.find((entry) => entry.key === activeKey);
658
+ if (active === void 0) throw new Error(`stacker: no history entry with the active key '${activeKey}'`);
624
659
  cached.add(active.key);
625
660
  const backward = /* @__PURE__ */ new Map();
626
- for (const entry of entries) if (entry.index < activeIndex) backward.set(entry.key, entry);
661
+ for (const entry of entries) if (entry.index < active.index) backward.set(entry.key, entry);
627
662
  let kept = 0;
628
663
  const take = (key) => {
629
664
  if (kept >= policy.max || cached.has(key) || !backward.has(key)) return;
@@ -748,6 +783,10 @@ var Router = class {
748
783
  this.#record(location, TOP);
749
784
  this.#view = this.#recompute();
750
785
  this.#unlisten = this.#history.listen(async ({ action, location: next, scroll }) => {
786
+ if (action === "update") {
787
+ this.#updates.emit();
788
+ return;
789
+ }
751
790
  const win = this.#win;
752
791
  const restoring = scroll === "auto" && win !== null;
753
792
  if (restoring) {
@@ -861,6 +900,8 @@ var Router = class {
861
900
  /**
862
901
  * returns to the nearest existing history entry for a route, or pushes if none exists.
863
902
  *
903
+ * pushes the destination if traversal to a matching entry fails.
904
+ *
864
905
  * @param to route target, or a relative URL resolved against the active location
865
906
  */
866
907
  popTo(to) {
@@ -870,13 +911,17 @@ var Router = class {
870
911
  if (wantedMatch !== void 0) {
871
912
  const wanted = this.#canonical(wantedMatch);
872
913
  const entries = this.#history.entries();
873
- for (let i = this.#history.location.index; i >= 0; i--) {
914
+ const from = this.#history.location.key;
915
+ const start = entries.findIndex((entry) => entry.key === from);
916
+ for (let i = start; i >= 0; i--) {
874
917
  const entry = entries[i];
875
918
  if (entry === void 0 || !entry.sameDocument || entry.url === null) break;
876
919
  const parts = parsePath(entry.url);
877
920
  const match = this.#matcher.match(parts.pathname, parts.search, parts.hash);
878
921
  if (match !== void 0 && match.name === wantedMatch.name && this.#canonical(match) === wanted) {
879
- this.#history.traverseTo(entry.key);
922
+ this.#history.traverseTo(entry.key).catch(() => {
923
+ if (this.#history.location.key === from) this.#history.push(url);
924
+ });
880
925
  return;
881
926
  }
882
927
  }
@@ -917,6 +962,19 @@ var Router = class {
917
962
  state: location.state
918
963
  });
919
964
  }
965
+ /**
966
+ * rewrites the active history entry's state, without navigating.
967
+ *
968
+ * the entry keeps its URL and slot, so the screen stays mounted and the viewport does not move. the whole
969
+ * state is replaced, so build the next value from `router.location.state` to keep the parts you still want.
970
+ * readers of `useLocation` re-render with it.
971
+ *
972
+ * @param state state data to store on the entry
973
+ * @throws when the state cannot be structured-cloned, leaving the entry as it was
974
+ */
975
+ updateState(state) {
976
+ this.#history.updateState(state);
977
+ }
920
978
  /** navigates back one entry. */
921
979
  back() {
922
980
  this.#history.back();
@@ -1009,7 +1067,7 @@ var Router = class {
1009
1067
  const cachedKeys = computeCachedKeys([...this.#entries.values()].map((entry) => ({
1010
1068
  index: entry.index,
1011
1069
  key: entry.key
1012
- })), active.index, this.#recency, { max: this.#max });
1070
+ })), active.key, this.#recency, { max: this.#max });
1013
1071
  const cached = [];
1014
1072
  for (const entry of this.#entries.values()) if (cachedKeys.has(entry.key)) cached.push({
1015
1073
  key: entry.key,
@@ -1,4 +1,4 @@
1
- import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-KOb6CZ7N.mjs";
1
+ import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-kax-GwM6.mjs";
2
2
  //#region src/history/memory.d.ts
3
3
  /** options for the memory history constructor. */
4
4
  interface MemoryHistoryOptions {
@@ -22,7 +22,8 @@ declare class MemoryHistory implements History {
22
22
  entries(): readonly HistoryEntry[];
23
23
  push(to: string, options?: HistoryNavigateOptions): void;
24
24
  replace(to: string, options?: HistoryNavigateOptions): void;
25
- traverseTo(key: string): void;
25
+ updateState(state: unknown): void;
26
+ traverseTo(key: string): Promise<void>;
26
27
  go(delta: number): void;
27
28
  back(): void;
28
29
  forward(): void;
package/dist/testing.mjs CHANGED
@@ -65,10 +65,24 @@ var MemoryHistory = class {
65
65
  scroll: options.scroll ?? "auto"
66
66
  });
67
67
  }
68
+ updateState(state) {
69
+ const location = {
70
+ ...this.#current(),
71
+ state: structuredClone(state)
72
+ };
73
+ this.#entries = this.#entries.with(this.#index, location);
74
+ this.#emit({
75
+ action: "update",
76
+ info: void 0,
77
+ location,
78
+ scroll: "preserve"
79
+ });
80
+ }
68
81
  traverseTo(key) {
69
82
  const index = this.#entries.findIndex((entry) => entry.key === key);
70
- if (index === -1) throw new Error(`stacker: no history entry with key '${key}'`);
83
+ if (index === -1) return Promise.reject(/* @__PURE__ */ new Error(`stacker: no history entry with key '${key}'`));
71
84
  this.go(index - this.#index);
85
+ return Promise.resolve();
72
86
  }
73
87
  go(delta) {
74
88
  const next = Math.max(0, Math.min(this.#index + delta, this.#entries.length - 1));
@@ -108,7 +122,7 @@ var MemoryHistory = class {
108
122
  key,
109
123
  pathname,
110
124
  search,
111
- state
125
+ state: structuredClone(state)
112
126
  };
113
127
  }
114
128
  #current() {
@@ -1,12 +1,13 @@
1
1
  //#region src/history/types.d.ts
2
2
  /**
3
- * the type of navigation that produced a history update.
3
+ * the type of write that produced a history update.
4
4
  *
5
5
  * - `push` — a new entry was added.
6
6
  * - `replace` — the active entry was replaced.
7
7
  * - `traverse` — navigation occurred to an existing entry.
8
+ * - `update` — the active entry's state was rewritten in place, without navigating.
8
9
  */
9
- type HistoryAction = 'push' | 'replace' | 'traverse';
10
+ type HistoryAction = 'push' | 'replace' | 'traverse' | 'update';
10
11
  /** an entry in the browser session history ledger. */
11
12
  interface HistoryEntry {
12
13
  /** unique per-revision identifier. */
@@ -124,8 +125,19 @@ interface History {
124
125
  * navigates to an existing entry by key.
125
126
  *
126
127
  * @param key target entry key
128
+ * @returns promise that resolves on commit and rejects if traversal fails
127
129
  */
128
- traverseTo(key: string): void;
130
+ traverseTo(key: string): Promise<void>;
131
+ /**
132
+ * rewrites the state of the active entry in place, without navigating.
133
+ *
134
+ * the entry keeps its id, key and URL, so no revision is minted and the user's place on the page is left
135
+ * alone. listeners are notified with the `update` action, since the caller is only ever one of them.
136
+ *
137
+ * @param state state data to store on the entry, replacing whatever is there
138
+ * @throws when the state cannot be structured-cloned
139
+ */
140
+ updateState(state: unknown): void;
129
141
  }
130
142
  //#endregion
131
143
  export { HistoryLocation as a, HistoryUpdate as c, HistoryListener as i, HistoryAction as n, HistoryNavigateOptions as o, HistoryEntry as r, HistoryScrollBehavior as s, History as t };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oomfware/stacker",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "type-safe stack router for React",
5
5
  "license": "0BSD",
6
6
  "repository": {