@esportsplus/routing 0.6.0

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+end_of_line = lf

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/dependabot.yml

@@ -0,0 +1,25 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+
+registries:
+  npm-npmjs:
+    token: ${{secrets.NPM_TOKEN}}
+    type: npm-registry
+    url: https://registry.npmjs.org
+
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    groups:
+      production-dependencies:
+        dependency-type: "production"
+      development-dependencies:
+        dependency-type: "development"
+    registries:
+      - npm-npmjs
+    schedule:
+      interval: "daily"

package/.github/workflows/bump.yml

@@ -0,0 +1,9 @@
+name: bump version
+
+on:
+  push:
+    branches: '**' # only trigger on branches, not on tags
+
+jobs:
+  bump:
+    uses: esportsplus/typescript/.github/workflows/bump.yml@main

package/.github/workflows/dependabot.yml

@@ -0,0 +1,12 @@
+name: dependabot automerge
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled]
+  workflow_dispatch:
+
+jobs:
+  automerge:
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/typescript/.github/workflows/dependabot.yml@main

package/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+  workflow_run:
+    workflows: [bump version]
+    types:
+      - completed
+
+jobs:
+  publish:
+    secrets:
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    uses: esportsplus/typescript/.github/workflows/publish.yml@main

package/README.md

@@ -0,0 +1,217 @@
+# @esportsplus/routing
+
+Type-safe client-side router with radix tree matching, middleware pipelines, and reactive navigation.
+
+## Install
+
+```bash
+pnpm add @esportsplus/routing
+```
+
+## Features
+
+- Type-safe route names and path parameters
+- Radix tree matching (static > params > wildcards)
+- Composable middleware pipeline
+- Reactive navigation via `@esportsplus/reactivity`
+- Named routes with URI generation
+- Route factories for modular definitions
+- Subdomain routing
+- HTTP method routing (GET, POST, PUT, DELETE)
+
+## Usage
+
+### Define Routes
+
+```typescript
+import { router, Middleware, Next, Request, Route, RouteFactory } from '@esportsplus/routing/client';
+
+type Response = HTMLElement;
+
+// Route factory for modular definitions
+const homeRoutes: RouteFactory<Response> = (r) => r
+    .get({
+        name: 'home',
+        path: '/',
+        responder: (req) => renderHome()
+    })
+    .get({
+        name: 'about',
+        path: '/about',
+        responder: (req) => renderAbout()
+    });
+
+const userRoutes: RouteFactory<Response> = (r) => r
+    .get({
+        name: 'user',
+        path: '/users/:id',
+        responder: (req) => renderUser(req.data.parameters?.id)
+    })
+    .get({
+        name: 'user.settings',
+        path: '/users/:id/settings',
+        middleware: [authMiddleware],
+        responder: (req) => renderSettings(req.data.parameters?.id)
+    });
+```
+
+### Create Router
+
+```typescript
+// Compose route factories
+const app = router(homeRoutes, userRoutes);
+
+// Navigate
+app.redirect('home');
+app.redirect('user', { id: 123 });
+
+// Generate URIs
+app.uri('user', { id: 456 }); // '#/users/456'
+
+// History navigation
+app.back();
+app.forward();
+```
+
+### Middleware
+
+```typescript
+const authMiddleware: Middleware<Response> = (req, next) => {
+    if (!isAuthenticated()) {
+        return renderLogin();
+    }
+    return next(req);
+};
+
+const loggerMiddleware: Middleware<Response> = (req, next) => {
+    console.log(`${req.method} ${req.path}`);
+    return next(req);
+};
+
+// Apply global middleware and dispatch
+app.middleware(loggerMiddleware).dispatch;
+```
+
+### Reactive Matching
+
+```typescript
+// Create fallback route
+const notFound: Route<Response> = {
+    name: 'not-found',
+    path: null,
+    pipeline: pipeline<Request<Response>, Response>(),
+    subdomain: null
+};
+
+// Middleware that reactively matches routes
+const matchMiddleware = app.middleware.match(notFound);
+
+// Compose and dispatch
+app.middleware(matchMiddleware, loggerMiddleware).dispatch;
+```
+
+### Route Groups
+
+```typescript
+const apiRoutes: RouteFactory<Response> = (r) => r
+    .group({
+        path: '/api/v1',
+        middleware: [apiAuth]
+    })
+    .routes((r) => r
+        .get({
+            name: 'api.users',
+            path: '/users',
+            responder: handleUsers
+        })
+        .post({
+            name: 'api.users.create',
+            path: '/users',
+            responder: handleCreateUser
+        })
+    );
+```
+
+### Path Parameters
+
+```typescript
+// Required parameter
+.get({ name: 'user', path: '/users/:id', responder })
+
+// Optional parameter (prefix with ?)
+.get({ name: 'archive', path: '/posts/?:year/?:month', responder })
+
+// Wildcard (captures rest of path)
+.get({ name: 'files', path: '/files/*:path', responder })
+```
+
+### Subdomain Routing
+
+```typescript
+const adminRoutes: RouteFactory<Response> = (r) => r
+    .get({
+        name: 'admin.dashboard',
+        path: '/dashboard',
+        subdomain: 'admin',
+        responder: renderAdminDashboard
+    });
+```
+
+## Types
+
+```typescript
+// Route factory function
+type RouteFactory<T> = (router: Router<T, any>) => Router<T, RouteRegistry>;
+
+// Middleware function
+type Middleware<T> = (input: Request<T>, next: Next<T>) => T;
+
+// Next function in middleware chain
+type Next<T> = (input: Request<T>) => T;
+
+// Request object
+type Request<T> = {
+    data: Record<PropertyKey, unknown> & { parameters?: Record<string, unknown>; route?: Route<T> };
+    hostname: string;
+    href: string;
+    method: string;
+    origin: string;
+    path: string;
+    port: string;
+    protocol: string;
+    query: Record<string, unknown>;
+    subdomain?: string;
+};
+
+// Route definition
+type Route<T> = {
+    name: string | null;
+    path: string | null;
+    pipeline: Pipeline<Request<T>, T>;
+    subdomain: string | null;
+};
+```
+
+## Route Matching Priority
+
+1. **Static paths** - exact match (`/users`)
+2. **Parameters** - dynamic segments (`/users/:id`)
+3. **Wildcards** - catch-all (`/files/*:path`)
+
+Static paths always take precedence over parameterized paths for the same position.
+
+## Hash-Based Navigation
+
+Routes use hash-based URLs (`#/path`) for client-side navigation without server configuration.
+
+```typescript
+// URL: https://example.com/#/users/123?tab=profile
+
+request.path     // '/users/123'
+request.query    // { tab: 'profile' }
+request.hostname // 'example.com'
+```
+
+## License
+
+MIT

