@oomfware/stacker 0.2.1 → 0.2.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 CHANGED
@@ -325,6 +325,16 @@ new NavigationHistory({
325
325
  });
326
326
  ```
327
327
 
328
+ ### failed navigations
329
+
330
+ `NavigationHistory` sends navigation and render errors to `onError`. it defaults to `reportError`:
331
+
332
+ ```ts
333
+ new NavigationHistory({
334
+ onError: (error) => captureException(error),
335
+ });
336
+ ```
337
+
328
338
  ### metadata
329
339
 
330
340
  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-Bo4ESWAT.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,7 @@ 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
+ traverseTo(key: string): Promise<void>;
344
350
  go(delta: number): void;
345
351
  back(): void;
346
352
  forward(): void;
@@ -477,6 +483,8 @@ declare class Router<R extends RouteRegistry<unknown>> {
477
483
  /**
478
484
  * returns to the nearest existing history entry for a route, or pushes if none exists.
479
485
  *
486
+ * pushes the destination if traversal to a matching entry fails.
487
+ *
480
488
  * @param to route target, or a relative URL resolved against the active location
481
489
  */
482
490
  popTo(to: RouteTarget<R> | string): void;
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,23 @@ 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();
412
414
  this.#nav.addEventListener("navigate", this.#onNavigate);
415
+ this.#nav.addEventListener("navigateerror", this.#onNavigateError);
413
416
  this.#win.history.scrollRestoration = "manual";
414
417
  }
415
418
  get location() {
@@ -438,19 +441,19 @@ var NavigationHistory = class {
438
441
  this.#navigate(to, "replace", options);
439
442
  }
440
443
  traverseTo(key) {
441
- ignore(this.#nav.traverseTo(key));
444
+ return this.#track(this.#nav.traverseTo(key));
442
445
  }
443
446
  go(delta) {
444
447
  const entries = this.#nav.entries();
445
448
  const target = entries[Math.max(0, Math.min(this.#location.index + delta, entries.length - 1))];
446
449
  if (target === void 0 || target.key === this.#location.key) return;
447
- this.traverseTo(target.key);
450
+ this.#report(this.traverseTo(target.key));
448
451
  }
449
452
  back() {
450
- if (this.#nav.canGoBack) ignore(this.#nav.back());
453
+ if (this.#nav.canGoBack) this.#report(this.#track(this.#nav.back()));
451
454
  }
452
455
  forward() {
453
- if (this.#nav.canGoForward) ignore(this.#nav.forward());
456
+ if (this.#nav.canGoForward) this.#report(this.#track(this.#nav.forward()));
454
457
  }
455
458
  listen(listener) {
456
459
  this.#listeners.add(listener);
@@ -459,9 +462,24 @@ var NavigationHistory = class {
459
462
  };
460
463
  }
461
464
  dispose() {
465
+ this.#disposed = true;
462
466
  this.#nav.removeEventListener("navigate", this.#onNavigate);
467
+ this.#nav.removeEventListener("navigateerror", this.#onNavigateError);
463
468
  this.#listeners.clear();
464
469
  }
470
+ #track(result) {
471
+ result.finished?.catch(() => {});
472
+ return result.committed?.then(() => void 0) ?? Promise.resolve();
473
+ }
474
+ #fail(error) {
475
+ if (this.#disposed || isAbort(error)) return;
476
+ this.#onError(error);
477
+ }
478
+ #report(committed) {
479
+ committed.catch((error) => {
480
+ this.#fail(error);
481
+ });
482
+ }
465
483
  #navigate(to, history, options) {
466
484
  const url = new URL(to, this.#win.location.href).href;
467
485
  const envelope = {
@@ -469,11 +487,11 @@ var NavigationHistory = class {
469
487
  info: options.info,
470
488
  scroll: options.scroll ?? "auto"
471
489
  };
472
- ignore(this.#nav.navigate(url, {
490
+ this.#report(this.#track(this.#nav.navigate(url, {
473
491
  history,
474
492
  info: envelope,
475
493
  state: options.state ?? null
476
- }));
494
+ })));
477
495
  }
478
496
  #read() {
479
497
  const entry = this.#nav.currentEntry;
@@ -513,6 +531,10 @@ var NavigationHistory = class {
513
531
  }
514
532
  });
515
533
  };
534
+ #onNavigateError = (event) => {
535
+ const error = event.error;
536
+ this.#fail(error);
537
+ };
516
538
  };
517
539
  const toRelative = (url) => {
518
540
  if (url === null) return null;
@@ -612,18 +634,14 @@ var Builder = class {
612
634
  };
613
635
  //#endregion
614
636
  //#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) => {
637
+ /** selects the active entry and recent backward entries for caching. */
638
+ const computeCachedKeys = (entries, activeKey, recency, policy) => {
621
639
  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}`);
