@oomfware/stacker 0.2.0 → 0.2.1

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
@@ -206,6 +206,16 @@ const label = (target: RouteTarget<typeof routes>): string => {
206
206
  because a target spells its params alongside `name`, a route cannot declare a param called `name`;
207
207
  `defineRoutes` rejects it.
208
208
 
209
+ wrap route components in stacker's `lazy` to allow the router to preload them ahead of time.
210
+
211
+ ```tsx
212
+ const Profile = lazy(() => import('./screens/profile.tsx'));
213
+
214
+ <Link onPointerEnter={() => void router.preload('Profile')} to="/profile/alice">
215
+ alice
216
+ </Link>;
217
+ ```
218
+
209
219
  ### hooks
210
220
 
211
221
  generate type-safe hooks bound to your route configuration using `createRouterHooks`:
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
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";
2
- import { AnchorHTMLAttributes, ComponentType, EffectCallback, ReactElement, ReactNode } from "react";
2
+ import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
3
3
  //#region src/codec.d.ts
4
4
  /**
5
5
  * a bidirectional codec for a single route parameter.
@@ -199,11 +199,11 @@ declare const route: <const Params extends CodecRecord = Empty, const Query exte
199
199
  declare const layout: <const Children extends RouteChildren, const Params extends CodecRecord = Empty>(config: LayoutConfig<Children, Params>) => LayoutNode<Children, Params>;
200
200
  /** a node resolved with an id and normalized parameters. */
201
201
  interface ResolvedNode {
202
+ readonly kind: 'layout' | 'route';
202
203
  /** unique dot-separated node path. */
203
204
  readonly id: string;
204
205
  /** key name within the parent record. */
205
206
  readonly key: string;
206
- readonly kind: 'layout' | 'route';
207
207
  readonly node: RouteNode;
208
208
  /** local parameter codecs. */
209
209
  readonly params: CodecRecord;
@@ -285,9 +285,9 @@ type QueryPatchOf<R, K extends RouteName<R>> = LeafQueryPatch<LeavesMap<R>[K]>;
285
285
  //#region src/match.d.ts
286
286
  /** a node on a matched chain paired with its instance parameters. */
287
287
  interface MatchedNode {
288
+ readonly node: ResolvedNode;
288
289
  /** parameters used for instance keying. */
289
290
  readonly params: Readonly<Record<string, unknown>>;
290
- readonly node: ResolvedNode;
291
291
  }
292
292
  /** the result of matching a URL, containing the chain, leaf, name, and parameters. */
293
293
  interface RouteMatch {
@@ -364,6 +364,26 @@ interface View {
364
364
  readonly roots: readonly InstanceNode[];
365
365
  }
366
366
  //#endregion
367
+ //#region src/lazy.d.ts
368
+ /** a preloadable lazily-loaded component. */
369
+ type LazyComponent<T extends ComponentType<any>> = LazyExoticComponent<T> & {
370
+ /**
371
+ * start loading the component code.
372
+ *
373
+ * @returns promise that settles once loading finishes
374
+ */
375
+ preload(): Promise<void>;
376
+ };
377
+ /**
378
+ * defines a lazily-loaded component that can be preloaded.
379
+ *
380
+ * @param init component module loader
381
+ * @returns lazy component
382
+ */
383
+ declare const lazy: <T extends ComponentType<any>>(init: () => Promise<{
384
+ default: T;
385
+ }>) => LazyComponent<T>;
386
+ //#endregion
367
387
  //#region src/router.d.ts
368
388
  /** options for a navigation. */
369
389
  interface NavigateOptions<R extends RouteRegistry<unknown>> extends HistoryNavigateOptions {
@@ -446,6 +466,14 @@ declare class Router<R extends RouteRegistry<unknown>> {
446
466
  * @param options where to go, and how to get there
447
467
  */
448
468
  navigate(options: NavigateOptions<R>): void;
469
+ /**
470
+ * loads the code a route needs, without navigating to it.
471
+ *
472
+ * @param name route name
473
+ * @returns promise that settles once loading finishes
474
+ * @throws when `name` is not in the registry
475
+ */
476
+ preload(name: RouteName<R>): Promise<void>;
449
477
  /**
450
478
  * returns to the nearest existing history entry for a route, or pushes if none exists.
451
479
  *
@@ -592,4 +620,4 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'
592
620
  */
593
621
  declare const Link: ({ children, onClick, replace, to, ...rest }: LinkProps) => ReactElement;
594
622
  //#endregion
595
- export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryScrollBehavior, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LeafType, Link, type LinkProps, type MatchedNode, type MatchedTarget, type NavigateOptions, NavigationHistory, type NavigationHistoryOptions, type OptionalCodec, Outlet, type ParamsOf, type QueryPatchOf, type ReadonlyURLSearchParams, type ResolvedLeaf, type ResolvedNode, type RouteChildren, type RouteConfig, type RouteLeaf, type RouteMatch, type RouteMeta, type RouteName, type RouteNode, type RouteRegistry, type RouteTarget, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
623
+ export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryScrollBehavior, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LazyComponent, type LeafType, Link, type LinkProps, type MatchedNode, type MatchedTarget, type NavigateOptions, NavigationHistory, type NavigationHistoryOptions, type OptionalCodec, Outlet, type ParamsOf, type QueryPatchOf, type ReadonlyURLSearchParams, type ResolvedLeaf, type ResolvedNode, type RouteChildren, type RouteConfig, type RouteLeaf, type RouteMatch, type RouteMeta, type RouteName, type RouteNode, type RouteRegistry, type RouteTarget, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
package/dist/index.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { a as parsePath, i as encodeSegment, n as decodeRemainder, o as resolvePath, r as encodeRemainder, t as createPath } from "./url-DerpiRjh.mjs";
2
+ import { Suspense, createContext, lazy as lazy$1, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
2
3
  import { SimpleEventEmitter } from "@mary-ext/simple-event-emitter";
3
- import { Suspense, createContext, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
4
4
  import { Fragment, jsx, jsxs } from "react/jsx-runtime";
5
5
  //#region src/codec.ts
6
6
  const OPTIONAL = Symbol("stacker.optional");
@@ -81,9 +81,9 @@ const nonEmpty = () => ({
81
81
  * @returns the optional codec
82
82
  */
83
83
  const optional = (codec) => ({
84
+ [OPTIONAL]: true,
84
85
  decode: (raw) => codec.decode(raw),
85
- encode: (value) => codec.encode(value),
86
- [OPTIONAL]: true
86
+ encode: (value) => codec.encode(value)
87
87
  });
88
88
  /**
89
89
  * wraps a codec with a default value.
@@ -93,9 +93,9 @@ const optional = (codec) => ({
93
93
  * @returns the defaulted codec
94
94
  */
95
95
  const withDefault = (codec, fallback) => ({
96
+ [DEFAULT]: fallback,
96
97
  decode: (raw) => codec.decode(raw),
97
- encode: (value) => codec.encode(value),
98
- [DEFAULT]: fallback
98
+ encode: (value) => codec.encode(value)
99
99
  });
100
100
  const isOptional = (codec) => {
101
101
  return OPTIONAL in codec;
@@ -182,9 +182,9 @@ const defineRoutes = (tree) => {
182
182
  if (ids.has(id)) throw new Error(`stacker: duplicate node id '${id}'`);
183
183
  const params = node.params ?? {};
184
184
  const resolved = {
185
+ kind: node.kind,
185
186
  id,
186
187
  key,
187
- kind: node.kind,
188
188
  node,
189
189
  params,
190
190
  path: node.kind === "route" ? node.path : void 0
@@ -520,6 +520,45 @@ const toRelative = (url) => {
520
520
  return `${pathname}${search}${hash}`;
521
521
  };
522
522
  //#endregion
523
+ //#region src/lazy.ts
524
+ const noop = () => {};
525
+ /**
526
+ * defines a lazily-loaded component that can be preloaded.
527
+ *
528
+ * @param init component module loader
529
+ * @returns lazy component
530
+ */
531
+ const lazy = (init) => {
532
+ const component = lazy$1(init);
533
+ return Object.assign(component, { preload() {
534
+ try {
535
+ const internals = component;
536
+ internals._init(internals._payload);
537
+ } catch {}
538
+ return Promise.try(init).then(noop, noop);
539
+ } });
540
+ };
541
+ const isPreloadable = (component) => {
542
+ return typeof component.preload === "function";
543
+ };
544
+ /**
545
+ * loads every preloadable component in a list.
546
+ *
547
+ * @param components components to load
548
+ * @returns promise that settles once loading finishes
549
+ */
550
+ const preloadAll = (chain) => {
551
+ const pending = [];
552
+ for (const node of chain) {
553
+ const component = node.node.component;
554
+ if (!isPreloadable(component)) continue;
555
+ try {
556
+ pending.push(component.preload().then(noop, noop));
557
+ } catch {}
558
+ }
559
+ return Promise.all(pending).then(noop);
560
+ };
561
+ //#endregion
523
562
  //#region src/build.ts
524
563
  const SEGMENT = /:([A-Za-z_]\w*)/g;
525
564
  var Builder = class {
@@ -808,6 +847,18 @@ var Router = class {
808
847
  else this.#history.push(url, rest);
809
848
  }
810
849
  /**
850
+ * loads the code a route needs, without navigating to it.
851
+ *
852
+ * @param name route name
853
+ * @returns promise that settles once loading finishes
854
+ * @throws when `name` is not in the registry
855
+ */
856
+ preload(name) {
857
+ const leaf = this.#routes.leaves.get(name);
858
+ if (leaf === void 0) throw new Error(`stacker: unknown route '${name}'`);
859
+ return preloadAll(leaf.chain);
860
+ }
861
+ /**
811
862
  * returns to the nearest existing history entry for a route, or pushes if none exists.
812
863
  *
813
864
  * @param to route target, or a relative URL resolved against the active location
@@ -940,6 +991,7 @@ var Router = class {
940
991
  }
941
992
  #record(location, scrollPos) {
942
993
  const match = this.#match(location);
994
+ preloadAll(match.leaf.chain);
943
995
  const entry = {
944
996
  index: location.index,
945
997
  key: location.key,
@@ -999,17 +1051,17 @@ const toTarget = (match) => ({
999
1051
  });
1000
1052
  const makeNotFound = (component) => {
1001
1053
  const leafNode = {
1002
- component,
1003
1054
  kind: "route",
1055
+ component,
1004
1056
  params: {},
1005
1057
  path: "*",
1006
1058
  query: {},
1007
1059
  type: "page"
1008
1060
  };
1009
1061
  const node = {
1062
+ kind: "route",
1010
1063
  id: " notFound",
1011
1064
  key: " notFound",
1012
- kind: "route",
1013
1065
  node: leafNode,
1014
1066
  params: {},
1015
1067
  path: "*"
@@ -1244,4 +1296,4 @@ const Link = ({ children, onClick, replace, to, ...rest }) => {
1244
1296
  });
1245
1297
  };
1246
1298
  //#endregion
1247
- export { Link, NavigationHistory, Outlet, Router, RouterView, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
1299
+ export { Link, NavigationHistory, Outlet, Router, RouterView, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oomfware/stacker",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "type-safe stack router for React",
5
5
  "license": "0BSD",
6
6
  "repository": {