space-router 0.9.5 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@
 <h4 align="center">Framework agnostic router for single page apps</h4>
 <br />
 
-Space Router packs all the features you need to keep your app in sync with the url. It's distinct from many other routers in that there is only **a single callback**. This callback can be used to re-render your applocation, update a store and perform other actions on each url change. Space Router is **stateless**, it doesn't store the current route leaving state completely up to you to handle.
+Space Router packs all the features you need to keep your app in sync with the url. It's distinct from many other routers in that there is only **a single callback**. This callback can be used to re-render your application, update a store and perform other actions on each url change. Space Router is **stateless**, it doesn't store the current route leaving state completely up to you to handle.
 
 In summary, Space Router:
 
@@ -14,6 +14,7 @@ In summary, Space Router:
 - extracts url parameters and parses query strings
 - supports nested routes and arbitrary route metadata
 - fits into a wide range of application architectures and frameworks
+- ships TypeScript types
 - has no dependencies and weighs less than 2kb
 
 ## Install

package/dist/history.d.ts

@@ -0,0 +1,12 @@
+export type Mode = 'history' | 'hash' | 'memory';
+export interface History {
+    listen(onChange: (url: string) => void): () => void;
+    getUrl(): string;
+    push(url: string): void;
+    replace(url: string): void;
+}
+export interface CreateHistoryOptions {
+    mode?: Mode;
+    sync?: boolean;
+}
+export declare function createHistory(options?: CreateHistoryOptions): History;

package/dist/history.js

