workstar-router 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workstar Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# Workstar Router
+
+An experimental isomorphic URL matcher for Workstar applications. It has no DOM dependency and does not intercept links. The same route manifest can choose a server-rendered page and build browser links.
+
+```ts
+import { createRouter } from 'workstar-router';
+
+const router = createRouter([
+  {
+    name: 'home',
+    path: '/:locale?',
+    validate: { locale: (value) => ['en', 'de'].includes(value) },
+  },
+  { name: 'service', path: '/:locale?/services/:service' },
+] as const);
+
+router.match('/de/services/audit');
+router.href('service', { locale: 'de', service: 'audit' });
+```
+
+Static segments rank ahead of parameters. Optional parameters use `:name?`; final rest parameters use `*name`. Path parameters are decoded safely and link parameters are encoded. Native `<a href>` navigation remains the default, preserving server rendering and no-JavaScript behavior.
+Use `validate` for constrained parameters such as supported locales; otherwise any non-empty segment is accepted.
+
+This is not yet a client-side navigation system or a server framework. Request handling, data loading, form submissions, and page metadata belong to the application layer. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export interface RouteDefinition<Name extends string = string> {
+    readonly name: Name;
+    readonly path: string;
+    readonly validate?: Readonly<Record<string, (value: string) => boolean>>;
+}
+export interface RouteMatch<Name extends string = string> {
+    readonly name: Name;
+    readonly path: string;
+    readonly params: Readonly<Record<string, string>>;
+}
+export declare function createRouter<const Name extends string>(definitions: readonly RouteDefinition<Name>[]): {
+    match(pathname: string): RouteMatch<Name> | null;
+    href(name: Name, params?: Readonly<Record<string, string | undefined>>): string;
+};

package/dist/index.js

