@valancex/router 0.12.0 → 0.13.1

package/README.md

@@ -26,4 +26,5 @@ await Web.run(app, { container, primitives, present: "mount", plugins: [router.p
 - `router.commands(state)` gives `navigate`, `go` and `replace` commands for the application's state.
 - Guards: `canMatch` (sync), `canActivate`, `canDeactivate`, and `beforeEach`; each answers a boolean, a `redirect(...)`, or a Promise/Effect of one. A refused Back/Forward is undone.
 - Redirects name a route, never a URL; `router.safeNext(address)` only accepts an address on the application.
-- Not yet: nested routes, a `beforeunload` guard, typed HTTP interceptors.
+- `History`: the list of places visited and its moves (`History.start`, `push`, `replace`, `go`, `canGo`, `restore`), pure and serializable. A target with no history of its own (a window) keeps one in its state; `restore` drops entries that are no longer routes and starts again at the first when none is left. Guards are told why a move is made, including `"history"` for Back and Forward along such a list. `permit` runs a guard; one that throws or fails refuses. See `docs/application-model/NAVIGATION.md`.
+- Not yet: nested routes, a `beforeunload` guard, a mobile adapter.

package/dist/history.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The list of places an application has been, and the position in it: the model every target's navigation is made of (docs/application-model/NAVIGATION.md). It is plain data and pure
+ * functions, so a target that owns its list (a window has none of its own) keeps it in the application's state, and one that does not (the web's session history, a phone's back stack)
+ * can still describe, validate and restore what it has with the same rules.
+ *
+ * An entry is whatever names a place as plain data: a page's address, or a `RouteState`.
+ */
+export interface History<E> {
+    readonly entries: ReadonlyArray<E>;
+    /** The position of the current entry. */
+    readonly index: number;
+}
+/** A list that has only been to `entry`. */
+export declare const start: <E>(entry: E) => History<E>;
+/** The current entry. */
+export declare const current: <E>(history: History<E>) => E;
+/** Goes to `entry`: it comes after the current one, and whatever was ahead is dropped (as the web's `pushState` does). */
+export declare const push: <E>(history: History<E>, entry: E) => History<E>;
+/** Changes the current entry; nothing is added. */
+export declare const replace: <E>(history: History<E>, entry: E) => History<E>;
+/** Whether `distance` (-1 is back, +1 is forward) lands on an entry. A platform with no forward never offers a positive one. */
+export declare const canGo: <E>(history: History<E>, distance: number) => boolean;
+/** Moves along the list by `distance`. A move that would leave it changes nothing. */
+export declare const go: <E>(history: History<E>, distance: number) => History<E>;
+/**
+ * A list read back from somewhere (a store, the platform's restoration) is data from an earlier run, and the application may have changed since. Entries `valid` refuses are dropped; the
+ * position stays on the entry that was current, or the nearest one before it that is left (else the first); a list with nothing left starts again at `fallback`. Anything that is not a list
+ * of the right shape is `fallback` too, so a bad store is never a crash.
+ */
+export declare const restore: <E>(saved: unknown, valid: (entry: unknown) => entry is E, fallback: E) => History<E>;

package/dist/history.js

@@ -0,0 +1,37 @@
+/** A list that has only been to `entry`. */
+export const start = (entry) => ({ entries: [entry], index: 0 });
+/** The current entry. */
+export const current = (history) => history.entries[history.index];
+/** Goes to `entry`: it comes after the current one, and whatever was ahead is dropped (as the web's `pushState` does). */
+export const push = (history, entry) => ({ entries: [...history.entries.slice(0, history.index + 1), entry], index: history.index + 1 });
+/** Changes the current entry; nothing is added. */
+export const replace = (history, entry) => ({
+    entries: history.entries.map((each, at) => (at === history.index ? entry : each)),
+    index: history.index,
+});
+/** Whether `distance` (-1 is back, +1 is forward) lands on an entry. A platform with no forward never offers a positive one. */
+export const canGo = (history, distance) => Number.isInteger(distance) && history.index + distance >= 0 && history.index + distance < history.entries.length;
+/** Moves along the list by `distance`. A move that would leave it changes nothing. */
+export const go = (history, distance) => (canGo(history, distance) ? { entries: history.entries, index: history.index + distance } : history);
+/**
+ * A list read back from somewhere (a store, the platform's restoration) is data from an earlier run, and the application may have changed since. Entries `valid` refuses are dropped; the
+ * position stays on the entry that was current, or the nearest one before it that is left (else the first); a list with nothing left starts again at `fallback`. Anything that is not a list
+ * of the right shape is `fallback` too, so a bad store is never a crash.
+ */
+export const restore = (saved, valid, fallback) => {
+    const shape = saved;
+    if (typeof shape !== "object" || shape === null || !Array.isArray(shape.entries) || typeof shape.index !== "number" || !Number.isInteger(shape.index)) {
+        return start(fallback);
+    }
+    const kept = [];
+    let position = -1;
+    shape.entries.forEach((entry, at) => {
+        if (valid(entry)) {
+            kept.push(entry);
+            if (at <= shape.index) {
+                position = kept.length - 1;
+            }
+        }
+    });
+    return kept.length === 0 ? start(fallback) : { entries: kept, index: Math.max(0, position) };
+};

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { createRouter } from "./router.js";
 export type { Router, RouterOptions } from "./router.js";
 export { route } from "./route.js";
 export type { Route, RouteConfig } from "./route.js";
-export { redirect } from "./guards.js";
+export { redirect, runGuard as permit } from "./guards.js";
+export * as History from "./history.js";
 export { RouteDefinitionError } from "./pattern.js";
 export { RouteState } from "./types.js";
 export type { Decision, Guard, GuardContext, GuardResult, NavigationKind, Redirect, TitleContext } from "./types.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createRouter } from "./router.js";
 export { route } from "./route.js";
-export { redirect } from "./guards.js";
+export { redirect, runGuard as permit } from "./guards.js";
+export * as History from "./history.js";
 export { RouteDefinitionError } from "./pattern.js";
 export { RouteState } from "./types.js";

package/dist/router.d.ts

@@ -35,6 +35,11 @@ export declare const createRouter: <S extends Record<string, any>, C = undefined
             readonly to: string;
         }, void, never, never>;
     };
+    moveTo: (state: Nexus.State.StateHandle<S>, to: string, options?: {
+        readonly replace?: boolean;
+    }) => Effect.Effect<boolean>;
+    mayLeave: (state: S) => Effect.Effect<boolean>;
+    enter: (address: string, state: S) => Effect.Effect<RouteState>;
     match: (address: string) => RouteState;
     href: <P, Q>(to: Route<P, Q, S, C> | string, params?: P | Readonly<Record<string, unknown>>, query?: Q | Readonly<Record<string, unknown>>) => string;
     hrefOf: (state: RouteState) => string;

package/dist/router.js

@@ -367,7 +367,7 @@ export const createRouter = (options) => {
      * - `go` and `replace`: programmatic navigation to an address, `go({ to: "/inbox/42?tab=unread" })`; `replace` rewrites the current history entry instead of adding one. Each decides first (the guard
      *   for leaving, then the one for entering), then sets the state; a refusal leaves it where it is. They take one argument so a template can call them: `on.click={go("/inbox")}`.
      */
-    const moveTo = (state, to, replace) => Effect.gen(function* () {
+    const goTo = (state, to, replace) => Effect.gen(function* () {
         const target = resolve(to);
         if (target === undefined) {
             yield* Effect.logWarning("the address is not on this application");
@@ -381,10 +381,46 @@ export const createRouter = (options) => {
         const next = decision._tag === "Redirect" ? { ...decision.to, replace: true } : { ...decision.to, ...(replace ? { replace: true } : {}) };
         yield* state.update((latest) => Effect.succeed({ ...latest, [key]: next }));
     });
+    /**
+     * The route an application starts on, for an address it was opened at (a deep link, a saved session, the address the server rendered): the address's route after the entering guards have had their
+     * say. `match` alone does not ask them, so a link to a list that no longer exists would start the application on a screen with nothing to show. A redirect is followed; a refusal starts on the
+     * not-found route. Nothing is being left, so no `canDeactivate` runs. Give it the state the application will start with (guards read it).
+     */
+    const enter = (address, state) => Effect.gen(function* () {
+        const target = resolve(address) ?? notFoundState(new URL("/", FALLBACK_ORIGIN));
+        const decision = yield* decide({ from: undefined, to: target, state, kind: "initial" });
+        return decision._tag === "Refuse" ? notFoundState(new URL(address.startsWith("/") ? address : "/", FALLBACK_ORIGIN)) : strip(decision.to);
+    });
+    /**
+     * Goes to an address from inside a command: the same decision `go` makes (the guard for leaving, then the one for entering; a redirect is followed, a refusal leaves the application where it is),
+     * as an Effect a command can run after or before its own changes. It answers whether the application moved. A command that saves and then leaves should save first: the leaving guard sees
+     * the state as it is when this runs.
+     */
+    const moveTo = (state, to, options = {}) => Effect.gen(function* () {
+        const before = yield* state.get;
+        yield* goTo(state, to, options.replace === true);
+        const after = yield* state.get;
+        const was = routeOf(before);
+        const now = routeOf(after);
+        return was === undefined || now === undefined ? was !== now : !sameDestination(was, now);
+    });
+    /**
+     * May the application be left altogether (its window closing, its process ending)? Asks the current route's `canDeactivate` as a navigation of kind `"close"` whose destination is the route
+     * it is already on, since there is none. `true` when there is nothing to ask. This is what a target's close request should consult: a native window with unsaved edits is the same case as a
+     * page with a `beforeunload`.
+     */
+    const mayLeave = (state) => Effect.gen(function* () {
+        const current = routeOf(state);
+        const leaving = current === undefined ? undefined : routeNamed(current.name);
+        if (current === undefined || leaving?.config.canDeactivate === undefined) {
+            return true;
+        }
+        return (yield* runGuard(leaving.config.canDeactivate, { from: current, to: current, state, kind: "close", data: leaving.config.data ?? {} })) === true;
+    });
     const commands = (state) => ({
         navigate: Nexus.Command.define("navigate", RouteState, (next) => state.update((current) => Effect.succeed({ ...current, [key]: strip(next) })).pipe(Effect.asVoid)),
-        go: Nexus.Command.define("go", Destination, ({ to }) => moveTo(state, to, false)),
-        replace: Nexus.Command.define("replace", Destination, ({ to }) => moveTo(state, to, true)),
+        go: Nexus.Command.define("go", Destination, ({ to }) => goTo(state, to, false)),
+        replace: Nexus.Command.define("replace", Destination, ({ to }) => goTo(state, to, true)),
     });
-    return { base, key, notFoundName, table, plugin, commands, match: stateFor, href, hrefOf, resolve, safeNext, decide, titleOf, route: routeNamed, paths };
+    return { base, key, notFoundName, table, plugin, commands, moveTo, mayLeave, enter, match: stateFor, href, hrefOf, resolve, safeNext, decide, titleOf, route: routeNamed, paths };
 };

package/dist/types.d.ts

@@ -12,8 +12,11 @@ export interface RouteState {
     readonly replace?: boolean;
 }
 export declare const RouteState: Schema.Schema<RouteState>;
-/** Where a navigation came from. */
-export type NavigationKind = "link" | "popstate" | "programmatic";
+/**
+ * Where a navigation came from. `popstate`: the browser moved through its history on its own. `history`: the application moves along a list it keeps itself (Back and Forward on a target that
+ * has no browser). `close`: the window or page is going away.
+ */
+export type NavigationKind = "link" | "popstate" | "programmatic" | "history" | "initial" | "close";
 /** What a guard is told. `state` is the application's state now, before the navigation. */
 export interface GuardContext<S> {
     /** The route being left; `undefined` for the first navigation. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/router",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Routing for VALANCE applications: route definitions with typed path and query parameters, matching conditions, guards for entering and leaving a route, programmatic navigation, and a title per route. Plugs into Web.run as the URL policy.",
   "keywords": [
     "valance",
@@ -39,11 +39,17 @@
     "access": "public",
     "provenance": true
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "prepack": "tsc -p tsconfig.json"
+  },
   "dependencies": {
     "@valancex/nexus": "^0.12.0"
   },
   "peerDependencies": {
-    "@valancex/valance": "^0.12.0",
+    "@valancex/valance": "^0.13.0",
     "effect": "^3.10.0"
   },
   "devDependencies": {
@@ -51,16 +57,11 @@
     "@types/node": "^22.0.0",
     "@valancex/mesh-compiler": "^0.11.0",
     "@valancex/mesh-runtime": "^0.11.0",
-    "@valancex/port-web": "^0.4.0",
+    "@valancex/port-web": "^0.6.1",
+    "@valancex/valance": "workspace:^",
     "effect": "^3.10.0",
     "jsdom": "^26.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.2.0",
-    "@valancex/valance": "^0.12.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.typecheck.json",
-    "test": "vitest run"
+    "vitest": "^3.2.0"
   }
-}
+}