@dharmax/state-router 3.1.2 → 3.2.1

package/dist/state-manager.js

@@ -8,13 +8,22 @@ export class StateManager {
     stateContext;
     static dispatcher = dispatcher;
     changeAuthorities = [];
-    constructor(mode = 'hash', autostart = true) {
+    router;
+    beforeChangeHandlers = [];
+    afterChangeHandlers = [];
+    constructor(mode = 'hash', autostart = true, routerInstance = router) {
         this.mode = mode;
+        this.router = routerInstance;
         if (autostart)
-            router.listen(mode);
+            this.router.listen(mode);
     }
     start() {
-        router.listen(this.mode);
+        this.router.listen(this.mode);
+    }
+    stop() {
+        // unlisten router to cleanup event listeners
+        // @ts-ignore - older Router versions may not have unlisten
+        this.router.unlisten && this.router.unlisten();
     }
     onChange(handler) {
         return StateManager.dispatcher.on('state:changed', handler);
@@ -50,9 +59,9 @@ export class StateManager {
     }
     /** attempts to restore state from current url. Currently, works only in hash mode */
     restoreState(defaultState) {
-        if (router.navigate(window.location.pathname))
+        if (this.router.navigate(window.location.pathname))
             return;
-        router.navigate(defaultState);
+        this.router.navigate(defaultState);
     }
     /**
      *
@@ -67,13 +76,18 @@ export class StateManager {
         }
         // check if the state change was declined by any change authority and if so - don't do it and return false
         const changeConfirmations = await Promise.all(this.changeAuthorities.map(authority => authority(newState)));
-        if (changeConfirmations.includes(false))
+        const vetoes = await Promise.all(this.beforeChangeHandlers.map(h => Promise.resolve(h(newState, context))));
+        if (changeConfirmations.includes(false) || vetoes.includes(false))
             return false;
         // perform the change
         this.previousState = this.appState;
         this.stateContext = context;
         this.appState = newState;
         dispatcher.trigger('state-manager', 'state', 'changed', this.appState);
+        // afterChange hooks
+        for (const cb of this.afterChangeHandlers) {
+            await cb(this.appState, context, this.previousState);
+        }
         return true;
     }
     /**
@@ -86,8 +100,9 @@ export class StateManager {
     addState(name, pageName, route, mode) {
         pageName = pageName || name;
         route = route || pageName;
-        if (typeof route === "string") {
-            let newRoute = route.split('%').join('?(.*)');
+        if (typeof route === 'string' && route.includes('%')) {
+            // keep colon-based string patterns intact for Router to compile named params
+            const newRoute = route.split('%').join('?(.*)');
             route = new RegExp(`^${newRoute}$`);
         }
         this.registerStateByState({
@@ -99,8 +114,13 @@ export class StateManager {
     }
     registerStateByState(state) {
         this.allStates[state.name] = state;
-        router.add(state.route, async (context) => {
-            if (await this.setState(state.name, context)) {
+        const self = this;
+        this.router.add(state.route, async function (...captures) {
+            // prefer named params (from router string patterns), else multi-captures array, else first capture
+            // @ts-ignore
+            const named = (this && this.params) || null;
+            const context = named && Object.keys(named).length ? named : (captures.length <= 1 ? captures[0] : captures);
+            if (await self.setState(state.name, context)) {
                 // @ts-ignore
                 window.pageChangeHandler && window.pageChangeHandler('send', 'pageview', `/${state.name}/${context || ''}`);
                 // @ts-ignore
@@ -108,4 +128,18 @@ export class StateManager {
             }
         });
     }
+    onBeforeChange(handler) {
+        this.beforeChangeHandlers.push(handler);
+    }
+    onAfterChange(handler) {
+        this.afterChangeHandlers.push(handler);
+    }
+    onNotFound(handler) {
+        // proxy to router-level notFound
+        // @ts-ignore - older Router versions may not have onNotFound
+        this.router.onNotFound && this.router.onNotFound(handler);
+    }
+}
+export function createStateManager(mode = 'hash', autostart = true, routerInstance = router) {
+    return new StateManager(mode, autostart, routerInstance);
 }

package/dist-cjs/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./router"), exports);
+__exportStar(require("./state-manager"), exports);

package/dist-cjs/router.cjs

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.router = exports.Router = void 0;
+exports.createRouter = createRouter;
+class Router {
+    mode = 'hash';
+    routes = [];
+    root = '/';
+    rootCompare = '';
+    baseLocation = null;
+    staticFilters = [];
+    isListening = false;
+    bound = {};
+    notFoundHandler;
+    decodeParams = false;
+    constructor() {
+        this.staticFilters.push(url => {
+            const staticFileExtensions = ['.json', '.css', '.js', '.png', '.jpg', '.svg', '.webp', '.md', '.ejs', '.jsm', '.txt'];
+            return staticFileExtensions.some(ext => url.endsWith(ext));
+        });
+    }
+    cleanPathString(path) {
+        path = path.replace(/\/$/, '').replace(/^\//, '');
+        return path = path.replace(/#{2,}/g, '#');
+    }
+    clearQuery(url) {
+        const [path, query] = url.split('?');
+        if (!query)
+            return path;
+        const [_, hash] = query.split('#');
+        return hash ? `${path}#${hash}` : path;
+    }
+    isStaticFile(url) {
+        return (this.staticFilters || []).some(filter => filter(url));
+    }
+    resetRoot(root) {
+        const cleaned = this.cleanPathString(root);
+        this.root = '/' + cleaned + '/';
+        this.rootCompare = cleaned ? cleaned + '/' : '';
+    }
+    getLocation() {
+        if (!this.isBrowser())
+            return '';
+        if (this.mode === 'history') {
+            let fragment = decodeURI(window.location.pathname + window.location.search);
+            fragment = this.clearQuery(fragment);
+            // strip leading slash for comparison convenience
+            fragment = fragment.replace(/^\//, '');
+            if (this.root !== '/' && this.rootCompare && fragment.startsWith(this.rootCompare)) {
+                fragment = fragment.slice(this.rootCompare.length);
+            }
+            fragment = this.cleanPathString(fragment);
+            return fragment;
+        }
+        else {
+            const match = window.location.href.match(/#(.*)$/);
+            return match ? this.clearQuery(match[1]) : '';
+        }
+    }
+    add(pattern, handler) {
+        let paramNames;
+        if (typeof pattern === 'function') {
+            handler = pattern;
+            pattern = /^.*$/; // Match any path
+        }
+        else if (typeof pattern === 'string') {
+            const compiled = this.compilePattern(pattern);
+            pattern = compiled.regex;
+            paramNames = compiled.paramNames;
+        }
+        this.routes.push({ pattern: pattern, handler: handler, paramNames });
+        return this;
+    }
+    onNotFound(handler) {
+        this.notFoundHandler = handler;
+        return this;
+    }
+    setDecodeParams(decode) {
+        this.decodeParams = decode;
+        return this;
+    }
+    getQueryParams(search) {
+        if (!this.isBrowser() && !search)
+            return {};
+        const qs = typeof search === 'string' ? search : window.location.search || '';
+        const usp = new URLSearchParams(qs);
+        const obj = {};
+        usp.forEach((v, k) => { obj[k] = v; });
+        return obj;
+    }
+    isBrowser() {
+        return typeof window !== 'undefined' && typeof document !== 'undefined';
+    }
+    compilePattern(pattern) {
+        // normalize leading slash to align with cleanPathString behavior
+        const normalized = pattern.replace(/^\//, '');
+        const paramNames = [];
+        // convert /users/:id -> ^users/([^/]+)$
+        const reStr = normalized
+            .replace(/([.*+?^${}()|[\]\\])/g, '\\$1') // escape regex specials
+            .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_m, p1) => {
+            paramNames.push(p1);
+            return '([^/]+)';
+        });
+        return { regex: new RegExp(`^${reStr}$`), paramNames };
+    }
+    /**
+     *
+     * @param location
+     * @return true if it was intercepted or false if not handled
+     */
+    handleChange(location) {
+        const path = (location ?? this.getLocation()) || '';
+        if (this.isStaticFile(path))
+            return false; // Bypass routing for static files
+        for (const route of this.routes) {
+            const match = route.pattern ? path.match(route.pattern) : null;
+            if (match) {
+                match.shift(); // Remove the full match element
+                const queryParams = this.getQueryParams();
+                const captures = this.decodeParams ? match.map(v => safeDecode(v)) : match;
+                let params;
+                if (route.paramNames && route.paramNames.length) {
+                    params = {};
+                    route.paramNames.forEach((n, i) => params[n] = captures[i]);
+                }
+                route.handler.call({ queryParams, params }, ...captures);
+                return true;
+            }
+        }
+        if (this.notFoundHandler) {
+            this.notFoundHandler(path);
+            return true;
+        }
+        if (path)
+            console.warn(`No routing found for ${path}`);
+        return false;
+    }
+    listen(mode = 'hash') {
+        if (!this.isBrowser())
+            return;
+        // avoid duplicate listeners
+        if (this.isListening)
+            this.unlisten();
+        const self = this;
+        this.mode = mode;
+        const handler = (path) => {
+            const p = path || location.href.split('#')[0];
+            if (self.isStaticFile(p))
+                return;
+            const currentLocation = self.getLocation();
+            if (self.baseLocation !== currentLocation) {
+                self.baseLocation = currentLocation;
+                self.handleChange(currentLocation);
+            }
+        };
+        const handleInternalNavigation = (event) => {
+            // modified clicks or non-left clicks
+            const me = event;
+            if (event.type === 'click') {
+                if (me.button !== 0)
+                    return; // left-click only
+                if (me.metaKey || me.ctrlKey || me.shiftKey)
+                    return;
+            }
+            const target = event.target;
+            if (!target || !('closest' in target))
+                return;
+            const anchor = target.closest?.('a');
+            if (!anchor)
+                return;
+            if (event.type === 'keydown') {
+                const ke = event;
+                if (ke.key !== 'Enter')
+                    return;
+            }
+            const href = anchor.getAttribute('href') || '';
+            if (!href)
+                return;
+            const url = new URL(href, window.location.href);
+            // ignore external origins or different hostnames
+            if (url.origin !== window.location.origin)
+                return;
+            // ignore target=_blank, download, or rel=noreferrer
+            const t = anchor.getAttribute('target');
+            if (t && t.toLowerCase() === '_blank')
+                return;
+            if (anchor.hasAttribute('download'))
+                return;
+            const rel = anchor.getAttribute('rel');
+            if (rel && /\bnoreferrer\b/i.test(rel))
+                return;
+            const pathWithQuery = url.pathname + (url.search || '');
+            if (self.isStaticFile(pathWithQuery) || self.isStaticFile(url.pathname))
+                return;
+            event.preventDefault();
+            history.pushState({ path: pathWithQuery }, '', pathWithQuery);
+            handler(pathWithQuery);
+        };
+        switch (mode) {
+            case 'hash':
+                this.bound.hashchange = () => handler();
+                window.addEventListener('hashchange', this.bound.hashchange);
+                break;
+            case 'history':
+                this.bound.popstate = (event) => handler(event.state?.path);
+                this.bound.click = handleInternalNavigation;
+                this.bound.keydown = (event) => handleInternalNavigation(event);
+                window.addEventListener('popstate', this.bound.popstate);
+                document.addEventListener('click', this.bound.click);
+                document.addEventListener('keydown', this.bound.keydown);
+                break;
+        }
+        this.isListening = true;
+        handler();
+    }
+    unlisten() {
+        if (!this.isBrowser() || !this.isListening)
+            return;
+        switch (this.mode) {
+            case 'hash':
+                if (this.bound.hashchange)
+                    window.removeEventListener('hashchange', this.bound.hashchange);
+                break;
+            case 'history':
+                if (this.bound.popstate)
+                    window.removeEventListener('popstate', this.bound.popstate);
+                if (this.bound.click)
+                    document.removeEventListener('click', this.bound.click);
+                if (this.bound.keydown)
+                    document.removeEventListener('keydown', this.bound.keydown);
+                break;
+        }
+        this.bound = {};
+        this.isListening = false;
+    }
+    navigate(path = '', opts) {
+        if (!this.isBrowser())
+            return false;
+        if (this.mode === 'history') {
+            const url = this.root + this.cleanPathString(path);
+            if (opts?.replace)
+                history.replaceState(null, '', url);
+            else
+                history.pushState(null, '', url);
+        }
+        else
+            window.location.hash = this.cleanPathString(path);
+        return this.handleChange();
+    }
+    replace(path = '') {
+        return this.navigate(path, { replace: true });
+    }
+}
+exports.Router = Router;
+exports.router = new Router();
+function createRouter() { return new Router(); }
+function safeDecode(v) {
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v;
+    }
+}

package/dist-cjs/router.d.ts

@@ -0,0 +1,41 @@
+type RouteHandler = (...args: string[]) => void;
+export type RoutingMode = 'history' | 'hash';
+export declare class Router {
+    private mode;
+    private routes;
+    private root;
+    private rootCompare;
+    private baseLocation;
+    staticFilters: ((url: string) => boolean)[];
+    private isListening;
+    private bound;
+    private notFoundHandler?;
+    private decodeParams;
+    constructor();
+    private cleanPathString;
+    private clearQuery;
+    private isStaticFile;
+    resetRoot(root: string): void;
+    getLocation(): string;
+    add(pattern: RegExp | string | RouteHandler, handler?: RouteHandler): Router;
+    onNotFound(handler: (path: string) => void): Router;
+    setDecodeParams(decode: boolean): Router;
+    getQueryParams(search?: string): Record<string, string>;
+    private isBrowser;
+    private compilePattern;
+    /**
+     *
+     * @param location
+     * @return true if it was intercepted or false if not handled
+     */
+    handleChange(location?: string): boolean;
+    listen(mode?: RoutingMode): void;
+    unlisten(): void;
+    navigate(path?: string, opts?: {
+        replace?: boolean;
+    }): boolean;
+    replace(path?: string): boolean;
+}
+export declare const router: Router;
+export declare function createRouter(): Router;
+export {};

package/dist-cjs/state-manager.cjs

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateManager = void 0;
+exports.createStateManager = createStateManager;
+const router_1 = require("./router");
+const pubsub_1 = require("@dharmax/pubsub");
+class StateManager {
+    mode;
+    allStates = {};
+    appState;
+    previousState;
+    stateContext;
+    static dispatcher = pubsub_1.default;
+    changeAuthorities = [];
+    router;
+    beforeChangeHandlers = [];
+    afterChangeHandlers = [];
+    constructor(mode = 'hash', autostart = true, routerInstance = router_1.router) {
+        this.mode = mode;
+        this.router = routerInstance;
+        if (autostart)
+            this.router.listen(mode);
+    }
+    start() {
+        this.router.listen(this.mode);
+    }
+    stop() {
+        // unlisten router to cleanup event listeners
+        // @ts-ignore - older Router versions may not have unlisten
+        this.router.unlisten && this.router.unlisten();
+    }
+    onChange(handler) {
+        return StateManager.dispatcher.on('state:changed', handler);
+    }
+    /*
+    Add a hook which enable conditional approval of state change. It can be more than one; when a state
+    change is requested, all the registered authorities must return true (asynchronously) otherwise the change
+    requested doesn't happen.
+    **/
+    registerChangeAuthority(authorityCallback) {
+        this.changeAuthorities.push(authorityCallback);
+    }
+    getState() {
+        return this.appState || {};
+    }
+    get previous() {
+        return this.previousState;
+    }
+    get context() {
+        return this.stateContext;
+    }
+    /**
+     * set current page state
+     * @param state can be either just a state or a state and context (which can be sub-state, or anything else)
+     */
+    set state(state) {
+        if (Array.isArray(state)) {
+            const sName = state.shift();
+            this.setState(sName, state);
+        }
+        else
+            this.setState(state);
+    }
+    /** attempts to restore state from current url. Currently, works only in hash mode */
+    restoreState(defaultState) {
+        if (this.router.navigate(window.location.pathname))
+            return;
+        this.router.navigate(defaultState);
+    }
+    /**
+     *
+     * @param stateName state
+     * @param context extra context (e.g. sub-state)
+     */
+    async setState(stateName, context) {
+        const newState = this.allStates[stateName];
+        if (!newState) {
+            alert(`Undefined app state ${stateName}`);
+            return false;
+        }
+        // check if the state change was declined by any change authority and if so - don't do it and return false
+        const changeConfirmations = await Promise.all(this.changeAuthorities.map(authority => authority(newState)));
+        const vetoes = await Promise.all(this.beforeChangeHandlers.map(h => Promise.resolve(h(newState, context))));
+        if (changeConfirmations.includes(false) || vetoes.includes(false))
+            return false;
+        // perform the change
+        this.previousState = this.appState;
+        this.stateContext = context;
+        this.appState = newState;
+        pubsub_1.default.trigger('state-manager', 'state', 'changed', this.appState);
+        // afterChange hooks
+        for (const cb of this.afterChangeHandlers) {
+            await cb(this.appState, context, this.previousState);
+        }
+        return true;
+    }
+    /**
+     * Define an application state
+     * @param name
+     * @param pageName by default it equals the name (you can null it)
+     * @param route by default it equals the pageName (ditto)
+     * @param mode optional
+     */
+    addState(name, pageName, route, mode) {
+        pageName = pageName || name;
+        route = route || pageName;
+        if (typeof route === 'string' && route.includes('%')) {
+            // keep colon-based string patterns intact for Router to compile named params
+            const newRoute = route.split('%').join('?(.*)');
+            route = new RegExp(`^${newRoute}$`);
+        }
+        this.registerStateByState({
+            name,
+            pageName,
+            route,
+            mode
+        });
+    }
+    registerStateByState(state) {
+        this.allStates[state.name] = state;
+        const self = this;
+        this.router.add(state.route, async function (...captures) {
+            // prefer named params (from router string patterns), else multi-captures array, else first capture
+            // @ts-ignore
+            const named = (this && this.params) || null;
+            const context = named && Object.keys(named).length ? named : (captures.length <= 1 ? captures[0] : captures);
+            if (await self.setState(state.name, context)) {
+                // @ts-ignore
+                window.pageChangeHandler && window.pageChangeHandler('send', 'pageview', `/${state.name}/${context || ''}`);
+                // @ts-ignore
+                window.ga && window.ga('send', 'pageview', `/${state.name}/${context || ''}`);
+            }
+        });
+    }
+    onBeforeChange(handler) {
+        this.beforeChangeHandlers.push(handler);
+    }
+    onAfterChange(handler) {
+        this.afterChangeHandlers.push(handler);
+    }
+    onNotFound(handler) {
+        // proxy to router-level notFound
+        // @ts-ignore - older Router versions may not have onNotFound
+        this.router.onNotFound && this.router.onNotFound(handler);
+    }
+}
+exports.StateManager = StateManager;
+function createStateManager(mode = 'hash', autostart = true, routerInstance = router_1.router) {
+    return new StateManager(mode, autostart, routerInstance);
+}

package/dist-cjs/state-manager.d.ts

@@ -0,0 +1,56 @@
+import { RoutingMode, Router as RouterType } from "./router";
+import { IPubSubHandle, PubSubEvent } from "@dharmax/pubsub";
+export type ApplicationStateName = string;
+export type ApplicationState = {
+    name: ApplicationStateName;
+    pageName: string;
+    route: RegExp | string;
+    mode?: string | string[];
+};
+export type ChangeAuthority = (state: ApplicationState) => Promise<boolean>;
+export declare class StateManager {
+    private mode;
+    private allStates;
+    private appState;
+    private previousState;
+    private stateContext;
+    static dispatcher: import("@dharmax/pubsub").PubSub;
+    private changeAuthorities;
+    private router;
+    private beforeChangeHandlers;
+    private afterChangeHandlers;
+    constructor(mode?: RoutingMode, autostart?: boolean, routerInstance?: RouterType);
+    start(): void;
+    stop(): void;
+    onChange(handler: (event: PubSubEvent, data: any) => void): IPubSubHandle;
+    registerChangeAuthority(authorityCallback: (targetState: ApplicationState) => Promise<boolean>): void;
+    getState(): ApplicationState;
+    get previous(): ApplicationState;
+    get context(): any;
+    /**
+     * set current page state
+     * @param state can be either just a state or a state and context (which can be sub-state, or anything else)
+     */
+    set state(state: ApplicationStateName | [ApplicationStateName, ...any]);
+    /** attempts to restore state from current url. Currently, works only in hash mode */
+    restoreState(defaultState: ApplicationStateName): void;
+    /**
+     *
+     * @param stateName state
+     * @param context extra context (e.g. sub-state)
+     */
+    setState(stateName: ApplicationStateName, context?: any): Promise<boolean>;
+    /**
+     * Define an application state
+     * @param name
+     * @param pageName by default it equals the name (you can null it)
+     * @param route by default it equals the pageName (ditto)
+     * @param mode optional
+     */
+    addState(name: string, pageName?: string, route?: RegExp | string, mode?: string | string[]): void;
+    registerStateByState(state: ApplicationState): void;
+    onBeforeChange(handler: (target: ApplicationState, context?: any) => boolean | Promise<boolean>): void;
+    onAfterChange(handler: (state: ApplicationState, context?: any, previous?: ApplicationState) => void | Promise<void>): void;
+    onNotFound(handler: (path: string) => void): void;
+}
+export declare function createStateManager(mode?: RoutingMode, autostart?: boolean, routerInstance?: RouterType): StateManager;

package/package.json

@@ -1,14 +1,27 @@
 {
   "name": "@dharmax/state-router",
-  "version": "3.1.2",
+  "version": "3.2.1",
   "description": "A cute and tight router and application state controller",
-  "main": "dist/index.js",
+  "type": "module",
+  "main": "dist-cjs/index.cjs",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist-cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
 
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "npx tsc",
-    "prepublish": "npm run build"
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "npx tsc",
+    "build:cjs": "npx tsc -p tsconfig.cjs.json && node scripts/rename-cjs.mjs",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -23,9 +36,18 @@
   "bugs": {
     "url": "https://github.com/dharmax/state-router/issues"
   },
-  "homepage": "https://github.com/dharmax/state-routerr",
+  "homepage": "https://github.com/dharmax/state-router",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "dist-cjs",
+    "ReadMe.md"
+  ],
   "devDependencies": {
-    "typescript": "^4.9.5"
+    "typescript": "^5.9.2",
+    "vitest": "^2.0.5",
+    "jsdom": "^24.1.0",
+    "@vitest/coverage-v8": "^2.0.5"
   },
   "dependencies": {
     "@dharmax/pubsub": "^1.1.0"