package/build/client/constants.d.ts

@@ -0,0 +1,9 @@
+declare const ON_DELETE: string[];
+declare const ON_GET: string[];
+declare const ON_POST: string[];
+declare const ON_PUT: string[];
+declare const PARAMETER = 0;
+declare const STATIC = 1;
+declare const WILDCARD = 2;
+export { ON_DELETE, ON_GET, ON_POST, ON_PUT, PARAMETER, STATIC, WILDCARD };
+export { PACKAGE_NAME } from '../constants.js';

package/build/client/constants.js

@@ -0,0 +1,9 @@
+const ON_DELETE = ['DELETE'];
+const ON_GET = ['GET'];
+const ON_POST = ['POST'];
+const ON_PUT = ['PUT'];
+const PARAMETER = 0;
+const STATIC = 1;
+const WILDCARD = 2;
+export { ON_DELETE, ON_GET, ON_POST, ON_PUT, PARAMETER, STATIC, WILDCARD };
+export { PACKAGE_NAME } from '../constants.js';

package/build/client/index.d.ts

@@ -0,0 +1,17 @@
+import { AccumulateRoutes, ExtractOptionalParams, ExtractRequiredParams, InferOutput, Middleware, Next, PathParamsObject, Request, Route, RouteFactory, RoutePath } from './types.js';
+declare function back(): void;
+declare function forward(): void;
+declare const router: <const Factories extends readonly RouteFactory<any>[]>(...factories: Factories) => {
+    back: typeof back;
+    forward: typeof forward;
+    middleware: {
+        (...stages: Middleware<InferOutput<Factories[number]>>[]): InferOutput<Factories[number]>;
+        dispatch(request: Request<InferOutput<Factories[number]>>): InferOutput<Factories[number]>;
+        match(fallback: Route<InferOutput<Factories[number]>>): (request: Request<InferOutput<Factories[number]>>, next: Next<InferOutput<Factories[number]>>) => InferOutput<Factories[number]>;
+    };
+    redirect: <RouteName extends keyof AccumulateRoutes<Factories>>(name: RouteName, ...values: ExtractRequiredParams<RoutePath<AccumulateRoutes<Factories>, RouteName>> extends never ? ExtractOptionalParams<RoutePath<AccumulateRoutes<Factories>, RouteName>> extends never ? [] : [params?: PathParamsObject<RoutePath<AccumulateRoutes<Factories>, RouteName>>] : [params: PathParamsObject<RoutePath<AccumulateRoutes<Factories>, RouteName>>]) => void;
+    routes: Record<string, Route<InferOutput<Factories[number]>>>;
+    uri: <RouteName extends keyof AccumulateRoutes<Factories>>(name: RouteName, ...values: ExtractRequiredParams<RoutePath<AccumulateRoutes<Factories>, RouteName>> extends never ? ExtractOptionalParams<RoutePath<AccumulateRoutes<Factories>, RouteName>> extends never ? [] : [params?: PathParamsObject<RoutePath<AccumulateRoutes<Factories>, RouteName>>] : [params: PathParamsObject<RoutePath<AccumulateRoutes<Factories>, RouteName>>]) => string;
+};
+export { router };
+export type { Middleware, Next, Request, Route, RouteFactory } from './types.js';