@@ -0,0 +1,206 @@
+function splitPath(path, pattern = false) {
+    if (!path.startsWith('/') ||
+        (!pattern && path.includes('?')) ||
+        path.includes('#')) {
+        throw new TypeError('Route paths must be absolute pathnames.');
+    }
+    if (path === '/')
+        return [];
+    if (path.includes('//'))
+        throw new TypeError('Route paths cannot contain empty segments.');
+    return path.replace(/\/$/, '').slice(1).split('/');
+}
+function compile(definition) {
+    const names = new Set();
+    const segments = splitPath(definition.path, true).map((part, index, parts) => {
+        const parameter = /^:([A-Za-z][A-Za-z0-9_]*)(\?)?$/.exec(part);
+        const rest = /^\*([A-Za-z][A-Za-z0-9_]*)$/.exec(part);
+        if (parameter || rest) {
+            const name = (parameter ?? rest)?.[1];
+            if (!name || names.has(name))
+                throw new TypeError('Duplicate or invalid route parameter.');
+            names.add(name);
+            if (rest) {
+                if (index !== parts.length - 1)
+                    throw new TypeError('Rest parameter must be final.');
+                return { kind: 'rest', name };
+            }
+            return { kind: 'parameter', name, optional: Boolean(parameter?.[2]) };
+        }
+        if (part.startsWith(':') ||
+            part.startsWith('*') ||
+            !/^[A-Za-z0-9._~-]+$/.test(part)) {
+            throw new TypeError(`Invalid static route segment: ${part}`);
+        }
+        return { kind: 'static', value: part };
+    });
+    const shape = segments
+        .map((segment) => segment.kind === 'static'
+        ? `s:${segment.value}`
+        : segment.kind === 'rest'
+            ? '*'
+            : segment.optional
+                ? ':?'
+                : ':')
+        .join('/');
+    for (const name of Object.keys(definition.validate ?? {})) {
+        if (!names.has(name))
+            throw new TypeError(`Unknown route validator ${name}.`);
+    }
+    return { definition, segments, shape };
+}
+function specificity(segment) {
+    if (!segment)
+        return 2.5;
+    if (segment.kind === 'static')
+        return 4;
+    if (segment.kind === 'rest')
+        return 1;
+    return segment.optional ? 2 : 3;
+}
+function compareRoutes(left, right) {
+    const length = Math.max(left.segments.length, right.segments.length);
+    for (let index = 0; index < length; index++) {
+        const difference = specificity(right.segments[index]) - specificity(left.segments[index]);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function validParameters(route, params) {
+    for (const [name, isValid] of Object.entries(route.definition.validate ?? {})) {
+        const value = params[name];
+        if (value !== undefined && !isValid(value))
+            return false;
+    }
+    return true;
+}
+function decodePath(pathname) {
+    let parts;
+    try {
+        parts = splitPath(pathname);
+    }
+    catch {
+        return null;
+    }
+    try {
+        return parts.map((part) => {
+            const decoded = decodeURIComponent(part);
+            if (decoded === '.' ||
+                decoded === '..' ||
+                /[\/\\\u0000-\u001f]/.test(decoded)) {
+                throw new TypeError('Unsafe pathname segment.');
+            }
+            return decoded;
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function matchSegments(pattern, pathname, patternIndex, pathIndex, params) {
+    if (patternIndex === pattern.length)
+        return pathIndex === pathname.length ? params : null;
+    const segment = pattern[patternIndex];
+    if (!segment)
+        return null;
+    if (segment.kind === 'rest') {
+        if (pathIndex === pathname.length)
+            return null;
+        return { ...params, [segment.name]: pathname.slice(pathIndex).join('/') };
+    }
+    const current = pathname[pathIndex];
+    if (segment.kind === 'static') {
+        return current === segment.value
+            ? matchSegments(pattern, pathname, patternIndex + 1, pathIndex + 1, params)
+            : null;
+    }
+    if (current !== undefined) {
+        const consumed = matchSegments(pattern, pathname, patternIndex + 1, pathIndex + 1, {
+            ...params,
+            [segment.name]: current,
+        });
+        if (consumed)
+            return consumed;
+    }
+    return segment.optional
+        ? matchSegments(pattern, pathname, patternIndex + 1, pathIndex, params)
+        : null;
+}
+function encodeParameter(value, name) {
+    if (!value ||
+        value === '.' ||
+        value === '..' ||
+        /[\/\\\u0000-\u001f]/.test(value)) {
+        throw new TypeError(`Invalid value for route parameter ${name}.`);
+    }
+    return encodeURIComponent(value);
+}
+export function createRouter(definitions) {
+    const routes = definitions.map(compile);
+    const names = new Set();
+    const shapes = new Set();
+    for (const route of routes) {
+        if (names.has(route.definition.name) || shapes.has(route.shape)) {
+            throw new TypeError('Duplicate route name or path pattern.');
+        }
+        names.add(route.definition.name);
+        shapes.add(route.shape);
+    }
+    const ranked = [...routes].sort(compareRoutes);
+    return {
+        match(pathname) {
+            const parts = decodePath(pathname);
+            if (!parts)
+                return null;
+            for (const route of ranked) {
+                const params = matchSegments(route.segments, parts, 0, 0, {});
+                if (params && validParameters(route, params)) {
+                    return {
+                        name: route.definition.name,
+                        path: route.definition.path,
+                        params: Object.freeze(params),
+                    };
+                }
+            }
+            return null;
+        },
+        href(name, params = {}) {
+            const route = routes.find((candidate) => candidate.definition.name === name);
+            if (!route)
+                throw new TypeError(`Unknown route: ${name}`);
+            const used = new Set();
+            const parts = [];
+            for (const segment of route.segments) {
+                if (segment.kind === 'static') {
+                    parts.push(segment.value);
+                    continue;
+                }
+                used.add(segment.name);
+                const value = params[segment.name];
+                if (value === undefined &&
+                    segment.kind === 'parameter' &&
+                    segment.optional)
+                    continue;
+                if (value === undefined)
+                    throw new TypeError(`Missing route parameter ${segment.name}.`);
+                if (segment.kind === 'rest') {
+                    parts.push(...value
+                        .split('/')
+                        .map((part) => encodeParameter(part, segment.name)));
+                }
+                else {
+                    parts.push(encodeParameter(value, segment.name));
+                }
+            }
+            for (const key of Object.keys(params)) {
+                if (!used.has(key))
+                    throw new TypeError(`Unexpected route parameter ${key}.`);
+            }
+            if (!validParameters(route, params)) {
+                throw new TypeError('Route parameter failed validation.');
+            }
+            return parts.length ? `/${parts.join('/')}` : '/';
+        },
+    };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "workstar-router",
+  "version": "0.1.0-alpha.0",
+  "description": "A small isomorphic URL matcher for Workstar applications.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wslab-ai/workstar.git",
+    "directory": "packages/router"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}