@zenithbuild/router 0.6.6 → 0.6.9

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+type RouteParams = Record<string, string>;
+type RouteChangeDetail = {
+    path: string;
+    params?: RouteParams;
+    matched: boolean;
+};
+type RouteProtectionPolicy = {
+    beforeResolve?: boolean;
+    emitRedirects?: boolean;
+};
+type RouteEventHandler = (payload: unknown) => void;
+export declare function onRouteChange(callback: (detail: RouteChangeDetail) => void): () => void;
+export declare function _dispatchRouteChange(detail: RouteChangeDetail): void;
+export declare function _clearSubscribers(): void;
+export declare function _getSubscriberCount(): number;
+export declare function setRouteProtectionPolicy(policy: RouteProtectionPolicy): void;
+export declare function _getRouteProtectionPolicy(): RouteProtectionPolicy;
+export declare function on(eventName: string, handler: RouteEventHandler): void;
+export declare function off(eventName: string, handler: RouteEventHandler): void;
+export declare function _dispatchRouteEvent(eventName: string, payload: unknown): void;
+export {};

package/dist/events.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// events.js — Zenith Router V0
+// events.ts — Zenith Router V0
 // ---------------------------------------------------------------------------
 // Route change event system.
 //
@@ -7,53 +7,24 @@
 // Returns unsubscribe function.
 // No batching. No queue. Synchronous dispatch.
 // ---------------------------------------------------------------------------
-
-/** @type {Set<(detail: object) => void>} */
-const _subscribers = new Set();
-
-/**
- * Subscribe to route change events.
- *
- * @param {(detail: { path: string, params?: Record<string, string>, matched: boolean }) => void} callback
- * @returns {() => void} unsubscribe
- */
+const subscribers = new Set();
 export function onRouteChange(callback) {
-    _subscribers.add(callback);
-
+    subscribers.add(callback);
     return () => {
-        _subscribers.delete(callback);
+        subscribers.delete(callback);
     };
 }