package/build/client/index.js

@@ -0,0 +1,143 @@
+import * as reactivity_fa31f85817714b2e94bba1bba5e367420 from '@esportsplus/reactivity';
+import { effect, root } from '@esportsplus/reactivity';
+import { Router } from './router/index.js';
+import pipeline from '@esportsplus/pipeline';
+import { PACKAGE_NAME } from './constants.js';
+class ReactiveObject_fa31f85817714b2e94bba1bba5e367421 extends reactivity_fa31f85817714b2e94bba1bba5e367420.ReactiveObject {
+    #parameters;
+    #route;
+    constructor(_p0, _p1) {
+        super(null);
+        this.#parameters = this[reactivity_fa31f85817714b2e94bba1bba5e367420.SIGNAL](_p0);
+        this.#route = this[reactivity_fa31f85817714b2e94bba1bba5e367420.SIGNAL](_p1);
+    }
+    get parameters() {
+        return reactivity_fa31f85817714b2e94bba1bba5e367420.read(this.#parameters);
+    }
+    set parameters(_v0) {
+        reactivity_fa31f85817714b2e94bba1bba5e367420.write(this.#parameters, _v0);
+    }
+    get route() {
+        return reactivity_fa31f85817714b2e94bba1bba5e367420.read(this.#route);
+    }
+    set route(_v1) {
+        reactivity_fa31f85817714b2e94bba1bba5e367420.write(this.#route, _v1);
+    }
+}
+let cache = [], location = window.location;
+function back() {
+    window.history.back();
+}
+function forward() {
+    window.history.forward();
+}
+function href() {
+    let hash = location.hash || '#/', path = hash ? hash.slice(1).split('?') : ['/', ''], request = {
+        hostname: location.hostname,
+        href: location.href,
+        method: 'GET',
+        origin: location.origin,
+        path: path[0],
+        port: location.port,
+        protocol: location.protocol,
+        query: {}
+    };
+    if (path[1]) {
+        let params = new URLSearchParams(path[1]), query = request.query;
+        for (let [key, value] of params.entries()) {
+            query[key] = value;
+        }
+    }
+    return request;
+}
+function match(request, router, subdomain) {
+    if (router.subdomains !== null) {
+        let hostname = request.hostname, subdomains = router.subdomains;
+        for (let i = 0, n = subdomains.length; i < n; i++) {
+            if (!hostname.startsWith(subdomains[i])) {
+                continue;
+            }
+            subdomain = subdomains[i];
+            break;
+        }
+    }
+    return router.match(request.method, request.path, subdomain || '');
+}
+function middleware(request, router) {
+    let middleware = pipeline();
+    function host(...stages) {
+        for (let i = 0, n = stages.length; i < n; i++) {
+            middleware.add(stages[i]);
+        }
+        return middleware.dispatch(request);
+    }
+    ;
+    host.dispatch = (request) => {
+        let { route } = request.data;
+        if (route === undefined) {
+            throw new Error(`${PACKAGE_NAME}: route is undefined!`);
+        }
+        return route.pipeline.dispatch(request);
+    };
+    host.match = (fallback) => {
+        let state = new ReactiveObject_fa31f85817714b2e94bba1bba5e367421(undefined, undefined);
+        if (fallback === undefined) {
+            throw new Error(`${PACKAGE_NAME}: fallback route does not exist`);
+        }
+        effect(() => {
+            let { parameters, route } = match(request, router);
+            state.parameters = parameters;
+            state.route = route || fallback;
+        });
+        return (request, next) => {
+            if (state.route === undefined) {
+                throw new Error(`${PACKAGE_NAME}: route is undefined`);
+            }
+            return root(() => {
+                request.data = {
+                    parameters: state.parameters,
+                    route: state.route
+                };
+                return next(request);
+            });
+        };
+    };
+    return host;
+}
+function normalize(uri) {
+    if (uri[0] === '/') {
+        return '#' + uri;
+    }
+    return uri;
+}
+function onpopstate() {
+    let values = href();
+    for (let i = 0, n = cache.length; i < n; i++) {
+        let state = cache[i];
+        for (let key in values) {
+            state[key] = values[key];
+        }
+    }
+}
+const router = (...factories) => {
+    let instance = factories.reduce((r, factory) => factory(r), new Router()), request = reactivity_fa31f85817714b2e94bba1bba5e367420.reactive(Object.assign(href(), { data: {} }));
+    if (cache.push(request) === 1) {
+        window.addEventListener('hashchange', onpopstate);
+    }
+    return {
+        back,
+        forward,
+        middleware: middleware(request, instance),
+        redirect: (name, ...values) => {
+            if (name.indexOf('://') !== -1) {
+                return window.location.replace(name);
+            }
+            window.location.hash = normalize(instance.uri(name, values));
+        },
+        routes: instance.routes,
+        uri: (name, ...values) => {
+            return normalize(instance.uri(name, values));
+        }
+    };
+};
+export { router };

package/build/client/router/index.d.ts

@@ -0,0 +1,64 @@
+import { Route, Name, Options, PathParamsTuple, RouteOptions, RouteRegistry } from '../types.js';
+import { Node } from './node.js';
+declare function key(method: string, subdomain?: string | null): string;
+declare class Router<T, TRoutes extends RouteRegistry = {}> {
+    bucket: Record<ReturnType<typeof key>, {
+        root: Node<T>;
+        static: Record<string, Route<T>>;
+    }>;
+    groups: Options<T>[];
+    routes: Record<Name, Route<T>>;
+    subdomains: string[] | null;
+    private add;
+    private create;
+    delete<RouteName extends string = string, RoutePath extends string = string>(options: RouteOptions<T> & {
+        name?: RouteName;
+        path?: RoutePath;
+    }): Router<T, TRoutes & (RouteName extends string ? RoutePath extends string ? {
+        [K in RouteName]: {
+            path: RoutePath;
+        };
+    } : TRoutes : TRoutes)>;
+    get<RouteName extends string = string, RoutePath extends string = string>(options: RouteOptions<T> & {
+        name?: RouteName;
+        path?: RoutePath;
+    }): Router<T, TRoutes & (RouteName extends string ? RoutePath extends string ? {
+        [K in RouteName]: {
+            path: RoutePath;
+        };
+    } : TRoutes : TRoutes)>;
+    group(options: Options<T>): {
+        routes: (fn: (router: Router<T, TRoutes>) => void) => Router<T, TRoutes>;
+    };
+    match(method: string, path: string, subdomain?: string | null): {
+        parameters?: Readonly<Record<PropertyKey, unknown>>;
+        route?: Readonly<Route<T>> | undefined;
+    };
+    on<RouteName extends string = string, RoutePath extends string = string>(methods: string[], options: RouteOptions<T> & {
+        name?: RouteName;
+        path?: RoutePath;
+    }): Router<T, TRoutes & (RouteName extends string ? RoutePath extends string ? {
+        [K in RouteName]: {
+            path: RoutePath;
+        };
+    } : TRoutes : TRoutes)>;
+    post<RouteName extends string = string, RoutePath extends string = string>(options: RouteOptions<T> & {
+        name?: RouteName;
+        path?: RoutePath;
+    }): Router<T, TRoutes & (RouteName extends string ? RoutePath extends string ? {
+        [K in RouteName]: {
+            path: RoutePath;
+        };
+    } : TRoutes : TRoutes)>;
+    put<RouteName extends string = string, RoutePath extends string = string>(options: RouteOptions<T> & {
+        name?: RouteName;
+        path?: RoutePath;
+    }): Router<T, TRoutes & (RouteName extends string ? RoutePath extends string ? {
+        [K in RouteName]: {
+            path: RoutePath;
+        };
+    } : TRoutes : TRoutes)>;
+    uri<RouteName extends keyof TRoutes & string>(name: RouteName, values?: PathParamsTuple<TRoutes[RouteName]['path']>): string;
+}
+export { Router };
+export type { Route };