@stefanobalocco/jfsmrouter 2.0.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2019-2025, Stefano Balocco <stefano.balocco@gmail.com>
+All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+* Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+* Neither the name of Stefano Balocco nor the names of its contributors may
+be used to endorse or promote products derived from this software without
+specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,182 @@
+# jFSMRouter
+JavaScript Finite State Machine Router
+
+`jFSMRouter` (JavaScript Finite State Machine Router) is a JavaScript class that implements a **Finite State Machine** (FSM) integrated with a **hash-based router** for browsers. It allows centralized management of states, transitions, and routes.
+
+## 1. Singleton Instance
+
+The class uses the Singleton pattern: only one global instance exists, which you can access with:
+
+```js
+import router from 'https://cdn.jsdelivr.net/gh/StefanoBalocco/jFSMRouter@2.0.0/jFSMRouter.min.js';
+```
+
+## 2. States
+
+States represent the logical steps of your application.
+
+### 2.1 Add a State
+
+```js
+router.stateAdd('home');  // Adds the "home" state
+```
+
+- Returns `true` if the state is successfully created.
+- The first state added becomes the initial current state.
+
+### 2.2 Remove a State
+
+```js
+router.stateDel('home');   // Removes the "home" state
+```
+
+### 2.3 Handle Entry and Exit Hooks
+
+- **OnEnter**: functions called when entering a state.
+- **OnLeave**: functions called when leaving a state.
+
+```js
+function onEnter(prev, next) { console.log(`Entering ${next}`); }
+function onLeave(curr, next) { console.log(`Leaving ${curr}`); }
+
+router.stateOnEnterAdd('home', onEnter);
+router.stateOnLeaveAdd('home', onLeave);
+```
+
+To remove hooks:
+
+```js
+router.stateOnEnterDel('home', onEnter);
+router.stateOnLeaveDel('home', onLeave);
+```
+
+## 3. Transitions
+
+Transitions define permissions and hooks between two states.
+
+### 3.1 Add a Transition
+
+```js
+router.transitionAdd('home', 'about');
+```
+
+### 3.2 Remove a Transition
+
+```js
+router.transitionDel('home', 'about');
+```
+
+### 3.3 Transition Hooks
+
+- **OnBefore**: called before transitioning, can block it by returning `false`.
+- **OnAfter**: called after the state change.
+
+```js
+function before() { return confirm('Go to the About page?'); }
+async function after() { console.log('Transition completed'); }
+
+router.transitionOnBeforeAdd('home', 'about', before);
+router.transitionOnAfterAdd('home', 'about', after);
+```
+
+To remove hooks:
+
+```js
+router.transitionOnBeforeDel('home', 'about', before);
+router.transitionOnAfterDel('home', 'about', after);
+```
+
+## 4. Hash-Based Routing
+
+Each route is associated with a valid state.
+
+### 4.1 Add a Route
+
+```js
+// path: '/user/:id[09]'
+router.routeAdd(
+  'home',                   // required state
+  '/user/:id[09]',          // path with variables
+  (pathDef, actual, vars) => { console.log(vars.id); },
+  () => true,               // optional availability function
+  (pathDef, actual, vars) => { console.warn('Access denied'); }  // 403
+);
+```
+
+- **path** may include variables like `:name[AZ09]`, `:num[09]`, `:str[AZ]`.
+- **routeFunction**: callback called if all checks pass.
+- **available**: sync or async function to allow/deny the route.
+- **routeFunction403**: callback called in case of access denial (403).
+
+### 4.2 Remove a Route
+
+```js
+router.routeDel('/user/:id[09]');
+```
+
+### 4.3 Special Routes
+
+```js
+router.routeSpecialAdd(404, () => { /* page not found */ });
+router.routeSpecialAdd(403, () => { /* access denied */ });
+router.routeSpecialAdd(500, () => { /* internal error */ });
+```
+
+### 4.4 Manual trigger
+
+To force navigation:
+
+```js
+router.trigger('user/123'); // sets the hash and triggers routing
+```
+
+## 5. Internal Mechanism
+
+- The `hashchange` listener calls `checkHash()`.
+- More specific paths (higher weight) take priority.
+- FSM handles the proper hook sequence: OnBefore → OnLeave → OnAfter → OnEnter.
+
+## 6. Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head><title>jFSMRouter Demo</title></head>
+<body>
+<script type="module">
+  import router from 'https://example.org/jFSMRouter.js';
+
+  // Define states
+  router.stateAdd('home');
+  router.stateAdd('user');
+
+  // State hooks
+  router.stateOnEnterAdd('home', () => console.log('Entered Home'));
+  router.stateOnEnterAdd('user', (_, prev) => console.log(`User ${prev}→user`));
+
+  // Transitions
+  router.transitionAdd('home', 'user');
+
+  // Routing
+  router.routeSpecialAdd(404, () => document.body.innerHTML = '<h1>404 Not Found</h1>');
+  router.routeAdd(
+    'home', '/home', () => alert('Welcome!')
+  );
+  router.routeAdd(
+    'user', '/user/:id[09]', (pd, act, { id }) =>
+      document.body.innerHTML = `<h1>User ${id}</h1>`
+  );
+
+  // Initial startup (if hash already present)
+  router.checkHash();
+</script>
+</body>
+</html>
+```
+
+---
+
+**Notes**:
+- Uses ES Module syntax for import.
+- Hook handling supports both sync and async functions.
+- Avoid duplicate variable IDs in a single path (throws `Duplicate path id` exception).

package/build.mjs

@@ -0,0 +1,102 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { minify } from 'terser';
+import ts from 'typescript';
+
+const __dirname = path.dirname( fileURLToPath( import.meta.url ) );
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+
+function compileTsc( configPath ) {
+	const absConfig = path.resolve( __dirname, configPath );
+	const configFile = ts.readConfigFile( absConfig, ts.sys.readFile );
+	if( configFile.error ) {
+		throw new Error( ts.formatDiagnosticsWithColorAndContext( [ configFile.error ], {
+			getCurrentDirectory: ts.sys.getCurrentDirectory,
+			getCanonicalFileName: f => f,
+			getNewLine: () => '\n'
+		} ) );
+	}
+	const parsed = ts.parseJsonConfigFileContent(
+		configFile.config,
+		ts.sys,
+		path.dirname( absConfig )
+	);
+	const program = ts.createProgram( parsed.fileNames, parsed.options );
+	const emitResult = program.emit();
+	const diagnostics = ts.getPreEmitDiagnostics( program ).concat( emitResult.diagnostics );
+	if( 0 < diagnostics.length ) {
+		const message = ts.formatDiagnosticsWithColorAndContext( diagnostics, {
+			getCurrentDirectory: ts.sys.getCurrentDirectory,
+			getCanonicalFileName: f => f,
+			getNewLine: () => '\n'
+		} );
+		throw new Error( message );
+	}
+}
+
+// ── Library ───────────────────────────────────────────────────────────────────
+
+async function buildLibrary() {
+	console.log( 'Compiling TypeScript...' );
+	compileTsc( 'tsconfig.json' );
+	console.log( 'Minifying with terser...' );
+	const code = await fs.readFile( 'jFSMRouter.js', 'utf8' );
+	const result = await minify( code, {
+		module: true,
+		toplevel: true,
+		compress: true,
+		mangle: {
+			properties: {
+				regex: /^_/
+			}
+		}
+	} );
+	if( undefined === result.code ) {
+		throw new Error( 'Terser did not produce output.' );
+	}
+	await fs.writeFile( 'jFSMRouter.min.js', result.code );
+	console.log( '✓ Library built.' );
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+async function buildTests() {
+	console.log( 'Compiling tests...' );
+	compileTsc( 'tsconfig.tests.json' );
+	console.log( '✓ Tests compiled.' );
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+const targets = {
+	library: buildLibrary,
+	tests:   buildTests
+};
+
+const args = process.argv.slice( 2 );
+
+if( 0 === args.length ) {
+	console.log( 'Usage: node build.mjs <target> [<target> ...]' );
+	console.log( 'Available targets: ' + Object.keys( targets ).join( ', ' ) );
+	process.exit( 0 );
+}
+
+const unknown = args.filter( a => !( a in targets ) );
+if( 0 < unknown.length ) {
+	console.error( 'Unknown target(s): ' + unknown.join( ', ' ) );
+	process.exit( 1 );
+}
+
+async function main() {
+	const cL1 = args.length;
+	for( let iL1 = 0; iL1 < cL1; iL1++ ) {
+		await targets[ args[ iL1 ] ]();
+	}
+}
+
+main().catch( err => {
+	console.error( err );
+	process.exit( 1 );
+} );

package/jFSMRouter.d.ts

@@ -0,0 +1,53 @@
+type Undefinedable<T> = T | undefined;
+export type FunctionOnEnter = (currentState: string, nextState: string) => (void | Promise<void>);
+export type FunctionOnLeave = (currentState: string, prevState: string) => (void | Promise<void>);
+export type FunctionOnTransitionAfter = () => (void | Promise<void>);
+export type FunctionOnTransitionBefore = () => (any | Promise<any>);
+export type CheckAvailability = (path: string, hashPath: string, params?: {
+    [key: string]: string;
+}) => (boolean | Promise<boolean>);
+export type RouteFunction = (path: string, hashPath: string, params?: {
+    [key: string]: string;
+}) => (void | Promise<void>);
+declare class jFSMRouter {
+    private static _instance;
+    static get instance(): jFSMRouter;
+    private _regexDuplicatePathId;
+    private _regexSearchVariables;
+    private _routes;
+    private _routeFunction403;
+    private _routeFunction404;
+    private _routeFunction500;
+    private _routing;
+    private _queue;
+    private _inTransition;
+    private _currentState;
+    private _states;
+    private _transitions;
+    private _window;
+    private constructor();
+    private static _CheckRouteEquivalence;
+    stateAdd(state: string): boolean;
+    stateDel(state: string): boolean;
+    stateOnEnterAdd(state: string, func: FunctionOnEnter): boolean;
+    stateOnEnterDel(state: string, func: FunctionOnEnter): boolean;
+    stateOnLeaveAdd(state: string, func: FunctionOnLeave): boolean;
+    stateOnLeaveDel(state: string, func: FunctionOnLeave): boolean;
+    transitionAdd(from: string, to: string): boolean;
+    transitionDel(from: string, to: string): boolean;
+    transitionOnBeforeAdd(from: string, to: string, func: FunctionOnTransitionBefore): boolean;
+    transitionOnBeforeDel(from: string, to: string, func: FunctionOnTransitionBefore): boolean;
+    transitionOnAfterAdd(from: string, to: string, func: FunctionOnTransitionAfter): boolean;
+    transitionOnAfterDel(from: string, to: string, func: FunctionOnTransitionAfter): boolean;
+    get state(): Undefinedable<string>;
+    stateSet(nextState: string): Promise<boolean>;
+    checkTransition(nextState: string): boolean;
+    routeSpecialAdd(code: number, routeFunction: RouteFunction): boolean;
+    routeAdd(validState: string, path: string, routeFunction: RouteFunction, available?: CheckAvailability, routeFunction403?: RouteFunction): boolean;
+    routeDel(path: string): boolean;
+    trigger(path: string): void;
+    route(path: string): Promise<void>;
+    checkHash(): Promise<void>;
+}
+declare const _default: jFSMRouter;
+export default _default;