white-label-router 1.1.2 → 5.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 bshack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,361 +1,283 @@
 # white-label-router
 
-A simple ES6 JS router based on the history api and pushstate.
+> Turn URLs into application intent without hiding the web platform.
 
-Learn more about ES6 classes here:
+`white-label-router` is a framework-independent TypeScript router for browser and server applications. It progressively enhances real links with the History API in the browser and dispatches explicit request URLs on the server through the same matching, guard, lifecycle, query, focus, and mediator contracts.
 
-https://babeljs.io/docs/learn-es2015/
+[Documentation](https://whitelabeljs.org/docs/router/) · [API reference](https://whitelabeljs.org/api/#router) · [Demo site](https://whitelabeljs.org/)
 
-## Install
-
-Install the node module:
+**Responsibility:** translate navigation into application intent. Nothing more.
 
-```
-npm install white-label-router --save
-```
+## Why it exists
 
-## Import
+White Label keeps URLs, links, history, and server requests visible rather than replacing them with a proprietary navigation model. Router adds the application boundary around those platform primitives while preserving normal browser behavior whenever enhancement does not apply.
 
-```
-import Router from 'white-label-router';
-```
+Use it independently or compose it with the rest of White Label:
 
+- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) can publish `router:navigate` intent.
+- [`white-label-model`](https://github.com/bshack/white-label-model) can own state changed by a route.
+- [`white-label-view`](https://github.com/bshack/white-label-view) can own the rendering lifecycle started by a route.
+- [`generator-white-label`](https://github.com/bshack/white-label) demonstrates the complete composition.
 
-## Defining Routes
+The package has no runtime dependency on the other White Label packages.
 
-The most simple way simply executes any function you define:
+## Requirements
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-    }
-};
-```
+- Node.js `^22.18.0` or `>=24.11.0` for installation, development, and server execution.
+- npm, Yarn, and pnpm are supported for installation; see [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS.md).
+- Browser History API, location, and standard DOM events only when using browser navigation behavior.
+- A directly requestable server route for every public browser route so enhanced links remain meaningful without JavaScript.
 
-or you can also define initialize and destroy functions in your view which will be automatically called as the user navigates your application:
+## Install
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
-        this.routes = {
-            defaultRoute: {
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the defaultRoute initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
-                    }
-                }
-            },
-            '/page2': {
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the page2 initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the page2 has been destroyed');
-                    }
-                }
-            }
-        };
-    }
-};
+```sh
+npm install white-label-router
+# or: yarn add white-label-router
+# or: pnpm add white-label-router
 ```
 
-You have some additional options when using the view object approach. They include the ability to set the page title for a route and also do security check before a route's view is initialized at the router level:
+The same entrypoint is used in browsers and servers:
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
-        this.routes = {
-            defaultRoute: {
-                title: 'Home',
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the defaultRoute initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the defaultRoute has been destroyed');
-                    }
-                }
-            },
-            '/page2': {
-                title: 'Page 2',
-                view: {
-                    initialize: (scope, locationData) => {
-                        window.console.log('the page2 initialized');
-                    },
-                    destroy: (scope, locationData) => {
-                        window.console.log('the page2 has been destroyed');
-                    }
-                },
-                secure: this.isSecure
-            }
-        };
-    }
-    isSecure (scope, locationData) => {
-        if (someCookieIsValid) {
-            return true;
-        } else {
-            return false;
-        }
-    }
-};
+```js
+import Router from 'white-label-router';
 ```
 
-NOTE: routes are matched by checking if the beginning of the url path name string matches a route. For the example above the route '/page2' would be executed for both path names '/page2' and '/page23/232'.
+## One route contract, two runtimes
 
-## Scope
+### Browser
 
-Optionally you and provide a DOM element to be the scope of the router. That DOM object will then be passed into all your routes as they are executed. If you do not provide a scope then it will be passed in as null into your views. To do so you would like this:
+Omit the URL to dispatch the current browser location and attach browser navigation listeners:
 
+```js
+const router = new Router();
+router.routes = {
+    '/products': (_scope, location) => console.log(location.data.url),
+    defaultRoute: () => true
+};
+
+// initialize() dispatches the current URL and returns the router for chaining.
+router.initialize();
 ```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+### Server
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
+Pass the request URL explicitly. No `window` or `document` is required:
 
-    }
+```js
+const router = new Router();
+router.routes = {
+    '/products': (_scope, location) => console.log(location.data.url),
+    defaultRoute: () => true
 };
+router.initialize('/products/42?color=blue');
 ```
 
-## Instantiate
+Browser-only history, click interception, focus, and document-title effects are skipped on the server. Scope mutable routing state per request when appropriate.
 
-```
-const myRouter = new MyRouter();
+## Serverless and function runtimes
 
-myRouter.initialize();
+Pass the incoming request URL explicitly when Router runs inside a serverless function. The server path uses the same matching, query parsing, guards, and route lifecycle without requiring `window` or `document`.
+
+```js
+const requestUrl = new URL(request.url);
+const router = new Router();
+router.routes = routes;
+router.initialize(`${requestUrl.pathname}${requestUrl.search}`);
 ```
 
-## HTML Linking To Routes
+Create a request-scoped Router when its location state, mediator, route lifecycle, or other mutable configuration belongs to one invocation. Warm function processes may serve sequential or overlapping requests, so sharing one mutable Router can mix location/lifecycle state unless that process-wide lifetime is intentional.
 
-you can make any anchor tigger a specified route by simply setting the href attribute to your route path and adding the attribute 'data-pushstate'.
+Router handles **application routing inside the invocation**. It does not replace API Gateway routes, CDN routing, Vercel/Netlify/Cloudflare route configuration, load balancing, authentication infrastructure, or other cloud request plumbing.
 
-```
-<a href="/page2" data-pushstate>take me to page2</a>
-```
+The package currently documents Node.js as its supported server runtime. Its DOM-free server path uses standard URL APIs, but that is not a blanket compatibility claim for every edge provider; verify the actual target runtime before deployment.
 
-## Navigate
+## Progressive enhancement first
 
-you can also trigger navigation to a route with the navigate method
+Public navigation should remain a real link:
 
-```
-myRouter.navigate('/page2');
+```html
+<a href="/products/42" data-pushstate>View product 42</a>
 ```
 
-## Mediator
+`data-pushstate` opts the link into client-side enhancement. Links without it retain native behavior. Modified clicks, non-left clicks, downloads, alternate targets, and cross-origin URLs also remain native.
 
-Optionally you can use a mediator, such as White Label Mediator, with the router. To do so you would like this:
+This preserves keyboard behavior, context menus, no-JavaScript navigation, and crawler discovery. Public routes should have directly requestable URLs that return meaningful HTML and appropriate title, description, canonical, and robots metadata.
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
+## Define routes
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+A route can be a function:
 
-        this.mediator = myMediator;
+```js
+router.routes = {
+    '/help': (scope, location) => {
+        scope.textContent = `Help page: ${location.url}`;
+    }
+};
+```
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
+Or an object describing route lifecycle:
+
+```js
+router.routes = {
+    '/orders': {
+        title: 'Orders',
+        focus: '#orders-title',
+        secure(scope, location) {
+            // Guards must return exactly true to allow navigation.
+            return Boolean(window.currentUser);
+        },
+        view: {
+            initialize(scope, location) {
+                scope.textContent = 'Order history';
             },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
+            destroy(scope, nextLocation) {
+                scope.replaceChildren();
             }
-        };
-
+        }
     }
 };
 ```
 
-Then anywhere else in the application you want to trigger the router to navigate you could do so like this:
-
-```
-myMediator.emit('router:navigate', {
-    url: '/authentication',
-    message: 'Session expired, please login again.'
-});
-```
+`secure()` must return exactly `true` to allow navigation. On a successful route change, the previous route's `destroy()` runs before the next route's `initialize()`.
 
-## Scope
+## Matching
 
-Optionally you and provide a DOM element to be the scope of the router. That DOM object will then be passed into all your routes as they are executed. To do so you would like this:
+Routes match complete path boundaries. `/products` matches `/products` and `/products/42`, but not `/products-old`.
 
-```
-const MyRoute = class extends Router {
-    constructor() {
-        super();
+When multiple route prefixes match, Router selects the **longest matching route**, so specific routes win without depending on object insertion order:
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
-
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-
-    }
+```js
+router.routes = {
+    '/products': productsRoute,
+    '/products/sale': saleRoute,
+    defaultRoute
 };
 ```
 
-## Passing Data
+`/products/sale` selects `saleRoute` even though `/products` was defined first. When no prefix matches, `defaultRoute` runs if configured.
 
-The router passes in a location data object to the route that is being executed. Here is an example object passed:
+## Location contract
 
-```
+Routes receive the configured `scope` and a location object:
+
+```js
 {
-    url: ['/user'],
+    url: '/products/42?color=blue',
     data: {
-        url: [],
-        mediator: {},
-        query: {}
+        url: ['42'],
+        mediator: {source: 'featured-products'},
+        query: {color: 'blue'}
     }
 }
 ```
 
-'data.url' is an array of values parsed from the url being requested. For Example if the url was '/user/fred' and we defined a route for '/user' then data object passed into the '/user' route would be the following:
+`data.url` contains path segments after the matched prefix, `data.query` contains parsed query values, and `data.mediator` contains navigation data supplied programmatically or through the mediator. Values are URI-decoded with standard WHATWG URL APIs; applications must still validate untrusted values.
 
-```
-{
-    url: ['/user/fred'],
-    data: {
-        url: ['fred'],
-        mediator: {},
-        query: {}
-    }
-}
-```
+## Programmatic navigation
 
-'data.query' is an object of values parsed from the url query string. For Example if the url was '/user?name=fred' and we defined a route for '/user' then data object passed into the '/user' route would be the following:
+```js
+const result = router.navigate('/products/42', {
+    source: 'featured-products'
+});
 
-```
-{
-    url: ['/user?name=fred'],
-    data: {
-        url: [],
-        mediator: {},
-        query: {
-            name: 'fred'
-        }
-    }
-}
+// `result` is the router on success or false when navigation is rejected.
 ```
 
-'data.mediator' is an object of values parsed through the optional mediator. For Example if this was emitted through the mediator:
+In browsers, successful navigation updates history unless the call represents `popstate`. On servers it dispatches without History API effects.
 
-```
-myMediator.emit('router:navigate', {
-    url: '/authentication',
-    message: 'Session expired, please login again.'
-});
-```
+Calling `navigate()` without a URL dispatches the current browser URL. In a non-browser runtime the safe default is `/`; server applications should normally supply the request URL explicitly.
 
-Then the location data passed in to the '/authentication' route would be the following:
+## Mediator integration
 
-```
-{
-    url: ['/authentication'],
-    data: {
-        url: [],
-        mediator: {
-            url: '/authentication',
-            message: 'Session expired, please login again.'
-        }
-    }
-}
-```
+Assign any EventEmitter-compatible mediator that provides `on()` and `removeListener()`:
 
-## Let's look at an example:
+```js
+import Mediator from 'white-label-mediator';
 
-import the module
+const mediator = new Mediator();
+const router = new Router();
 
+router.mediator = mediator;
+router.initialize();
+
+mediator.emit('router:navigate', {
+    url: '/account',
+    reason: 'Session refreshed'
+});
 ```
-import Router from 'white-label-router';
+
+The complete event object becomes `location.data.mediator`. `destroy()` removes listeners owned by Router. Repeated listener initialization is idempotent.
+
+## Public API
+
+| Member | Behavior | Returns |
+| --- | --- | --- |
+| `routes` | Ordered route table of functions or lifecycle route objects. | Configuration property; not a method. |
+| `scope` | Application scope passed to route callbacks. | Configuration property; not a method. |
+| `mediator` | Optional EventEmitter-compatible source for `router:navigate`. | Configuration property; not a method. |
+| `initialize(url?)` | Dispatch the browser URL or an explicit server URL and attach applicable listeners. | The same `Router` instance. |
+| `navigate(url?, data?, isPopState?)` | Match and run a route; update browser history when appropriate. | The same `Router` instance on success; `false` for cross-origin browser URLs, rejected guards, or routes without runnable view behavior. |
+| `addListeners()` | Attach browser and optional mediator listeners once. | The same `Router` instance. |
+| `removeListeners()` | Release listeners owned by this router. | The same `Router` instance. |
+| `destroy()` | Release routing listeners. | The same `Router` instance after cleanup. |
+| `parseQueryString(query)` | Decode a query string using `URLSearchParams`. | A plain object containing the last value for each query key. |
+| `setLocationData(data?)` | Rebuild the current route location payload. | `undefined`; updates `locationData` in place. |
+| `applyPageContext(route)` | Update route title/focus context when applicable. | The same `Router` instance. |
+| `eventPushStateClick(event)` | Handle an eligible browser push-state click. | The same `Router` instance after handled navigation; `true` when native/default handling should continue. |
+| `eventPopState()` | Dispatch the current browser history location. | The same `Router` instance. |
+
+## Title and focus
+
+Object routes can define browser title and focus behavior:
+
+```js
+router.routes = {
+    '/account': {
+        title: 'Account',
+        focus: '#account-title',
+        view: renderAccount
+    }
+};
 ```
 
-extend the router
+The default focus selector is `main h1`. Set `focus: false` for an in-page refinement that should preserve current focus. Server runtimes retain `pageTitle` as route state but do not mutate a document or focus target.
 
-```
-const myRouter = class extends Router {
-    // this is the constructor. This executed whenever the view is instantiated.
-    constructor() {
+## Browser history behavior
 
-        super();
+Initialization dispatches the current URL without adding a duplicate history entry. Back/forward navigation reads `window.location`—including path, query, and hash—even when history state is null or belongs to another application. History state is not treated as the authoritative URL.
 
-        // the container element where all views will be placed
-        this.scope = document.querySelector('body');
+## TypeScript
 
-        this.routes = {
-            defaultRoute: (scope, locationData) => {
-                //here you would put any view specific logic for the defaultRoute
-                window.console.log('the defaultRoute executed');
-            },
-            '/page2': (scope, locationData) => {
-                //here you would put any view specific logic for the page2 route
-                window.console.log('the page2 route executed');
-            }
-        };
-        
-    }
+Implementation uses strict TypeScript and emits JavaScript, source maps, and declarations into `dist`.
+
+```ts
+const router = new Router();
+const greeting: Router.Route = (scope, location) => {
+    console.log(location.data.query.name);
 };
 
+router.routes['/hello'] = greeting;
+router.initialize();
 ```
 
-instantiate your router
+`Router.Route`, `Router.Location`, `Router.Navigation`, and `Router.Handler` expose the supported contracts. Browser DOM types are present because the same class supports browser scopes and events; server hosts do not need DOM globals at runtime.
 
-```
-const myRouter = new MyRoute();
-```
-
-initialize your router
+## Development
 
-```
-myRouter.initialize();
+```sh
+npm ci --ignore-scripts
+npm run lint
+npm run typecheck
+npm test
+npm run coverage
+npm run audit
+npm pack --dry-run
 ```
 
-navigate to '/page2'
+Tests cover browser behavior, DOM-free server routing, and parity of the shared route contract. Coverage enforces 100% statements, branches, functions, and lines per implementation file. CI builds authored source, uploads generated artifacts for inspection, audits dependencies, packs the package, and verifies the packed public API across npm, Yarn, and pnpm.
 
-```
-myRouter.navigate('/page2');
-```
+Edit `src/*.ts` and regenerate `dist`; do not edit generated files directly.
 
-In the example above we have set up two routes. The first route 'defaultRoute' is a catch all route. If no other routes match the specified url path this is the route that will be executed. In this example the defaultRoute would be executed for 'http://example.com' or 'http://example.com/home', but not 'http://example.com/page2'.
+## Design boundary
 
-The second defined route 'page2' will only be executed when the specified url path starts with '/page2', or for example 'http://example.com/page2'.
+Router owns URL-to-intent translation. It intentionally does not own application state, rendering, data loading, authentication policy, or server infrastructure. Real links and server URLs remain the foundation; Router enhances them instead of replacing them.

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/** Navigation payload, including caller-defined metadata. */
+interface NavigationData {
+    url?: string;
+    [key: string]: unknown;
+}
+/** URL-derived values supplied to route handlers. */
+interface LocationData {
+    url: string;
+    data: {
+        url: string[];
+        mediator: NavigationData | undefined;
+        query: Record<string, string>;
+    };
+}
+type RouteHandler = (scope: Element | null, location: LocationData) => unknown;
+/** An object route can own a function or a view lifecycle. */
+interface RouteObject {
+    title?: string;
+    focus?: string | false;
+    secure?: RouteHandler;
+    view?: RouteHandler | {
+        initialize?: RouteHandler;
+        destroy?: RouteHandler;
+    };
+}
+type Route = RouteHandler | RouteObject;
+/** Minimal event-bus contract required by the router. */
+interface NavigationMediator {
+    on(event: string, callback: (data?: NavigationData) => unknown): unknown;
+    removeListener(event: string, callback: (data?: NavigationData) => unknown): unknown;
+}
+/** History API router that also dispatches request URLs in non-browser runtimes. */
+declare class Router {
+    routes: Record<string, Route>;
+    url: string;
+    route: string | null;
+    scope: Element | null;
+    previousRoute: string | null;
+    pageTitle: string | null;
+    mediator: NavigationMediator | false;
+    boundPushStateClick: (event: MouseEvent) => unknown;
+    boundPopState: (event: PopStateEvent) => unknown;
+    boundMediatorNavigate: (data?: NavigationData) => unknown;
+    listenersInitialized: boolean;
+    locationData: LocationData;
+    /** Create an instance with its own state and listener references. */
+    constructor();
+    /** True when browser navigation APIs are available. */
+    private isBrowserRuntime;
+    /** Stable base URL for WHATWG URL parsing in browser and server runtimes. */
+    private getOrigin;
+    /** Read the authoritative browser URL, or retain the supplied server URL. */
+    private getCurrentUrl;
+    /** Normalize browser navigation to a same-origin path, query, and hash. */
+    private normalizeBrowserUrl;
+    /**
+     * Start this instance and return it for lifecycle chaining.
+     * In a browser the URL is optional and defaults to window.location. On a server pass the request URL.
+     */
+    initialize(url?: string): this;
+    /** Register browser and optional mediator handlers once. */
+    addListeners(): this;
+    /** Release owned state and listeners so the instance can leave the application lifecycle. */
+    destroy(): this;
+    /** Release listeners owned by this instance; subclasses may extend the lifecycle hook. */
+    removeListeners(): this;
+    /** Intercept eligible same-origin push-state links while preserving normal browser actions. */
+    eventPushStateClick(e: MouseEvent): true | this;
+    /** Restore browser history state without adding a new history entry. */
+    eventPopState(): this;
+    /** Decode URL query parameters, keeping the last value for duplicate keys. */
+    parseQueryString(queryString: string): {
+        [k: string]: string;
+    };
+    /** Build decoded path, query, and mediator data for the selected route. */
+    setLocationData(mediatorData?: NavigationData): void;
+    /** Update page context after a route renders. DOM effects are browser-only. */
+    applyPageContext(route: Route): this;
+    /** Select a route, enforce its guard, transition view lifecycles, and update browser history when available. */
+    navigate(url?: string, mediatorData?: NavigationData, isPopState?: boolean): false | this;
+}
+/** Public route configuration and navigation payload types. */
+declare namespace Router {
+    type Handler = RouteHandler;
+    type Route = RouteHandler | RouteObject;
+    type Location = LocationData;
+    type Navigation = NavigationData;
+}
+export = Router;