@dharmax/state-router 1.1.1 → 1.2.0

package/ReadMe.md

@@ -6,37 +6,48 @@ What is a functional router? it's a router that captures a url changes and
 per specific pattern of url, it simply triggers a handler. It supports hash notation 
 as well as normal url patterns. It also supports contexts (url parameters).
 
-Together with the state manager - which will be the main object you'd need 
-to work with, you get a very simple semantic application state management: 
+Together with the **state manager** included here - which will be the main object you'd need 
+to work with, you get a very friendly and strong semantic application state management: 
 each state can be given a logical name, route and an associated page/component.
 
+# Features
+* Very easy to use
+* Purely Functional - no need for anything by simple JS 
+* Only one tiny dependency 
+* Easily allow any authorization logic to be used 
+* Tiny footprint
+* Doesn't monopolise the URL 
+* Supports state contexts 
 
 # Example
 
 ## state definitions
 
 ```javascript
+
+    // this is how you define the states: logical name, component name, route (as string or regex) 
     stateManager.addState('main', 'main-page', /main$/);
     stateManager.addState('login', 'login-box', 'login')
     stateManager.addState('signup', 'signup-box', /signup/)
     stateManager.addState('my-profile') // will assume the page name and the route are the same...
-    stateManager.addState('inbox')
+    stateManager.addState('inbox') // automatically assume the logical name, component and route are the same 
     stateManager.addState('about')
-    stateManager.addState('discussion', 'discussion-page', 'discussion/%')
-```
-
-## usage in the gui
-
-In your main component, you write something like that:
-
-```javascript
-
-stateManager.onChange( event => {
-    // this specific example works with RiotJs, but you get the drift
-    this.update({
-        currentPage: event.data.pageName
+    stateManager.addState('discussion', 'discussion-page', 'discussion/%') // route with parameter (the % is added to the state's context )
+
+    // this is an example of how you handle the state change (navigation events) 
+    stateManager.onChange( event => {
+        // this specific example works with RiotJs, but you get the drift
+        this.update({
+            currentPage: event.data.pageName
+        })
     })
-})
-
 
+    // this is how you can add hooks by which you can block navigation based
+    //  on any logic you want.
+    stateManager.registerChangeAuthority( async targetState => {
+        if ( ! await PermissionManager.isUserAllowedToSeePage(targetState.pageName))
+            return false
+        return openConfirmDialog('Confirm leaving this page')
+    })
+    
 ```

package/dist/router.d.ts

@@ -3,7 +3,7 @@ declare class Route {
     re: RegExp;
     handler: Function;
 }
