@marianmeres/simple-router 1.9.0

package/README.md

@@ -0,0 +1,75 @@
+# @marianmeres/simple-router
+
+Small path-like string parser. Originally inspired by
+[sapper-like regex routes](https://sapper.svelte.dev/docs#Regexes_in_routes).
+Intended primarily for - but not limited to - client side SPA routing.
+
+## Installation
+
+```shell
+npm i @marianmeres/simple-router
+```
+
+## Quick example
+
+```js
+// routes definitions can be added via ctor config object
+const router = new SimpleRouter({
+    '/': () => pageIndex(),
+    '*': () => page404(), // catch all (last resort fallback)
+});
+
+// or via "on" api
+router.on(
+    '/article/[id([0-9]+)]/[slug]',
+    ({ id, slug }) => pageArticle(id, slug)
+);
+
+// finally, perform route match (execute router)
+// (example here returns "component" which is then "rendered")
+window.onhashchange = () => render(router.exec(location.hash));
+```
+
+See [tests](tests) or [examples](examples) for more.
+
+## Route matching
+
+Route segments:
+- `exact` matches `exact`
+- `[name]` matches `any` and is resolved as `{ name: 'any' }` param
+- `[name(regex)]` matches if `regex.test(segment)` is truthy
+- `exact?` or `[name]?` marks segment as optional
+- `[...name]` matches "rest segments"
+
+Few notes on segments separators (which is slash `/` by default):
+- multiple ones are always normalized to single,
+- separator is always trimmed (both left and right) before matching
+
+| Example route definition  | Example input      | Result                      |
+| ------------------------- | ------------------ | --------------------------- |
+| `/foo`                    | `/bar`             | `null`                      |
+| `/foo`                    | (empty string)     | `null`                      |
+| `/foo/[bar]`              | `/foo`             | `null`                      |
+| `/[foo]/bar`              | `/foo`             | `null`                      |
+| `/[foo]/[bar]`            | `/foo`             | `null`                      |
+| `/`                       | (empty string)     | `{}`                        |
+| (empty string)            | `///`              | `{}`                        |
+| `foo`                     | `foo`              | `{}`                        |
+| `//foo///bar.baz/`        | `foo/bar.baz`      | `{}`                        |
+| `foo/bar/baz`             | `//foo//bar/baz//` | `{}`                        |
+| `/[foo]`                  | `/bar`             | `{"foo":"bar"}`             |
+| `#/foo/[bar]`             | `#/foo/bat`        | `{"bar":"bat"}`             |
+| `#/[foo]/[bar]`           | `#/baz/bat`        | `{"foo":"baz","bar":"bat"}` |
+| `#/[foo]/bar`             | `#/baz/bar`        | `{"foo":"baz"}`             |
+| `/[id([0-9]+)]`           | `/123`             | `{"id":"123"}`              |
+| `/[id(\d-\d)]`            | `/1-2`             | `{"id":"1-2"}`              |
+| `/[id([0-9]+)]`           | `/foo`             | `null`                      |
+| `/foo/[bar]/[id([0-9]+)]` | `/foo/baz/123`     | `{"bar":"baz","id":"123"}`  |
+| `/foo/[id([0-9]+)]/[bar]` | `/foo/bar/baz`     | `null`                      |
+| `/foo/[([0-9]+)]`         | `/foo/123`         | `null` (missing name before regex) |
+| `/foo/[bar]?`             | `/foo`             | `{}`                        |
+| `/foo/[bar]?`             | `/foo/bar`         | `{ bar: 'bar' }`            |
+| `/foo/[bar]?/baz`         | `/foo/bar/baz`     | `{ bar: 'bar' }`            |
+| `/[...path]/[file]`       | `/foo/bar/baz.js`  | `{ path': 'foo/bar', file: 'baz.js' }`|
+See [tests](tests) or [examples](examples) for more.
+

package/dist/index.cjs

@@ -0,0 +1,221 @@
+'use strict';
+
+class SimpleRoute {
+    route;
+    static SPLITTER = '/';
+    _parsed;
+    constructor(route) {
+        this.route = route;
+        this._parsed = SimpleRoute._parse(route);
+    }
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
+    static _escapeRegExp(str) {
+        return str.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&');
+    }
+    static _sanitizeAndSplit(str) {
+        const s = SimpleRoute._escapeRegExp(SimpleRoute.SPLITTER);
+        return (`${str}`
+            .trim()
+            // splitter trim left and right
+            .replace(new RegExp(`^(${s})+`), '')
+            .replace(new RegExp(`(${s})+$`), '')
+            .split(SimpleRoute.SPLITTER)
+            // remove empty segments... will "normalize" multiple splitters into one
+            .filter(Boolean));
+    }
+    static _parse(route) {
+        let wasSpread = false;
+        return SimpleRoute._sanitizeAndSplit(route).reduce((memo, segment) => {
+            let name = null;
+            // if optional, remove trailing '?' marker
+            let isOptional = segment.endsWith('?');
+            if (isOptional)
+                segment = segment.slice(0, -1);
+            let isSpread = segment.startsWith('[...');
+            if (isSpread) {
+                if (isOptional) {
+                    throw new Error('Spread segment must not be marked as optional');
+                }
+                if (wasSpread) {
+                    throw new Error('Multiple spread segments are invalid');
+                }
+                wasSpread = true;
+                segment = '[' + segment.substr(4);
+            }
+            let test = new RegExp('^' + SimpleRoute._escapeRegExp(segment) + '$');
+            // starting with at least one word char within brackets...
+            let m = segment.match(/^\[(\w.+)]$/);
+            if (m) {
+                name = m[1];
+                test = /.+/;
+                // id([0-9]+)
+                let m2 = m[1].match(/^(\w.*)\((.+)\)$/);
+                if (m2) {
+                    name = m2[1];
+                    test = new RegExp('^' + m2[2] + '$');
+                }
+            }
+            memo.push({ segment, name, test, isOptional, isSpread });
+            return memo;
+        }, []);
+    }
+    static parseQueryString(str) {
+        return `${str}`
+            .replace(/^&/, '')
+            .replace(/&$/, '')
+            .split('&')
+            .reduce((memo, kvpair) => {
+            const [k, v] = kvpair.split('=').map(decodeURIComponent);
+            if (k.length)
+                memo[k] = v;
+            return memo;
+        }, {});
+    }
+    parse(url, allowQueryParams = true) {
+        let matched = {};
+        const qPos = url.indexOf('?');
+        if (allowQueryParams && ~qPos) {
+            const _backup = url;
+            url = _backup.slice(0, qPos);
+            matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
+        }
+        let segments = SimpleRoute._sanitizeAndSplit(url);
+        // SPREAD PARAMS DANCING BLOCK - if there are "spread" definitions we need to adjust input
+        // that is "group" (join) segments that were initially splitted
+        const hasSpread = !!this._parsed.filter((v) => v.isSpread).length;
+        if (hasSpread) {
+            let newSegments = [];
+            this._parsed.forEach((p, i) => {
+                if (p.isSpread) {
+                    // there are defined segments after the "spread" definition
+                    if (this._parsed[i + 1]) {
+                        // SimpleRoute
+                        newSegments.push(segments.slice(0, this._parsed.length - i).join(SimpleRoute.SPLITTER));
+                        segments = segments.slice(this._parsed.length - i);
+                    }
+                    // there are no more defined segments
+                    else {
+                        newSegments.push(segments.join(SimpleRoute.SPLITTER));
+                    }
+                }
+                else {
+                    newSegments = newSegments.concat(segments.slice(0, 1));
+                    segments = segments.slice(1);
+                }
+            });
+            segments = newSegments;
+        }
+        // minimum required (not optional) segments length
+        const reqLen = this._parsed.reduce((memo, p, idx, arr) => {
+            const next = arr[idx + 1];
+            // if is not optional or has not optional still to come
+            if (!p.isOptional || (next && !next.isOptional)) {
+                memo++;
+            }
+            return memo;
+        }, 0);
+        // quick cheap check: if counts dont match = no match
+        if (segments.length < reqLen) {
+            return null;
+        }
+        for (const [i, s] of segments.entries()) {
+            const p = this._parsed[i];
+            if (!p || !p.test.test(s)) {
+                return null;
+            }
+            if (p.name) {
+                matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
+            }
+        }
+        return matched;
+    }
+}
+
+class SimpleRouter {
+    // console log debug on/off switch
+    static debug = false;
+    _routes = [];
+    _catchAll;
+    // current (last matched) route and params (in the shape { route: "...", params: {} } )
+    _current = {
+        route: null,
+        params: null,
+        label: null,
+    };
+    // https://svelte.dev/docs#Store_contract
+    _subscriptions = new Set();
+    constructor(config = null) {
+        Object.entries(config || {}).forEach(([route, cb]) => {
+            this.on(route, cb);
+        });
+    }
+    _dbg(...a) {
+        SimpleRouter.debug && console.log('[SimpleRouter]', ...a);
+    }
+    reset() {
+        this._routes = [];
+        return this;
+    }
+    get current() {
+        return this._current;
+    }
+    on(routes, cb, { label = null, allowQueryParams = true } = {}) {
+        if (!Array.isArray(routes))
+            routes = [routes];
+        routes.forEach((route) => {
+            if (route === '*') {
+                this._catchAll = cb;
+            }
+            else {
+                this._routes.push([new SimpleRoute(route), cb, allowQueryParams, label]);
+            }
+        });
+    }
+    exec(url, fallbackFn) {
+        const dbgPrefix = `'${url}' -> `;
+        const isFn = (v) => typeof v === 'function';
+        for (const [route, cb, allowQueryParams, label] of this._routes) {
+            // first match wins
+            // parse returns null or params object (which can be empty)
+            const params = route.parse(url, allowQueryParams);
+            if (params) {
+                this._publishCurrent(route.route, params, label);
+                this._dbg(`${dbgPrefix}matches '${route.route}' with`, params);
+                return isFn(cb) ? cb(params, route.route) : true;
+            }
+        }
+        if (isFn(fallbackFn)) {
+            this._publishCurrent(null, null, null);
+            this._dbg(`${dbgPrefix}fallback...`);
+            return fallbackFn();
+        }
+        if (isFn(this._catchAll)) {
+            this._publishCurrent('*', null, null);
+            this._dbg(`${dbgPrefix}catchall...`);
+            return this._catchAll(null, '*');
+        }
+        this._publishCurrent(null, null, null);
+        this._dbg(`${dbgPrefix}no match...`);
+        return false;
+    }
+    _publishCurrent(route, params, label) {
+        this._current = { route, params, label };
+        this._subscriptions.forEach((cb) => cb(this._current));
+    }
+    // https://svelte.dev/docs#Store_contract
+    subscribe(subscription) {
+        if (typeof subscription !== 'function') {
+            throw new TypeError('Subscription is not a function');
+        }
+        this._subscriptions.add(subscription);
+        subscription(this._current);
+        // For interoperability with RxJS Observables, the .subscribe method is also
+        // allowed to return an object with an .unsubscribe method
+        return {
+            unsubscribe: () => this._subscriptions.delete(subscription),
+        };
+    }
+}
+
+exports.SimpleRoute = SimpleRoute;
+exports.SimpleRouter = SimpleRouter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SimpleRoute } from './route';
+export { SimpleRouter } from './router';