@@ -0,0 +1,98 @@
+export function createHistory(options = {}) {
+    const sync = !!options.sync;
+    let mode = options.mode || 'history';
+    let listener = null;
+    let pending = false;
+    const memory = [];
+    if (typeof window === 'undefined') {
+        mode = 'memory';
+    }
+    function emit() {
+        if (listener)
+            listener(getUrl());
+    }
+    function schedule() {
+        if (sync)
+            return emit();
+        if (pending)
+            return;
+        pending = true;
+        queueMicrotask(() => {
+            pending = false;
+            emit();
+        });
+    }
+    function listen(onChange) {
+        if (listener)
+            throw new Error('Already listening');
+        listener = onChange;
+        let off;
+        if (mode !== 'memory') {
+            off = on(window, mode === 'history' ? 'popstate' : 'hashchange', schedule);
+            schedule();
+        }
+        return () => {
+            listener = null;
+            if (off)
+                off();
+        };
+    }
+    function go(url, replace) {
+        url = url.replace(/^\/?#?\/?/, '/').replace(/\/$/, '') || '/';
+        if (mode === 'history') {
+            history[replace ? 'replaceState' : 'pushState']({}, '', url);
+            schedule();
+        }
+        else if (mode === 'hash') {
+            // hashchange only fires when the URL actually changes; if it doesn't,
+            // we schedule the emit manually so navigation stays consistent with
+            // history mode (where pushState is silent and we always schedule).
+            const same = url === getUrl();
+            location[replace ? 'replace' : 'assign']('#' + url);
+            if (same)
+                schedule();
+        }
+        else if (mode === 'memory') {
+            if (replace && memory.length) {
+                memory[memory.length - 1] = url;
+            }
+            else {
+                memory.push(url);
+            }
+            schedule();
+        }
+    }
+    function getUrl() {
+        if (mode === 'memory') {
+            return memory[memory.length - 1] ?? '';
+        }
+        const hash = getHash();
+        if (mode === 'hash') {
+            return hash === '' ? '/' : hash;
+        }
+        let url = location.pathname + location.search;
+        if (hash !== '') {
+            url += '#' + hash;
+        }
+        return url;
+    }
+    function getHash() {
+        return location.hash.slice(1);
+    }
+    return {
+        listen,
+        getUrl,
+        push(url) {
+            go(url);
+        },
+        replace(url) {
+            go(url, true);
+        },
+    };
+}
+function on(el, type, fn) {
+    el.addEventListener(type, fn, false);
+    return function off() {
+        el.removeEventListener(type, fn, false);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { qs } from './qs.ts';
+export { createHistory } from './history.ts';
+export { createMatcher, createRouter, merge } from './router.ts';
+export type { Qs } from './qs.ts';
+export type { Mode, History, CreateHistoryOptions } from './history.ts';
+export type { MatcherOptions, RouteData, RouterOptions, Route, NavigateTarget, To, Redirect, RouteDefinition, Matcher, Router, } from './router.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { qs } from "./qs.js";
+export { createHistory } from "./history.js";
+export { createMatcher, createRouter, merge } from "./router.js";

package/dist/match.d.ts

@@ -0,0 +1,11 @@
+import type { Qs } from './qs.ts';
+export interface MatchedRoute {
+    pattern: string;
+    url: string;
+    pathname: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    search: string;
+    hash: string;
+}
+export declare function matchOne(pattern: string, url: string, qs?: Qs): MatchedRoute | undefined;

package/dist/match.js

@@ -0,0 +1,59 @@
+export function matchOne(pattern, url, qs) {
+    if (!pattern)
+        return;
+    const re = /(?:\?([^#]*))?(#.*)?$/;
+    const originalUrl = url;
+    const originalPattern = pattern;
+    const c = url.match(re);
+    const params = {};
+    let query = {};
+    let search = '';
+    let hash = '';
+    if (c && c[1]) {
+        search = '?' + c[1];
+        query = qs ? qs.parse(c[1]) : {};
+    }
+    if (c && c[2]) {
+        hash = c[2];
+    }
+    if (pattern !== '*') {
+        const urlSegs = segmentize(url.replace(re, ''));
+        const patSegs = segmentize(pattern);
+        const max = Math.max(urlSegs.length, patSegs.length);
+        for (let i = 0; i < max; i++) {
+            const ps = patSegs[i];
+            if (ps && ps.charAt(0) === ':') {
+                const param = ps.replace(/(^:|[+*?]+$)/g, '');
+                const flags = ps.match(/[+*?]+$/)?.[0] ?? '';
+                const plus = flags.indexOf('+') > -1;
+                const star = flags.indexOf('*') > -1;
+                const val = urlSegs[i] || '';
+                if (!val && !star && (flags.indexOf('?') < 0 || plus))
+                    return;
+                params[param] = decodeURIComponent(val);
+                if (plus || star) {
+                    params[param] = urlSegs.slice(i).map(decodeURIComponent).join('/');
+                    break;
+                }
+            }
+            else if (ps !== urlSegs[i]) {
+                return;
+            }
+        }
+    }
+    return {
+        pattern: originalPattern,
+        url: originalUrl,
+        pathname: originalUrl.replace(re, ''),
+        params,
+        query,
+        search,
+        hash,
+    };
+}
+function segmentize(url) {
+    return strip(url).split('/');
+}
+function strip(url) {
+    return url.replace(/(^\/+|\/+$)/g, '');
+}

package/dist/qs.d.ts

@@ -0,0 +1,5 @@
+export interface Qs {
+    parse(queryString: string): Record<string, string>;
+    stringify(query: Record<string, unknown>): string;
+}
+export declare const qs: Qs;

package/dist/qs.js

@@ -0,0 +1,27 @@
+export const qs = {
+    parse(queryString) {
+        return queryString.split('&').reduce((acc, pair) => {
+            if (!pair)
+                return acc;
+            const i = pair.indexOf('=');
+            const key = decode(i < 0 ? pair : pair.slice(0, i));
+            const val = i < 0 ? '' : decode(pair.slice(i + 1));
+            acc[key] = val;
+            return acc;
+        }, {});
+    },
+    stringify(query) {
+        return Object.keys(query)
+            .reduce((acc, key) => {
+            const value = query[key];
+            if (value !== undefined) {
+                acc.push(encodeURIComponent(key) + '=' + encodeURIComponent(value));
+            }
+            return acc;
+        }, [])
+            .join('&');
+    },
+};
+function decode(s) {
+    return decodeURIComponent(s.replace(/\+/g, ' '));
+}

package/dist/router.d.ts

@@ -0,0 +1,53 @@
+import { type MatchedRoute } from './match.ts';
+import { type Mode } from './history.ts';
+import { type Qs } from './qs.ts';
+export interface RouterOptions {
+    mode?: Mode;
+    qs?: Qs;
+    sync?: boolean;
+}
+export interface MatcherOptions {
+    qs?: Qs;
+}
+export interface Route<Data = Record<string, unknown>> extends MatchedRoute {
+    data: RouteData<Data>[];
+}
+export interface NavigateTarget {
+    url?: string;
+    pathname?: string;
+    params?: Record<string, string | number>;
+    query?: Record<string, unknown> | null;
+    hash?: string | null;
+    replace?: boolean;
+    merge?: boolean;
+}
+export type To = string | NavigateTarget;
+export type Redirect<Data = Record<string, unknown>> = To | ((route: Route<Data>) => To);
+export type RouteData<Data = Record<string, unknown>> = Data & {
+    path: string;
+    redirect?: Redirect<Data>;
+};
+export type RouteDefinition<Data = Record<string, unknown>> = Data & {
+    path?: string;
+    redirect?: Redirect<Data>;
+    routes?: RouteDefinition<Data>[];
+};
+export interface Router<Data = Record<string, unknown>> {
+    listen(routes: RouteDefinition<Data>[], onChange?: (route: Route<Data>) => void): () => void;
+    navigate(to: To, curr?: Route<Data>): void;
+    href(to: To, curr?: Route<Data>): string;
+    match(url: string): Route<Data> | undefined;
+    getUrl(): string;
+}
+export interface Matcher<Data = Record<string, unknown>> {
+    match(url: string): Route<Data> | undefined;
+}
+interface FlatRoute<Data = Record<string, unknown>> {
+    pattern: string;
+    data: RouteData<Data>[];
+}
+export declare function createRouter<Data = Record<string, unknown>>(options?: RouterOptions): Router<Data>;
+export declare function createMatcher<Data = Record<string, unknown>>(routeMap: RouteDefinition<Data>[], options?: MatcherOptions): Matcher<Data>;
+export declare function flatten<Data = Record<string, unknown>>(routeMap: RouteDefinition<Data>[]): FlatRoute<Data>[];
+export declare function merge(curr: Partial<Route> | NavigateTarget | undefined, to: NavigateTarget): NavigateTarget;
+export {};

package/dist/router.js

@@ -0,0 +1,141 @@
+import { matchOne } from "./match.js";
+import { createHistory } from "./history.js";
+import { qs as defaultQs } from "./qs.js";
+const PARAM_RE = /:([A-Za-z0-9_]+)([+*?])?/g;
+const MAX_REDIRECTS = 10;
+export function createRouter(options = {}) {
+    const mode = options.mode || 'history';
+    const qs = options.qs || defaultQs;
+    const sync = options.sync || false;
+    const history = createHistory({ mode, sync });
+    let matcher = createMatcher([], { qs });
+    const router = {
+        listen(routeMap, cb) {
+            matcher = createMatcher(routeMap, { qs });
+            let redirects = 0;
+            return history.listen((url) => {
+                const route = matcher.match(url);
+                if (!route) {
+                    redirects = 0;
+                    return;
+                }
+                for (const r of route.data) {
+                    if (r.redirect) {
+                        if (++redirects > MAX_REDIRECTS) {
+                            redirects = 0;
+                            throw new Error('space-router: too many redirects');
+                        }
+                        const target = typeof r.redirect === 'function' ? r.redirect(route) : r.redirect;
+                        return router.navigate({ url: router.href(target), replace: true });
+                    }
+                }
+                redirects = 0;
+                if (cb)
+                    cb(route);
+            });
+        },
+        navigate(to, curr) {
+            const target = typeof to === 'string' ? { url: to } : to;
+            const url = router.href(target, curr);
+            if (target.replace) {
+                history.replace(url);
+            }
+            else {
+                history.push(url);
+            }
+        },
+        href(to, curr) {
+            // already a url
+            if (typeof to === 'string') {
+                return to;
+            }
+            // align with navigate API
+            if (to.url) {
+                return to.url;
+            }
+            let target = to;
+            if (target.merge) {
+                const c = curr || router.match(router.getUrl());
+                target = merge(c, target);
+            }
+            let url = target.pathname || '/';
+            if (target.params) {
+                const params = target.params;
+                url = url.replace(PARAM_RE, (m, name, flag) => {
+                    const v = params[name];
+                    if (v == null)
+                        return m;
+                    if (flag === '+' || flag === '*') {
+                        return String(v).split('/').map(encodeURIComponent).join('/');
+                    }
+                    return encodeURIComponent(String(v));
+                });
+            }
+            if (target.query && Object.keys(target.query).length) {
+                const query = qs.stringify(target.query);
+                if (query) {
+                    url = url + '?' + query;
+                }
+            }
+            if (target.hash) {
+                const prefix = target.hash.startsWith('#') ? '' : '#';
+                url = url + prefix + target.hash;
+            }
+            return url;
+        },
+        match(url) {
+            return matcher.match(url);
+        },
+        getUrl() {
+            return history.getUrl();
+        },
+    };
+    return router;
+}
+export function createMatcher(routeMap, options = {}) {
+    const routes = flatten(routeMap);
+    const qs = options.qs || defaultQs;
+    return {
+        match(url) {
+            if (!url)
+                return undefined;
+            for (const route of routes) {
+                const m = matchOne(route.pattern, url, qs);
+                if (m) {
+                    return { ...m, data: route.data };
+                }
+            }
+            return undefined;
+        },
+    };
+}
+export function flatten(routeMap) {
+    const routes = [];
+    const parentData = [];
+    function addLevel(level) {
+        level.forEach((route) => {
+            const { path = '', routes: children, ...routeData } = route;
+            const segment = { path, ...routeData };
+            // pathless routes only contribute data to their children — they have
+            // no pattern of their own to match
+            if (path) {
+                routes.push({ pattern: path, data: parentData.concat([segment]) });
+            }
+            if (children) {
+                parentData.push(segment);
+                addLevel(children);
+                parentData.pop();
+            }
+        });
+    }
+    addLevel(routeMap);
+    return routes;
+}
+export function merge(curr, to) {
+    const c = (curr || {});
+    const pathname = to.pathname || c.pattern || c.pathname;
+    const params = Object.assign({}, c.params, to.params);
+    const query = to.query === null ? null : Object.assign({}, c.query, to.query);
+    const hash = to.hash === null ? null : to.hash || c.hash || '';
+    return { pathname, params, query, hash };
+}

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "space-router",
   "description": "All the routing essentials.",
-  "version": "0.9.5",
-  "main": "dist/cjs",
-  "module": "dist/esm",
-  "license": "ICS",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "ISC",
+  "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git://github.com/KidkArolis/space-router.git"
@@ -20,36 +33,30 @@
     "url"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "author": "Karolis Narkevicius",
   "scripts": {
-    "test": "npm run build && oxlint -c oxlintrc.json && prettier --check '**/*.{js,css,yml}' && c8 ava",
-    "format": "prettier --write '**/*.{js,css,yml}'",
+    "test": "npm run build && oxlint -c oxlintrc.json && oxfmt --check '**/*.{ts,js,css,yml}' && c8 ava",
+    "format": "oxfmt --write '**/*.{ts,js,css,yml}'",
     "coverage": "c8 --reporter=html ava",
-    "build": "node ./tasks/build.js",
-    "watch": "node ./tasks/build.js -w",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "watch": "tsc -p tsconfig.build.json --watch",
     "release": "np --no-release-draft",
     "release:beta": "np --tag=beta --no-release-draft",
     "release:docs": "hugo -s docs && gh-pages -d docs/public"
   },
   "devDependencies": {
-    "@swc-node/register": "^1.11.1",
-    "@swc/cli": "^0.8.0",
-    "@swc/core": "^1.15.13",
-    "ava": "^6.4.1",
+    "ava": "^8.0.1",
     "c8": "^11.0.0",
-    "execa": "^9.6.1",
     "gh-pages": "^6.3.0",
-    "oxlint": "^1.50.0",
-    "prettier": "^3.8.1"
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "typescript": "^6.0.3"
   },
   "ava": {
-    "require": [
-      "@swc-node/register"
+    "extensions": [
+      "ts"
     ]
-  },
-  "overrides": {
-    "minimatch": ">=10.2.1"
   }
 }

package/src/history.ts

@@ -0,0 +1,116 @@
+export type Mode = 'history' | 'hash' | 'memory'
+
+export interface History {
+  listen(onChange: (url: string) => void): () => void
+  getUrl(): string
+  push(url: string): void
+  replace(url: string): void
+}
+
+export interface CreateHistoryOptions {
+  mode?: Mode
+  sync?: boolean
+}
+
+export function createHistory(options: CreateHistoryOptions = {}): History {
+  const sync = !!options.sync
+  let mode: Mode = options.mode || 'history'
+  let listener: ((url: string) => void) | null = null
+  let pending = false
+
+  const memory: string[] = []
+
+  if (typeof window === 'undefined') {
+    mode = 'memory'
+  }
+
+  function emit() {
+    if (listener) listener(getUrl())
+  }
+
+  function schedule() {
+    if (sync) return emit()
+    if (pending) return
+    pending = true
+    queueMicrotask(() => {
+      pending = false
+      emit()
+    })
+  }
+
+  function listen(onChange: (url: string) => void) {
+    if (listener) throw new Error('Already listening')
+    listener = onChange
+    let off: (() => void) | undefined
+    if (mode !== 'memory') {
+      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', schedule)
+      schedule()
+    }
+    return () => {
+      listener = null
+      if (off) off()
+    }
+  }
+
+  function go(url: string, replace?: boolean) {
+    url = url.replace(/^\/?#?\/?/, '/').replace(/\/$/, '') || '/'
+    if (mode === 'history') {
+      history[replace ? 'replaceState' : 'pushState']({}, '', url)
+      schedule()
+    } else if (mode === 'hash') {
+      // hashchange only fires when the URL actually changes; if it doesn't,
+      // we schedule the emit manually so navigation stays consistent with
+      // history mode (where pushState is silent and we always schedule).
+      const same = url === getUrl()
+      location[replace ? 'replace' : 'assign']('#' + url)
+      if (same) schedule()
+    } else if (mode === 'memory') {
+      if (replace && memory.length) {
+        memory[memory.length - 1] = url
+      } else {
+        memory.push(url)
+      }
+      schedule()
+    }
+  }
+
+  function getUrl(): string {
+    if (mode === 'memory') {
+      return memory[memory.length - 1] ?? ''
+    }
+
+    const hash = getHash()
+    if (mode === 'hash') {
+      return hash === '' ? '/' : hash
+    }
+
+    let url = location.pathname + location.search
+    if (hash !== '') {
+      url += '#' + hash
+    }
+
+    return url
+  }
+
+  function getHash() {
+    return location.hash.slice(1)
+  }
+
+  return {
+    listen,
+    getUrl,
+    push(url) {
+      go(url)
+    },
+    replace(url) {
+      go(url, true)
+    },
+  }
+}
+
+function on(el: Window, type: string, fn: () => void) {
+  el.addEventListener(type, fn, false)
+  return function off() {
+    el.removeEventListener(type, fn, false)
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { qs } from './qs.ts'
+export { createHistory } from './history.ts'
+export { createMatcher, createRouter, merge } from './router.ts'
+
+export type { Qs } from './qs.ts'
+export type { Mode, History, CreateHistoryOptions } from './history.ts'
+export type {
+  MatcherOptions,
+  RouteData,
+  RouterOptions,
+  Route,
+  NavigateTarget,
+  To,
+  Redirect,
+  RouteDefinition,
+  Matcher,
+  Router,
+} from './router.ts'