640
+ const active = entries.find((entry) => entry.key === activeKey);
641
+ if (active === void 0) throw new Error(`stacker: no history entry with the active key '${activeKey}'`);
624
642
  cached.add(active.key);
625
643
  const backward = /* @__PURE__ */ new Map();
626
- for (const entry of entries) if (entry.index < activeIndex) backward.set(entry.key, entry);
644
+ for (const entry of entries) if (entry.index < active.index) backward.set(entry.key, entry);
627
645
  let kept = 0;
628
646
  const take = (key) => {
629
647
  if (kept >= policy.max || cached.has(key) || !backward.has(key)) return;
@@ -861,6 +879,8 @@ var Router = class {
861
879
  /**
862
880
  * returns to the nearest existing history entry for a route, or pushes if none exists.
863
881
  *
882
+ * pushes the destination if traversal to a matching entry fails.
883
+ *
864
884
  * @param to route target, or a relative URL resolved against the active location
865
885
  */
866
886
  popTo(to) {
@@ -870,13 +890,17 @@ var Router = class {
870
890
  if (wantedMatch !== void 0) {
871
891
  const wanted = this.#canonical(wantedMatch);
872
892
  const entries = this.#history.entries();
873
- for (let i = this.#history.location.index; i >= 0; i--) {
893
+ const from = this.#history.location.key;
894
+ const start = entries.findIndex((entry) => entry.key === from);
895
+ for (let i = start; i >= 0; i--) {
874
896
  const entry = entries[i];
875
897
  if (entry === void 0 || !entry.sameDocument || entry.url === null) break;
876
898
  const parts = parsePath(entry.url);
877
899
  const match = this.#matcher.match(parts.pathname, parts.search, parts.hash);
878
900
  if (match !== void 0 && match.name === wantedMatch.name && this.#canonical(match) === wanted) {
879
- this.#history.traverseTo(entry.key);
901
+ this.#history.traverseTo(entry.key).catch(() => {
902
+ if (this.#history.location.key === from) this.#history.push(url);
903
+ });
880
904
  return;
881
905
  }
882
906
  }
@@ -1009,7 +1033,7 @@ var Router = class {
1009
1033
  const cachedKeys = computeCachedKeys([...this.#entries.values()].map((entry) => ({
1010
1034
  index: entry.index,
1011
1035
  key: entry.key
1012
- })), active.index, this.#recency, { max: this.#max });
1036
+ })), active.key, this.#recency, { max: this.#max });
1013
1037
  const cached = [];
1014
1038
  for (const entry of this.#entries.values()) if (cachedKeys.has(entry.key)) cached.push({
1015
1039
  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-Bo4ESWAT.mjs";
2
2
  //#region src/history/memory.d.ts
3
3
  /** options for the memory history constructor. */
4
4
  interface MemoryHistoryOptions {
@@ -22,7 +22,7 @@ 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
+ traverseTo(key: string): Promise<void>;
26
26
  go(delta: number): void;
27
27
  back(): void;
28
28
  forward(): void;
package/dist/testing.mjs CHANGED
@@ -67,8 +67,9 @@ var MemoryHistory = class {
67
67
  }
68
68
  traverseTo(key) {
69
69
  const index = this.#entries.findIndex((entry) => entry.key === key);
70
- if (index === -1) throw new Error(`stacker: no history entry with key '${key}'`);
70
+ if (index === -1) return Promise.reject(/* @__PURE__ */ new Error(`stacker: no history entry with key '${key}'`));
71
71
  this.go(index - this.#index);
72
+ return Promise.resolve();
72
73
  }
73
74
  go(delta) {
74
75
  const next = Math.max(0, Math.min(this.#index + delta, this.#entries.length - 1));
@@ -124,8 +124,9 @@ interface History {
124
124
  * navigates to an existing entry by key.
125
125
  *
126
126
  * @param key target entry key
127
+ * @returns promise that resolves on commit and rejects if traversal fails
127
128
  */
128
- traverseTo(key: string): void;
129
+ traverseTo(key: string): Promise<void>;
129
130
  }
130
131
  //#endregion
131
132
  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.2",
4
4
  "description": "type-safe stack router for React",
5
5
  "license": "0BSD",
6
6
  "repository": {