package/dist/index.js

@@ -0,0 +1,218 @@
+class SimpleRoute {
+    route;
+    static SPLITTER = '/';
+    _parsed;
+    constructor(route) {
+        this.route = route;
+        this._parsed = SimpleRoute._parse(route);
+    }
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
+    static _escapeRegExp(str) {
+        return str.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&');
+    }
+    static _sanitizeAndSplit(str) {
+        const s = SimpleRoute._escapeRegExp(SimpleRoute.SPLITTER);
+        return (`${str}`
+            .trim()
+            // splitter trim left and right
+            .replace(new RegExp(`^(${s})+`), '')
+            .replace(new RegExp(`(${s})+$`), '')
+            .split(SimpleRoute.SPLITTER)
+            // remove empty segments... will "normalize" multiple splitters into one
+            .filter(Boolean));
+    }
+    static _parse(route) {
+        let wasSpread = false;
+        return SimpleRoute._sanitizeAndSplit(route).reduce((memo, segment) => {
+            let name = null;
+            // if optional, remove trailing '?' marker
+            let isOptional = segment.endsWith('?');
+            if (isOptional)
+                segment = segment.slice(0, -1);
+            let isSpread = segment.startsWith('[...');
+            if (isSpread) {
+                if (isOptional) {
+                    throw new Error('Spread segment must not be marked as optional');
+                }
+                if (wasSpread) {
+                    throw new Error('Multiple spread segments are invalid');
+                }
+                wasSpread = true;
+                segment = '[' + segment.substr(4);
+            }
+            let test = new RegExp('^' + SimpleRoute._escapeRegExp(segment) + '$');
+            // starting with at least one word char within brackets...
+            let m = segment.match(/^\[(\w.+)]$/);
+            if (m) {
+                name = m[1];
+                test = /.+/;
+                // id([0-9]+)
+                let m2 = m[1].match(/^(\w.*)\((.+)\)$/);
+                if (m2) {
+                    name = m2[1];
+                    test = new RegExp('^' + m2[2] + '$');
+                }
+            }
+            memo.push({ segment, name, test, isOptional, isSpread });
+            return memo;
+        }, []);
+    }
+    static parseQueryString(str) {
+        return `${str}`
+            .replace(/^&/, '')
+            .replace(/&$/, '')
+            .split('&')
+            .reduce((memo, kvpair) => {
+            const [k, v] = kvpair.split('=').map(decodeURIComponent);
+            if (k.length)
+                memo[k] = v;
+            return memo;
+        }, {});
+    }
+    parse(url, allowQueryParams = true) {
+        let matched = {};
+        const qPos = url.indexOf('?');
+        if (allowQueryParams && ~qPos) {
+            const _backup = url;
+            url = _backup.slice(0, qPos);
+            matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
+        }
+        let segments = SimpleRoute._sanitizeAndSplit(url);
+        // SPREAD PARAMS DANCING BLOCK - if there are "spread" definitions we need to adjust input
+        // that is "group" (join) segments that were initially splitted
+        const hasSpread = !!this._parsed.filter((v) => v.isSpread).length;
+        if (hasSpread) {
+            let newSegments = [];
+            this._parsed.forEach((p, i) => {
+                if (p.isSpread) {
+                    // there are defined segments after the "spread" definition
+                    if (this._parsed[i + 1]) {
+                        // SimpleRoute
+                        newSegments.push(segments.slice(0, this._parsed.length - i).join(SimpleRoute.SPLITTER));
+                        segments = segments.slice(this._parsed.length - i);
+                    }
+                    // there are no more defined segments
+                    else {
+                        newSegments.push(segments.join(SimpleRoute.SPLITTER));
+                    }
+                }
+                else {
+                    newSegments = newSegments.concat(segments.slice(0, 1));
+                    segments = segments.slice(1);
+                }
+            });
+            segments = newSegments;
+        }
+        // minimum required (not optional) segments length
+        const reqLen = this._parsed.reduce((memo, p, idx, arr) => {
+            const next = arr[idx + 1];
+            // if is not optional or has not optional still to come
+            if (!p.isOptional || (next && !next.isOptional)) {
+                memo++;
+            }
+            return memo;
+        }, 0);
+        // quick cheap check: if counts dont match = no match
+        if (segments.length < reqLen) {
+            return null;
+        }
+        for (const [i, s] of segments.entries()) {
+            const p = this._parsed[i];
+            if (!p || !p.test.test(s)) {
+                return null;
+            }
+            if (p.name) {
+                matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
+            }
+        }
+        return matched;
+    }
+}
+
+class SimpleRouter {
+    // console log debug on/off switch
+    static debug = false;
+    _routes = [];
+    _catchAll;
+    // current (last matched) route and params (in the shape { route: "...", params: {} } )
+    _current = {
+        route: null,
+        params: null,
+        label: null,
+    };
+    // https://svelte.dev/docs#Store_contract
+    _subscriptions = new Set();
+    constructor(config = null) {
+        Object.entries(config || {}).forEach(([route, cb]) => {
+            this.on(route, cb);
+        });
+    }
+    _dbg(...a) {
+        SimpleRouter.debug && console.log('[SimpleRouter]', ...a);
+    }
+    reset() {
+        this._routes = [];
+        return this;
+    }
+    get current() {
+        return this._current;
+    }
+    on(routes, cb, { label = null, allowQueryParams = true } = {}) {
+        if (!Array.isArray(routes))
+            routes = [routes];
+        routes.forEach((route) => {
+            if (route === '*') {
+                this._catchAll = cb;
+            }
+            else {
+                this._routes.push([new SimpleRoute(route), cb, allowQueryParams, label]);
+            }
+        });
+    }
+    exec(url, fallbackFn) {
+        const dbgPrefix = `'${url}' -> `;
+        const isFn = (v) => typeof v === 'function';
+        for (const [route, cb, allowQueryParams, label] of this._routes) {
+            // first match wins
+            // parse returns null or params object (which can be empty)
+            const params = route.parse(url, allowQueryParams);
+            if (params) {
+                this._publishCurrent(route.route, params, label);
+                this._dbg(`${dbgPrefix}matches '${route.route}' with`, params);
+                return isFn(cb) ? cb(params, route.route) : true;
+            }
+        }
+        if (isFn(fallbackFn)) {
+            this._publishCurrent(null, null, null);
+            this._dbg(`${dbgPrefix}fallback...`);
+            return fallbackFn();
+        }
+        if (isFn(this._catchAll)) {
+            this._publishCurrent('*', null, null);
+            this._dbg(`${dbgPrefix}catchall...`);
+            return this._catchAll(null, '*');
+        }
+        this._publishCurrent(null, null, null);
+        this._dbg(`${dbgPrefix}no match...`);
+        return false;
+    }
+    _publishCurrent(route, params, label) {
+        this._current = { route, params, label };
+        this._subscriptions.forEach((cb) => cb(this._current));
+    }
+    // https://svelte.dev/docs#Store_contract
+    subscribe(subscription) {
+        if (typeof subscription !== 'function') {
+            throw new TypeError('Subscription is not a function');
+        }
+        this._subscriptions.add(subscription);
+        subscription(this._current);
+        // For interoperability with RxJS Observables, the .subscribe method is also
+        // allowed to return an object with an .unsubscribe method
+        return {
+            unsubscribe: () => this._subscriptions.delete(subscription),
+        };
+    }
+}
+
+export { SimpleRoute, SimpleRouter };