-
-/**
- * Dispatch a route change to all subscribers.
- *
- * @param {{ path: string, params?: Record<string, string>, matched: boolean }} detail
- */
 export function _dispatchRouteChange(detail) {
-    for (const cb of _subscribers) {
-        cb(detail);
+    for (const callback of subscribers) {
+        callback(detail);
     }
 }
-
-/**
- * Clear all subscribers. Used for testing and teardown.
- */
 export function _clearSubscribers() {
-    _subscribers.clear();
+    subscribers.clear();
 }
-
-/**
- * Get the current subscriber count. Used for leak detection.
- *
- * @returns {number}
- */
 export function _getSubscriberCount() {
-    return _subscribers.size;
+    return subscribers.size;
 }
-
-// --- Route Protection Events & Policy ---
-
 const ROUTE_POLICY_KEY = '__zenith_route_protection_policy';
 const ROUTE_EVENT_LISTENERS_KEY = '__zenith_route_event_listeners';
 const ROUTE_EVENT_NAMES = [
@@ -65,84 +36,61 @@ const ROUTE_EVENT_NAMES = [
     'route:deny',
     'route:redirect'
 ];
-
 function getRouteProtectionScope() {
-    return typeof globalThis === 'object' && globalThis ? globalThis : {};
+    return typeof globalThis === 'object' && globalThis
+        ? globalThis
+        : {};
 }
-
 function ensureRouteProtectionState() {
     const scope = getRouteProtectionScope();
-
     let policy = scope[ROUTE_POLICY_KEY];
     if (!policy || typeof policy !== 'object') {
         policy = {};
         scope[ROUTE_POLICY_KEY] = policy;
     }
-
     let listeners = scope[ROUTE_EVENT_LISTENERS_KEY];
     if (!listeners || typeof listeners !== 'object') {
         listeners = Object.create(null);
         scope[ROUTE_EVENT_LISTENERS_KEY] = listeners;
     }
-
     for (const eventName of ROUTE_EVENT_NAMES) {
         if (!(listeners[eventName] instanceof Set)) {
             listeners[eventName] = new Set();
         }
     }
-
     return { policy, listeners };
 }
-
-/**
- * Configure default behaviors for route protection.
- * @param {import('../index').RouteProtectionPolicy} policy 
- */
 export function setRouteProtectionPolicy(policy) {
     const state = ensureRouteProtectionState();
     state.policy = Object.assign({}, state.policy, policy);
     getRouteProtectionScope()[ROUTE_POLICY_KEY] = state.policy;
 }
-
 export function _getRouteProtectionPolicy() {
     return ensureRouteProtectionState().policy;
 }
-
-/**
- * Listen to route protection lifecycle events.
- * @param {string} eventName 
- * @param {Function} handler 
- */
 export function on(eventName, handler) {
-    const listeners = ensureRouteProtectionState().listeners;
-    if (listeners[eventName] instanceof Set) {
-        listeners[eventName].add(handler);
+    const eventListeners = ensureRouteProtectionState().listeners[eventName];
+    if (eventListeners instanceof Set) {
+        eventListeners.add(handler);
     }
 }
-
-/**
- * Remove a route protection lifecycle event listener.
- * @param {string} eventName 
- * @param {Function} handler 
- */
 export function off(eventName, handler) {
-    const listeners = ensureRouteProtectionState().listeners;
-    if (listeners[eventName] instanceof Set) {
-        listeners[eventName].delete(handler);
+    const eventListeners = ensureRouteProtectionState().listeners[eventName];
+    if (eventListeners instanceof Set) {
+        eventListeners.delete(handler);
     }
 }
-
 export function _dispatchRouteEvent(eventName, payload) {
-    const listeners = ensureRouteProtectionState().listeners[eventName];
-    if (!(listeners instanceof Set)) {
+    const eventListeners = ensureRouteProtectionState().listeners[eventName];
+    if (!(eventListeners instanceof Set)) {
         return;
     }
-
-    for (const handler of listeners) {
+    for (const handler of eventListeners) {
         try {
             handler(payload);
-        } catch (e) {
-            console.error(`[Zenith Router] Error in ${eventName} listener:`, e);
+        }
+        catch (error) {
+            console.error(`[Zenith Router] Error in ${eventName} listener:`, error);
         }
     }
 }

package/dist/history.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Push a new path to the browser history.
+ *
+ * @param {string} path
+ */
+export function push(path: string): void;
+/**
+ * Replace the current path in browser history.
+ *
+ * @param {string} path
+ */
+export function replace(path: string): void;
+/**
+ * Subscribe to popstate (back/forward) events.
+ * Returns an unlisten function.
+ *
+ * @param {(path: string) => void} callback
+ * @returns {() => void} unlisten
+ */
+export function listen(callback: (path: string) => void): () => void;
+/**
+ * Get the current pathname.
+ *
+ * @returns {string}
+ */
+export function current(): string;

package/dist/history.js

@@ -10,13 +10,10 @@
 //
 // No hash routing. No scroll restoration. No batching.
 // ---------------------------------------------------------------------------
-
 /** @type {Set<(path: string) => void>} */
 const _listeners = new Set();
-
 /** @type {boolean} */
 let _listening = false;
-
 /**
  * Internal popstate handler — fires all registered listeners.
  */
@@ -26,16 +23,15 @@ function _onPopState() {
         cb(path);
     }
 }
-
 /**
  * Ensure the global popstate listener is attached (once).
  */
 function _ensureListening() {
-    if (_listening) return;
+    if (_listening)
+        return;
     window.addEventListener('popstate', _onPopState);
     _listening = true;
 }
-
 /**
  * Push a new path to the browser history.
  *
@@ -44,7 +40,6 @@ function _ensureListening() {
 export function push(path) {
     window.location.assign(path);
 }
-
 /**
  * Replace the current path in browser history.
  *
@@ -53,7 +48,6 @@ export function push(path) {
 export function replace(path) {
     window.location.replace(path);
 }
-
 /**
  * Subscribe to popstate (back/forward) events.
  * Returns an unlisten function.
@@ -64,7 +58,6 @@ export function replace(path) {
 export function listen(callback) {
     _ensureListening();
     _listeners.add(callback);
-
     return () => {
         _listeners.delete(callback);
         if (_listeners.size === 0) {
@@ -73,7 +66,6 @@ export function listen(callback) {
         }
     };
 }
-
 /**
  * Get the current pathname.
  *

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createRouter } from "./router.js";
+export { matchRoute } from "./match.js";
+export { navigate, back, forward, getCurrentPath } from "./navigate.js";
+export { onRouteChange, on, off, setRouteProtectionPolicy, _getRouteProtectionPolicy, _dispatchRouteEvent } from "./events.js";

package/dist/index.js

@@ -3,7 +3,6 @@
 // ---------------------------------------------------------------------------
 // Structural navigation exports + route protection policy/event hooks.
 // ---------------------------------------------------------------------------
-
 export { createRouter } from './router.js';
 export { navigate, back, forward, getCurrentPath } from './navigate.js';
 export { onRouteChange, on, off, setRouteProtectionPolicy, _getRouteProtectionPolicy, _dispatchRouteEvent } from './events.js';

package/dist/match.d.ts

@@ -0,0 +1,22 @@
+type RouteParams = Record<string, string>;
+type RouteEntry = {
+    path: string;
+    load: (params: RouteParams) => unknown;
+};
+type MatchResult = {
+    route: RouteEntry;
+    params: RouteParams;
+};
+/**
+ * Match a pathname against a single route definition.
+ */
+export declare function matchPath(routePath: string, pathname: string): {
+    matched: boolean;
+    params: RouteParams;
+};
+/**
+ * Match a pathname against an ordered array of route definitions.
+ * Returns the first match (deterministic, first-match-wins).
+ */
+export declare function matchRoute(routes: RouteEntry[], pathname: string): MatchResult | null;
+export {};

package/dist/match.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// match.js — Zenith Router V0
+// match.ts — Zenith Router V0
 // ---------------------------------------------------------------------------
 // Deterministic path matching engine.
 //
@@ -15,35 +15,20 @@
 //
 // No regex.
 // ---------------------------------------------------------------------------
-
-/**
- * @typedef {{ path: string, load: Function }} RouteEntry
- * @typedef {{ route: RouteEntry, params: Record<string, string> }} MatchResult
- */
-
 /**
  * Match a pathname against a single route definition.
- *
- * @param {string} routePath - The route pattern (e.g. '/users/:id')
- * @param {string} pathname  - The actual URL path (e.g. '/users/42')
- * @returns {{ matched: boolean, params: Record<string, string> }}
  */
 export function matchPath(routePath, pathname) {
-    const routeSegments = _splitPath(routePath);
-    const pathSegments = _splitPath(pathname);
-
+    const routeSegments = splitPath(routePath);
+    const pathSegments = splitPath(pathname);
     const params = {};
     let routeIndex = 0;
     let pathIndex = 0;
-
     while (routeIndex < routeSegments.length) {
-        const routeSeg = routeSegments[routeIndex];
+        const routeSeg = routeSegments[routeIndex] || '';
         if (routeSeg.startsWith('*')) {
-            // Catch-all must be terminal.
             const optionalCatchAll = routeSeg.endsWith('?');
-            const paramName = optionalCatchAll
-                ? routeSeg.slice(1, -1)
-                : routeSeg.slice(1);
+            const paramName = optionalCatchAll ? routeSeg.slice(1, -1) : routeSeg.slice(1);
             if (routeIndex !== routeSegments.length - 1) {
                 return { matched: false, params: {} };
             }
@@ -52,140 +37,97 @@ export function matchPath(routePath, pathname) {
             if (rest.length === 0 && !optionalCatchAll && !rootRequiredCatchAll) {
                 return { matched: false, params: {} };
             }
-            params[paramName] = _normalizeCatchAll(rest);
+            params[paramName] = normalizeCatchAll(rest);
             pathIndex = pathSegments.length;
             routeIndex = routeSegments.length;
             break;
         }
-
         if (pathIndex >= pathSegments.length) {
             return { matched: false, params: {} };
         }
-
-        const pathSeg = pathSegments[pathIndex];
+        const pathSeg = pathSegments[pathIndex] || '';
         if (routeSeg.startsWith(':')) {
-            // Dynamic param — extract value as string
-            const paramName = routeSeg.slice(1);
-            params[paramName] = pathSeg;
-        } else if (routeSeg !== pathSeg) {
-            // Literal mismatch
+            params[routeSeg.slice(1)] = pathSeg;
+        }
+        else if (routeSeg !== pathSeg) {
             return { matched: false, params: {} };
         }
-
         routeIndex += 1;
         pathIndex += 1;
     }
-
     if (routeIndex !== routeSegments.length || pathIndex !== pathSegments.length) {
         return { matched: false, params: {} };
     }
-
     return { matched: true, params };
 }
-
 /**
  * Match a pathname against an ordered array of route definitions.
  * Returns the first match (deterministic, first-match-wins).
- *
- * @param {RouteEntry[]} routes - Ordered route manifest
- * @param {string} pathname     - The URL path to match
- * @returns {MatchResult | null}
  */
 export function matchRoute(routes, pathname) {
-    const ordered = [...routes].sort((a, b) => _compareRouteSpecificity(a.path, b.path));
-    for (let i = 0; i < ordered.length; i++) {
-        const route = ordered[i];
+    const ordered = [...routes].sort((a, b) => compareRouteSpecificity(a.path, b.path));
+    for (const route of ordered) {
         const result = matchPath(route.path, pathname);
-
         if (result.matched) {
             return { route, params: result.params };
         }
     }
-
     return null;
 }
-
-/**
- * Split a path string into non-empty segments.
- *
- * @param {string} path
- * @returns {string[]}
- */
-function _splitPath(path) {
+function splitPath(path) {
     return path.split('/').filter(Boolean);
 }
-
-/**
- * Catch-all params are normalized as slash-joined, non-empty path segments.
- * Segments keep raw URL-encoded bytes (no decodeURIComponent).
- *
- * @param {string[]} segments
- * @returns {string}
- */
-function _normalizeCatchAll(segments) {
+function normalizeCatchAll(segments) {
     return segments.filter(Boolean).join('/');
 }
-
-/**
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function _compareRouteSpecificity(a, b) {
-    if (a === '/' && b !== '/') return -1;
-    if (b === '/' && a !== '/') return 1;
-
-    const aSegs = _splitPath(a);
-    const bSegs = _splitPath(b);
-    const aClass = _routeClass(aSegs);
-    const bClass = _routeClass(bSegs);
+function compareRouteSpecificity(a, b) {
+    if (a === '/' && b !== '/')
+        return -1;
+    if (b === '/' && a !== '/')
+        return 1;
+    const aSegs = splitPath(a);
+    const bSegs = splitPath(b);
+    const aClass = routeClass(aSegs);
+    const bClass = routeClass(bSegs);
     if (aClass !== bClass) {
         return bClass - aClass;
     }
-
     const max = Math.min(aSegs.length, bSegs.length);
-
-    for (let i = 0; i < max; i++) {
-        const aWeight = _segmentWeight(aSegs[i]);
-        const bWeight = _segmentWeight(bSegs[i]);
+    for (let index = 0; index < max; index += 1) {
+        const aWeight = segmentWeight(aSegs[index]);
+        const bWeight = segmentWeight(bSegs[index]);
         if (aWeight !== bWeight) {
             return bWeight - aWeight;
         }
     }
-
     if (aSegs.length !== bSegs.length) {
         return bSegs.length - aSegs.length;
     }
-
     return a.localeCompare(b);
 }
-
-/**
- * @param {string[]} segments
- * @returns {number}
- */
-function _routeClass(segments) {
+function routeClass(segments) {
     let hasParam = false;
     let hasCatchAll = false;
     for (const segment of segments) {
         if (segment.startsWith('*')) {
             hasCatchAll = true;
-        } else if (segment.startsWith(':')) {
+        }
+        else if (segment.startsWith(':')) {
             hasParam = true;
         }
     }
-    if (!hasParam && !hasCatchAll) return 3;
-    if (hasCatchAll) return 1;
+    if (!hasParam && !hasCatchAll)
+        return 3;
+    if (hasCatchAll)
+        return 1;
     return 2;
 }
-
-/**
- * @param {string | undefined} segment
- * @returns {number}
- */
-function _segmentWeight(segment) {
-    if (!segment) return 0;
-    if (segment.startsWith('*')) return 1;
-    if (segment.startsWith(':')) return 2;
+function segmentWeight(segment) {
+    if (!segment)
+        return 0;
+    if (segment.startsWith('*'))
+        return 1;
+    if (segment.startsWith(':'))
+        return 2;
     return 3;
 }

package/dist/navigate.d.ts

@@ -0,0 +1,5 @@
+export declare function _setNavigationResolver(resolver: ((path: string) => Promise<void>) | null): void;
+export declare function navigate(path: string): Promise<void>;
+export declare function back(): void;
+export declare function forward(): void;
+export declare function getCurrentPath(): string;

package/dist/navigate.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// navigate.js — Zenith Router V0
+// navigate.ts — Zenith Router V0
 // ---------------------------------------------------------------------------
 // Navigation API.
 //
@@ -11,57 +11,23 @@
 // The navigate function accepts a resolver callback so the router
 // can wire match → mount logic without circular dependencies.
 // ---------------------------------------------------------------------------
-
-import { push, current } from './history.js';
-import { _dispatchRouteChange } from './events.js';
-
-/** @type {((path: string) => Promise<void>) | null} */
-let _resolveNavigation = null;
-
-/**
- * Wire the navigation resolver.
- * Called once by createRouter() to bind match → mount logic.
- *
- * @param {(path: string) => Promise<void>} resolver
- */
+import { current, push } from './history.js';
+let resolveNavigation = null;
 export function _setNavigationResolver(resolver) {
-    _resolveNavigation = resolver;
+    resolveNavigation = resolver;
 }
-
-/**
- * Navigate to a path.
- * Pushes history, then resolves through the router pipeline.
- *
- * @param {string} path
- * @returns {Promise<void>}
- */
 export async function navigate(path) {
     push(path);
-
-    if (_resolveNavigation) {
-        await _resolveNavigation(path);
+    if (resolveNavigation) {
+        await resolveNavigation(path);
     }
 }
-
-/**
- * Go back in history.
- */
 export function back() {
     history.back();
 }
-
-/**
- * Go forward in history.
- */
 export function forward() {
     history.forward();
 }
-
-/**
- * Get the current pathname.
- *
- * @returns {string}
- */
 export function getCurrentPath() {
     return current();
 }

package/dist/router.d.ts

@@ -0,0 +1,18 @@
+type RouteParams = Record<string, string>;
+type RouteLoader = (params: RouteParams) => unknown | Promise<unknown>;
+type RouteDefinition = {
+    path: string;
+    load: RouteLoader;
+};
+type RouterConfig = {
+    routes: RouteDefinition[];
+    container: HTMLElement;
+    mount?: unknown;
+    cleanup?: unknown;
+};
+type RouterInstance = {
+    start: () => Promise<void>;
+    destroy: () => void;
+};
+export declare function createRouter(config: RouterConfig): RouterInstance;
+export {};

package/dist/router.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// router.js — Zenith Router V0
+// router.ts — Zenith Router V0
 // ---------------------------------------------------------------------------
 // Router assembly: wires match engine + history + runtime mount/unmount.
 //
@@ -11,101 +11,60 @@
 // - Mount/unmount delegated to @zenithbuild/runtime
 // - Deterministic first-match-wins
 // ---------------------------------------------------------------------------
-
-import { matchRoute } from './match.js';
-import { listen, current } from './history.js';
 import { _dispatchRouteChange } from './events.js';
+import { current, listen } from './history.js';
+import { matchRoute } from './match.js';
 import { _setNavigationResolver } from './navigate.js';
-
-/**
- * Create a router instance.
- *
- * @param {{ routes: Array<{ path: string, load: Function }>, container: HTMLElement, mount?: Function, cleanup?: Function }} config
- * @returns {{ start: () => Promise<void>, destroy: () => void }}
- */
 export function createRouter(config) {
     const { routes, container } = config;
-
-    // Allow injecting mount/cleanup for testing without importing runtime
-    const mountFn = config.mount || null;
-    const cleanupFn = config.cleanup || null;
-
+    const mountFn = typeof config.mount === 'function' ? config.mount : null;
+    const cleanupFn = typeof config.cleanup === 'function' ? config.cleanup : null;
     if (!container || !(container instanceof HTMLElement)) {
         throw new Error('[Zenith Router] createRouter() requires an HTMLElement container');
     }
-
     if (!Array.isArray(routes) || routes.length === 0) {
         throw new Error('[Zenith Router] createRouter() requires a non-empty routes array');
     }
-
-    let _unlisten = null;
-    let _started = false;
-    let _hasMounted = false;
-
-    /**
-     * Resolve a path: match → load → mount.
-     *
-     * @param {string} path
-     */
-    async function _resolve(path) {
+    let unlisten = null;
+    let started = false;
+    let hasMounted = false;
+    async function resolvePath(path) {
         const result = matchRoute(routes, path);
-
         if (!result) {
             _dispatchRouteChange({ path, matched: false });
             return;
         }
-
-        // Teardown previous page (only if we've mounted before)
-        if (_hasMounted && cleanupFn) {
+        if (hasMounted && cleanupFn) {
             cleanupFn();
         }
-
-        // Load module
         const pageModule = await result.route.load(result.params);
-
-        // Mount new page
         if (mountFn) {
             mountFn(container, pageModule);
-            _hasMounted = true;
+            hasMounted = true;
         }
-
         _dispatchRouteChange({
             path,
             params: result.params,
             matched: true
         });
     }
-
-    /**
-     * Start the router — match initial route and begin listening.
-     */
     async function start() {
-        if (_started) return;
-        _started = true;
-
-        // Wire navigate() to use our resolver
-        _setNavigationResolver(_resolve);
-
-        // Listen for popstate (back/forward)
-        _unlisten = listen((path) => {
-            _resolve(path);
+        if (started)
+            return;
+        started = true;
+        _setNavigationResolver(resolvePath);
+        unlisten = listen((path) => {
+            void resolvePath(path);
         });
-
-        // Initial route
-        await _resolve(current());
+        await resolvePath(current());
     }
-
-    /**
-     * Tear down the router — remove listeners, clear state.
-     */
     function destroy() {
-        if (_unlisten) {
-            _unlisten();
-            _unlisten = null;
+        if (unlisten) {
+            unlisten();
+            unlisten = null;
         }
         _setNavigationResolver(null);
-        _started = false;
+        started = false;
     }
-
     return { start, destroy };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/router",
-  "version": "0.6.6",
+  "version": "0.6.9",
   "description": "File-based SPA router for Zenith framework with deterministic, compile-time route resolution",
   "license": "MIT",
   "type": "module",
@@ -40,8 +40,8 @@
   "scripts": {
     "format": "prettier --write \"**/*.ts\"",
     "format:check": "prettier --check \"**/*.ts\"",
-    "typecheck": "tsc --noEmit",
-    "build": "mkdir -p dist && cp -a src/* dist/ && cp src/ZenLink.zen dist/ZenLink.zen",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/ZenLink.zen dist/ZenLink.zen",
     "release": "bun run scripts/release.ts",
     "release:dry": "bun run scripts/release.ts --dry-run",
     "release:patch": "bun run scripts/release.ts --bump=patch",
@@ -62,6 +62,7 @@
     "@napi-rs/cli": "^2.18.4",
     "@types/bun": "latest",
     "@types/node": "latest",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "typescript": "^5.7.3"
   }
 }