-export declare type RoutingMode = 'history' | 'hash';
+export type RoutingMode = 'history' | 'hash';
 export declare const router: {
     mode: RoutingMode;
     routes: Route[];

package/dist/state-manager.d.ts

@@ -1,20 +1,23 @@
 import { RoutingMode } from "./router";
 import { IPubSubHandle, PubSubEvent } from "@dharmax/pubsub";
-export declare type ApplicationStateName = string;
-export declare type ApplicationState = {
+export type ApplicationStateName = string;
+export type ApplicationState = {
     name: ApplicationStateName;
     pageName: string;
     route: RegExp;
     mode?: string | string[];
 };
+export type ChangeAuthority = (state: ApplicationState) => Promise<boolean>;
 export declare class StateManager {
     private allStates;
     private appState;
     private previousState;
     private stateContext;
     static dispatcher: import("@dharmax/pubsub").PubSub;
+    private changeAuthorities;
     constructor(mode?: RoutingMode);
     onChange(handler: (event: PubSubEvent, data: any) => void): IPubSubHandle;
+    registerChangeAuthority(authorityCallback: (state: ApplicationState) => Promise<boolean>): void;
     getState(): ApplicationState;
     get previous(): ApplicationState;
     get context(): ApplicationState;
@@ -30,7 +33,7 @@ export declare class StateManager {
      * @param stateName state
      * @param context extra context (e.g. sub-state)
      */
-    setState(stateName: ApplicationStateName, context?: any): boolean;
+    setState(stateName: ApplicationStateName, context?: any): Promise<boolean>;
     /**
      * Define an application state
      * @param name

package/dist/state-manager.js

@@ -3,12 +3,21 @@ import dispatcher from "@dharmax/pubsub";
 export class StateManager {
     constructor(mode = 'hash') {
         this.allStates = {};
+        this.changeAuthorities = [];
         router.mode = mode;
         router.listen();
     }
     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 || {};
     }
@@ -31,7 +40,7 @@ export class StateManager {
     /** attempts to restore state from current url */
     restoreState(defaultState) {
         let dest = window.location.hash;
-        if (dest == '#login' || dest == '')
+        if (dest === '#login' || dest === '')
             dest = '#' + defaultState;
         router.navigate(dest);
     }
@@ -40,12 +49,17 @@ export class StateManager {
      * @param stateName state
      * @param context extra context (e.g. sub-state)
      */
-    setState(stateName, context) {
+    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(a => a(newState)));
+        if (changeConfirmations.find(c => c === false))
+            return false;
+        // perform the change
         this.previousState = this.appState;
         this.stateContext = context;
         this.appState = newState;
@@ -75,8 +89,8 @@ export class StateManager {
     }
     registerStateByState(state) {
         this.allStates[state.name] = state;
-        router.add(state.route, (context) => {
-            if (this.setState(state.name, context)) {
+        router.add(state.route, async (context) => {
+            if (await this.setState(state.name, context)) {
                 // @ts-ignore
                 if (window.ga) {
                     // @ts-ignore

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dharmax/state-router",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A cute and tight router and application state controller",
-  "main": "dist/router.js",
+  "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -25,7 +25,7 @@
   },
   "homepage": "https://github.com/dharmax/state-routerr",
   "devDependencies": {
-    "typescript": "^4.4.3"
+    "typescript": "^4.9.3"
   },
   "dependencies": {
     "@dharmax/pubsub": "^1.1.0"

package/src/state-manager.ts

@@ -11,6 +11,7 @@ export type ApplicationState = {
     mode?: string | string[]
 }
 
+export type ChangeAuthority = (state: ApplicationState) => Promise<boolean>
 
 export class StateManager {
     private allStates: { [name: string]: ApplicationState } = {}
@@ -19,6 +20,7 @@ export class StateManager {
     private stateContext: ApplicationState
 
     public static dispatcher = dispatcher
+    private changeAuthorities: ChangeAuthority[] = [];
 
     constructor(mode: RoutingMode = 'hash') {
 
@@ -27,11 +29,20 @@ export class StateManager {
 
     }
 
-    onChange(handler: (event: PubSubEvent, data: any) => void):IPubSubHandle {
+    onChange(handler: (event: PubSubEvent, data: any) => void): IPubSubHandle {
 
         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: (targetState: ApplicationState) => Promise<boolean>) {
+        this.changeAuthorities.push(authorityCallback)
+    }
+
     getState(): ApplicationState {
         return this.appState || <ApplicationState>{}
     }
@@ -55,7 +66,7 @@ export class StateManager {
             this.setState(state)
     }
 
-    /** attempts to restore state from current url */
+    /** attempts to restore state from current url. Currently, works only in hash mode */
     restoreState(defaultState: ApplicationStateName) {
         let dest = window.location.hash
         if (dest == '#login' || dest == '')
@@ -68,7 +79,7 @@ export class StateManager {
      * @param stateName state
      * @param context extra context (e.g. sub-state)
      */
-    setState(stateName: ApplicationStateName, context?: any): boolean {
+    async setState(stateName: ApplicationStateName, context?: any): Promise<boolean> {
 
         const newState = this.allStates[stateName];
         if (!newState) {
@@ -76,6 +87,12 @@ export class StateManager {
             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) ))
+        if (changeConfirmations.find( c => c === false))
+            return false
+
+        // perform the change
         this.previousState = this.appState
         this.stateContext = context
         this.appState = newState
@@ -108,15 +125,14 @@ export class StateManager {
 
     registerStateByState(state: ApplicationState) {
         this.allStates[state.name] = state
-        router.add(state.route, (context: any) => {
-            if (this.setState(state.name, context)) {
+        router.add(state.route, async (context: any) => {
+            if (await this.setState(state.name, context)) {
 
                 // @ts-ignore
                 if (window.ga) {
                     // @ts-ignore
                     window.ga('send', 'pageview', `/${state.name}/${context || ''}`);
                 }
-
             }
         })
     }