package/dist/route.d.ts

@@ -0,0 +1,18 @@
+export interface RouteConfig {
+    segment: string;
+    name: string;
+    test: RegExp;
+    isOptional: boolean;
+    isSpread: boolean;
+}
+export declare class SimpleRoute {
+    readonly route: any;
+    static SPLITTER: string;
+    protected _parsed: RouteConfig[];
+    constructor(route: any);
+    protected static _escapeRegExp(str: string): string;
+    protected static _sanitizeAndSplit(str: any): string[];
+    protected static _parse(route: any): any[];
+    static parseQueryString(str: any): {};
+    parse(url: any, allowQueryParams?: boolean): {};
+}

package/dist/router.d.ts

@@ -0,0 +1,31 @@
+import { SimpleRoute } from './route';
+export declare class SimpleRouter {
+    static debug: boolean;
+    protected _routes: [SimpleRoute, Function, boolean, string][];
+    protected _catchAll: Function;
+    protected _current: {
+        route: string;
+        params: any;
+        label: string;
+    };
+    protected _subscriptions: Set<Function>;
+    constructor(config?: {
+        [route: string]: Function;
+    });
+    protected _dbg(...a: any[]): void;
+    reset(): this;
+    get current(): {
+        route: string;
+        params: any;
+        label: string;
+    };
+    on(routes: string | string[], cb: Function, { label, allowQueryParams }?: {
+        label?: any;
+        allowQueryParams?: boolean;
+    }): void;
+    exec(url: string, fallbackFn?: Function): any;
+    protected _publishCurrent(route: any, params: any, label: any): void;
+    subscribe(subscription: Function): {
+        unsubscribe: () => boolean;
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@marianmeres/simple-router",
+  "version": "1.9.0",
+  "description": "Minimalistic route parser for sapper-like regex routes",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist/*",
+    "build": "npm run clean && rollup -c",
+    "dev": "npm run clean && rollup -c -w",
+    "prettier": "prettier --write \"{src,tests,examples}/**/*.{js,ts,json}\"",
+    "release": "release",
+    "test": "test-runner",
+    "test:watch": "nodemon -q -w dist -w tests -x test-runner --"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marianmeres/simple-router.git"
+  },
+  "keywords": [
+    "router"
+  ],
+  "author": "Marian Meres <marian@meres.sk>",
+  "license": "WTFPL",
+  "bugs": {
+    "url": "https://github.com/marianmeres/simple-router/issues"
+  },
+  "homepage": "https://github.com/marianmeres/simple-router#readme",
+  "devDependencies": {
+    "@marianmeres/release": "^0.0.7",
+    "@marianmeres/test-runner": "^2.0.8",
+    "@rollup/plugin-typescript": "^9.0.2",
+    "@types/node": "^14.18.33",
+    "lodash": "^4.17.21",
+    "nodemon": "^2.0.20",
+    "prettier": "^2.2.1",
+    "rimraf": "^3.0.2",
+    "rollup": "^3.3.0",
+    "tslib": "^2.4.1",
+    "typescript": "^4.8.4"
+  }
+}