@dharmax/state-router 3.2.0 → 4.0.1

package/dist/state-manager.js

@@ -2,19 +2,30 @@ import { router } from "./router";
 import dispatcher from "@dharmax/pubsub";
 export class StateManager {
     mode;
-    allStates = {};
-    appState;
-    previousState;
-    stateContext;
+    #allStates = {};
+    #appState = null;
+    #previousState = null;
+    #stateContext;
+    #currentTransitionId = 0;
     static dispatcher = dispatcher;
-    changeAuthorities = [];
-    constructor(mode = 'hash', autostart = true) {
+    #changeAuthorities = [];
+    #router;
+    #beforeChangeHandlers = [];
+    #afterChangeHandlers = [];
+    constructor(mode = 'hash', autostart = true, routerInstance = router) {
         this.mode = mode;
+        this.#router = routerInstance;
+        this.#router.setMode(mode);
         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);
@@ -25,16 +36,16 @@ export class StateManager {
     requested doesn't happen.
     **/
     registerChangeAuthority(authorityCallback) {
-        this.changeAuthorities.push(authorityCallback);
+        this.#changeAuthorities.push(authorityCallback);
     }
     getState() {
-        return this.appState || {};
+        return this.#appState || {};
     }
     get previous() {
-        return this.previousState;
+        return this.#previousState;
     }
     get context() {
-        return this.stateContext;
+        return this.#stateContext;
     }
     /**
      * set current page state
@@ -43,16 +54,21 @@ export class StateManager {
     set state(state) {
         if (Array.isArray(state)) {
             const sName = state.shift();
-            this.setState(sName, state);
+            this.setState(sName, state.length === 1 ? state[0] : state);
         }
         else
             this.setState(state);
     }
-    /** attempts to restore state from current url. Currently, works only in hash mode */
+    /** attempts to restore state from current url. */
     restoreState(defaultState) {
-        if (router.navigate(window.location.pathname))
+        if (this.#router.handleChange())
             return;
-        router.navigate(defaultState);
+        const state = this.#allStates[defaultState];
+        let path = defaultState;
+        if (state && typeof state.route === 'string') {
+            path = state.route;
+        }
+        this.#router.navigate(path);
     }
     /**
      *
@@ -60,20 +76,34 @@ export class StateManager {
      * @param context extra context (e.g. sub-state)
      */
     async setState(stateName, context) {
-        const newState = this.allStates[stateName];
+        const transitionId = ++this.#currentTransitionId;
+        const newState = this.#allStates[stateName];
         if (!newState) {
-            alert(`Undefined app state ${stateName}`);
-            return false;
+            throw new Error(`Undefined app state ${stateName}`);
         }
         // 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 changeConfirmations = await Promise.all(this.#changeAuthorities.map(authority => authority(newState)));
+        if (transitionId !== this.#currentTransitionId)
+            return false;
+        const vetoes = await Promise.all(this.#beforeChangeHandlers.map(h => Promise.resolve(h(newState, context))));
+        if (transitionId !== this.#currentTransitionId)
             return false;
+        if (changeConfirmations.includes(false) || vetoes.includes(false))
+            return false;
+        if (this.#appState && this.#appState.onExit) {
+            await this.#appState.onExit(this.#stateContext);
+            if (transitionId !== this.#currentTransitionId)
+                return false;
+        }
         // perform the change
-        this.previousState = this.appState;
-        this.stateContext = context;
-        this.appState = newState;
-        dispatcher.trigger('state-manager', 'state', 'changed', this.appState);
+        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 +116,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({
@@ -98,9 +129,14 @@ export class StateManager {
         });
     }
     registerStateByState(state) {
-        this.allStates[state.name] = state;
-        router.add(state.route, async (context) => {
-            if (await this.setState(state.name, context)) {
+        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
@@ -108,4 +144,24 @@ export class StateManager {
             }
         });
     }
+    onBeforeChange(handler) {
+        this.#beforeChangeHandlers.push(handler);
+    }
+    onAfterChange(handler) {
+        this.#afterChangeHandlers.push(handler);
+    }
+    onExit(stateName, handler) {
+        const state = this.#allStates[stateName];
+        if (state) {
+            state.onExit = 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,268 @@
+"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 + '/' : '';
+    }
+    setMode(mode) {
+        this.#mode = mode;
+    }
+    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)
+                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(this.getLocation());
+                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,29 @@
+type RouteHandler = (...args: string[]) => void;
+export type RoutingMode = 'history' | 'hash';
+export declare class Router {
+    #private;
+    staticFilters: ((url: string) => boolean)[];
+    constructor();
+    resetRoot(root: string): void;
+    setMode(mode: RoutingMode): 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>;
+    /**
+     *
+     * @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,172 @@
+"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 = null;
+    #previousState = null;
+    #stateContext;
+    #currentTransitionId = 0;
+    static dispatcher = pubsub_1.default;
+    #changeAuthorities = [];
+    #router;
+    #beforeChangeHandlers = [];
+    #afterChangeHandlers = [];
+    constructor(mode = 'hash', autostart = true, routerInstance = router_1.router) {
+        this.mode = mode;
+        this.#router = routerInstance;
+        this.#router.setMode(mode);
+        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.length === 1 ? state[0] : state);
+        }
+        else
+            this.setState(state);
+    }
+    /** attempts to restore state from current url. */
+    restoreState(defaultState) {
+        if (this.#router.handleChange())
+            return;
+        const state = this.#allStates[defaultState];
+        let path = defaultState;
+        if (state && typeof state.route === 'string') {
+            path = state.route;
+        }
+        this.#router.navigate(path);
+    }
+    /**
+     *
+     * @param stateName state
+     * @param context extra context (e.g. sub-state)
+     */
+    async setState(stateName, context) {
+        const transitionId = ++this.#currentTransitionId;
+        const newState = this.#allStates[stateName];
+        if (!newState) {
+            throw new Error(`Undefined app state ${stateName}`);
+        }
+        // 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 (transitionId !== this.#currentTransitionId)
+            return false;
+        const vetoes = await Promise.all(this.#beforeChangeHandlers.map(h => Promise.resolve(h(newState, context))));
+        if (transitionId !== this.#currentTransitionId)
+            return false;
+        if (changeConfirmations.includes(false) || vetoes.includes(false))
+            return false;
+        if (this.#appState && this.#appState.onExit) {
+            await this.#appState.onExit(this.#stateContext);
+            if (transitionId !== this.#currentTransitionId)
+                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);
+    }
+    onExit(stateName, handler) {
+        const state = this.#allStates[stateName];
+        if (state) {
+            state.onExit = 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);
+}