svelte-navigator-lite 1.1.4 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # svelte-navigator-lite
 
-A lightweight, label-based router for Svelte 5. Define named routes that map to URL patterns, then use `router.route` reactively — not just to show components, but for any logic that depends on where you are.
+A lightweight, pattern-based router for Svelte 5. Routes are defined with familiar URL patterns, guards are reusable named functions, and the reactive `router` singleton integrates directly with Svelte runes.
 
 ## Installation
 
@@ -8,261 +8,159 @@ A lightweight, label-based router for Svelte 5. Define named routes that map to
 npm install svelte-navigator-lite
 ```
 
-## Setup
+## Quick start
 
-Call `createRouter` once at your app's entry point (e.g. `App.svelte`):
-
-```ts
-import { createRouter, router } from 'svelte-navigator-lite';
-import type { RouteList } from 'svelte-navigator-lite';
-
-const routes: RouteList = {
-    'login': {
-        rootPath: 'login',
-        segments: [],
-    },
-    'dashboard': {
-        rootPath: 'dashboard',
-        segments: [],
-    },
-};
-
-createRouter(routes, 'dashboard'); // second argument is the default/fallback route
-```
-
-Then use `router.route` anywhere in your Svelte components — it's a reactive Svelte 5 `$state` value:
+Define your routes and guards, then call `createRouter` on mount.
 
 ```svelte
-{#if router.is('login')}
-    <Login />
-{:else if router.is('dashboard')}
-    <Dashboard />
-{/if}
-```
-
----
-
-## Defining Routes
-
-Every route has a `rootPath` — the first URL segment — and an array of `segments` for everything after it.
-
-### Static routes
-
-```ts
-'login': {
-    rootPath: 'login',  // matches /login
-    segments: [],
-}
-```
-
-### Dynamic params
-
-Use `name` to capture a URL segment into `router.params`:
-
-```ts
-'event': {
-    rootPath: 'event',
-    segments: [{ name: 'eventId' }],  // matches /event/123
-}
-// router.params.eventId === '123'
-```
-
-### Enforced static segments
-
-Use `enforceVal` to require a literal string at that position:
-
-```ts
-'create-calendar': {
-    rootPath: 'calendar',
-    segments: [{ enforceVal: 'create' }],  // matches /calendar/create only
-}
-```
-
-### Mixed segments
-
-`enforceVal` and `name` segments can be combined in any order:
-
-```ts
-'edit-event': {
-    rootPath: 'event',
-    segments: [
-        { name: 'eventId' },        // matches /event/:eventId/edit
-        { enforceVal: 'edit' },
-    ],
-}
-```
-
-### Optional segments
-
-Add `optional: true` to make a trailing segment optional. Optional segments must come after all required segments.
-
-```ts
-'event': {
-    rootPath: 'event',
-    segments: [
-        { name: 'eventId' },
-        { enforceVal: 'edit', optional: true },  // matches /event/123 AND /event/123/edit
-    ],
-}
-```
-
----
-
-## Search Params
-
-Search params are automatically captured into `router.searchParams` when present in the URL. No configuration is needed — they never affect whether a route matches.
-
-```ts
-// /password-reset?token=abc  →  router.searchParams.token === 'abc'
-// /password-reset            →  router.searchParams === {}
-```
-
----
+<!-- App.svelte -->
+<script lang="ts">
+    import { onMount } from 'svelte';
+    import { createRouter, router } from 'svelte-navigator-lite';
+    import { auth } from '$stores/auth.svelte';
+    import AppShell from '$lib/components/AppShell.svelte';
+
+    onMount(() => {
+        createRouter({
+            routes: [
+                { name: 'cal',      pattern: '/cal'                        },
+                { name: 'cal-date', pattern: '/cal/:mm/:dd/:yyyy'          },
+                { name: 'event',    pattern: '/event/:eventId'             },
+                { name: 'edit',     pattern: '/event/:eventId/edit'        },
+                { name: 'login',    pattern: '/login',  guards: ['unauth'] },
+                { name: 'signup',   pattern: '/signup', guards: ['unauth'] },
+            ],
+            guards: {
+                auth:   { condition: () => !auth.isValid(), redirectTo: 'login' },
+                unauth: { condition: () =>  auth.isValid(), redirectTo: 'cal'   },
+            },
+            fallback: 'cal',
+        });
+    });
+</script>
+
+<AppShell />
+```
+
+## Route patterns
+
+Patterns follow standard URL conventions.
+
+| Pattern | Example URL | Params |
+|---|---|---|
+| `/cal` | `/cal` | `{}` |
+| `/event/:eventId` | `/event/abc-123` | `{ eventId: 'abc-123' }` |
+| `/event/:eventId/edit` | `/event/abc-123/edit` | `{ eventId: 'abc-123' }` |
+| `/cal/:mm/:dd/:yyyy` | `/cal/05/13/2026` | `{ mm: '05', dd: '13', yyyy: '2026' }` |
+| `/settings/:page?` | `/settings` or `/settings/account` | `{}` or `{ page: 'account' }` |
+
+Append `?` to a param name to make it optional. Optional params must come at the end of the pattern.
 
 ## Navigating
 
-### `router.navigate(route, params?, searchParams?)`
+```typescript
+import { router } from 'svelte-navigator-lite';
 
-Navigate to a named route. Path params fill dynamic segments; pass search params separately as the third argument.
+// Static route
+router.navigate('login');
 
-```ts
+// With path params
 router.navigate('event', { eventId: '123' });
-// → /event/123
 
-router.navigate('password-reset', undefined, { token: 'abc123' });
-// → /password-reset?token=abc123
-
-router.navigate('event', { eventId: '123' }, { tab: 'details' });
-// → /event/123?tab=details
+// With path params + search params
+router.navigate('edit', { eventId: '123' }, { from: 'calendar' });
 ```
 
-Throws if a required param is missing.
+`navigate` returns a `Promise<void>`. Guards are evaluated before navigation — if a guard fires, the router redirects instead and original params are not forwarded.
 
-### `goto(path)`
+## Reading state
 
-Lower-level navigation to a raw path. Accepts an optional `{ replaceState: true }` option to replace instead of push.
+```typescript
+import { router } from 'svelte-navigator-lite';
 
-```ts
-import { goto } from 'svelte-navigator-lite';
+router.route        // current route name: string
+router.params       // path params: Record<string, string>
+router.searchParams // query params: Record<string, string>
+router.notFound     // true if the URL matched no route and the fallback was used
 
-goto('/login');
-goto('/login', { replaceState: true });
+router.is('cal')              // true if current route === 'cal'
+router.matches(['cal', 'event']) // true if current route is in the list
 ```
 
----
+All properties are reactive — use them in Svelte templates or `$effect` blocks and they update automatically on navigation.
 
-## Route Guards
+## Guards
 
-Guards run before navigation and redirect if their condition is met. `fn` returning `true` triggers the redirect.
+Guards are defined once in `createRouter` and referenced by name in route definitions.
 
-```ts
-import type { RouteGuard } from 'svelte-navigator-lite';
-
-const guards = {
-    authenticated: {
-        fn: () => !auth.isValid(),   // redirect if NOT authenticated
-        redirectTo: 'login',
-    } satisfies RouteGuard,
-    unauthenticated: {
-        fn: () => auth.isValid(),    // redirect if already authenticated
-        redirectTo: 'dashboard',
-    } satisfies RouteGuard,
-};
-
-const routes: RouteList = {
-    'login': {
-        rootPath: 'login',
-        segments: [],
-        routeGuards: [guards.unauthenticated],
-    },
-    'dashboard': {
-        rootPath: 'dashboard',
-        segments: [],
-        routeGuards: [guards.authenticated],
+```typescript
+createRouter({
+    routes: [
+        { name: 'cal',          pattern: '/cal',          guards: ['auth']  },
+        { name: 'login',        pattern: '/login',        guards: ['unauth'] },
+        { name: 'verify-email', pattern: '/verify-email', guards: ['unauth'] },
+        { name: 'login-check',  pattern: '/login',        guards: ['unauth', 'emailCheck'] },
+    ],
+    guards: {
+        auth: {
+            condition: () => !auth.isValid(),
+            redirectTo: 'login',
+        },
+        unauth: {
+            condition: () => auth.isValid(),
+            redirectTo: 'cal',
+        },
+        emailCheck: {
+            condition: () => auth.containsCreds() && !auth.user?.verified,
+            redirectTo: 'verify-email',
+        },
     },
-};
+    fallback: 'cal',
+});
 ```
 
-Guards run in order and stop at the first redirect.
-
----
-
-## API Reference
-
-### `createRouter(routes, defaultRoute)`
-
-Registers all routes and sets the fallback route. Parses the current URL immediately. Must be called once before using `router`.
-
-### `router.route`
+**`condition`** — called before entering the route. Return `true` to trigger the redirect.
 
-The label of the currently matched route. Falls back to `defaultRoute` if no route matches.
+**`redirectTo`** — route name to navigate to instead.
 
-### `router.params`
+Multiple guards on a route are checked in order; the first one that fires wins. Guard redirects are also checked for guards (recursively), with cycle detection to prevent infinite loops.
 
-An object containing the captured path param values for the current route.
+## `page` store
 
-### `router.searchParams`
+A Svelte readable store that emits `{ url: URL }` on every navigation. Compatible with SvelteKit's `$app/stores` page store shape.
 
-An object containing the search params present in the current URL. Empty object when none are present.
-
-### `router.notFound`
-
-`true` when the current URL did not match any defined route and the router fell back to `defaultRoute`. Use this to render a 404 state without needing a dedicated catch-all route.
+```typescript
+import { page } from 'svelte-navigator-lite';
 
-```svelte
-{#if router.notFound}
-    <NotFound />
-{:else if router.is('dashboard')}
-    <Dashboard />
-{/if}
+page.subscribe(({ url }) => {
+    console.log(url.pathname);
+});
 ```
 
-### `router.navigate(route, params?, searchParams?)`
-
-Navigate to a named route, applying guards and building the URL from the route definition.
-
-### `router.is(route)`
-
-Returns `true` if `router.route === route`. Useful for active link styling.
-
-```ts
-class:active={router.is('dashboard')}
-```
+## `goto`
 
-### `router.matches(routes)`
+Low-level path navigation. Prefer `router.navigate` for named routes.
 
-Returns `true` if `router.route` is any of the provided route names.
+```typescript
+import { goto } from 'svelte-navigator-lite';
 
-```ts
-class:active={router.matches(['dashboard', 'settings'])}
+await goto('/some/path');
+await goto('/some/path', { replaceState: true }); // replace instead of push
 ```
 
-### `router.registerRoute(name, route)`
-
-Register a new route.
-```ts
-registerRoute('settings', {
-    rootPath: 'settings',
-    segments: [],
-    routeGuards: [guards.authenticated],
-})
-
-### `page`
+## Migrating from v1
 
-A readable Svelte store that emits `{ url: URL }` and updates on every navigation. Useful when you need the raw URL.
+The `rootPath` + `segments` route definition is replaced by a single `pattern` string, and `routeGuards` inline on each route are replaced by named guards defined once.
 
-```ts
-import { page } from 'svelte-navigator-lite';
+```typescript
+// v1
+'edit': {
+    rootPath: 'event',
+    segments: [{ name: 'eventId' }, { enforceVal: 'edit' }],
+    routeGuards: [{ fn: () => !auth.isValid(), redirectTo: 'login' }],
+}
 
-$page.url.pathname;
+// v2
+{ name: 'edit', pattern: '/event/:eventId/edit', guards: ['auth'] }
+// with guard defined once in createRouter: auth: { condition: () => !auth.isValid(), redirectTo: 'login' }
 ```
-
----
-
-## Matching Rules
-
-- Routes are matched in the order they are defined — first match wins.
-- `rootPath` is always required and must match the first URL segment exactly.
-- Segment count must be between `required segments + 1` and `total segments + 1` (the `+1` accounts for `rootPath`).
-- A route with no segments only matches its `rootPath` with nothing after it (e.g. `/login` not `/login/extra`).
-- Unmatched URLs fall back to the `defaultRoute`.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createRouter, router, page, goto } from './router.svelte';
-export type { Route, RouteList, Router, RouteGuard } from './router.svelte';
+export { createRouter, router, page, goto, _createRouter } from './router.svelte.js';
+export type { RouteDefinition, Guard, RouterConfig } from './types.js';

package/dist/index.js

@@ -1,2 +1 @@
-// svelte-navigator-lite
-export { createRouter, router, page, goto } from './router.svelte';
+export { createRouter, router, page, goto, _createRouter } from './router.svelte.js';

package/dist/match.d.ts

@@ -0,0 +1,16 @@
+import type { RouteDefinition } from './types.js';
+type CompiledRoute = {
+    name: string;
+    pattern: string;
+    regex: RegExp;
+    paramNames: string[];
+    guards: string[];
+};
+export type RouteMatch = {
+    name: string;
+    params: Record<string, string>;
+};
+export declare function compileRoutes(routes: RouteDefinition[]): CompiledRoute[];
+export declare function matchPath(compiled: CompiledRoute[], pathname: string): RouteMatch | null;
+export declare function buildPath(pattern: string, params?: Record<string, string>): string;
+export {};

package/dist/match.js

@@ -0,0 +1,54 @@
+export function compileRoutes(routes) {
+    return routes.map(route => {
+        const paramNames = [];
+        const regexStr = route.pattern
+            // Escape regex special chars (except : and /)
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            // Optional params /:name? — make the whole slash+segment optional together
+            .replace(/\/:([a-zA-Z_][a-zA-Z0-9_]*)\?/g, (_, name) => {
+            paramNames.push(name);
+            return '(?:/([^/]*))?';
+        })
+            // Required params :name
+            .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+            paramNames.push(name);
+            return '([^/]+)';
+        });
+        return {
+            name: route.name,
+            pattern: route.pattern,
+            regex: new RegExp(`^${regexStr}/?$`),
+            paramNames,
+            guards: route.guards ?? [],
+        };
+    });
+}
+export function matchPath(compiled, pathname) {
+    for (const route of compiled) {
+        const m = pathname.match(route.regex);
+        if (!m)
+            continue;
+        const params = {};
+        route.paramNames.forEach((name, i) => {
+            const val = m[i + 1];
+            if (val)
+                params[name] = decodeURIComponent(val);
+        });
+        return { name: route.name, params };
+    }
+    return null;
+}
+// Build a URL path from a pattern and params.
+// Optional params omitted from params are dropped cleanly.
+export function buildPath(pattern, params = {}) {
+    const path = pattern
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\?/g, (_, name) => name in params ? encodeURIComponent(params[name]) : '')
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+        if (!(name in params))
+            throw new Error(`[router] missing required param "${name}" for pattern "${pattern}"`);
+        return encodeURIComponent(params[name]);
+    })
+        .replace(/\/+/g, '/') // collapse double slashes left by dropped optional params
+        .replace(/\/$/, ''); // strip trailing slash
+    return path || '/';
+}

package/dist/match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/match.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import { compileRoutes, matchPath, buildPath } from './match';
+// ─── matchPath ────────────────────────────────────────────────────────────────
+describe('matchPath — static routes', () => {
+    it('matches an exact path', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/login')).toEqual({ name: 'login', params: {} });
+    });
+    it('does not match a different path', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/signup')).toBeNull();
+    });
+    it('returns null when no routes match', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/unknown/path')).toBeNull();
+    });
+    it('returns the first matching route', () => {
+        const compiled = compileRoutes([
+            { name: 'first', pattern: '/cal' },
+            { name: 'second', pattern: '/cal' },
+        ]);
+        expect(matchPath(compiled, '/cal')?.name).toBe('first');
+    });
+});
+describe('matchPath — required params', () => {
+    it('captures a single param', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event/abc-123')).toEqual({
+            name: 'event',
+            params: { eventId: 'abc-123' },
+        });
+    });
+    it('does not match when a required param is absent', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event')).toBeNull();
+    });
+    it('captures multiple params', () => {
+        const compiled = compileRoutes([{ name: 'cal-date', pattern: '/cal/:mm/:dd/:yyyy' }]);
+        expect(matchPath(compiled, '/cal/05/13/2026')).toEqual({
+            name: 'cal-date',
+            params: { mm: '05', dd: '13', yyyy: '2026' },
+        });
+    });
+    it('captures params mixed with literal segments', () => {
+        const compiled = compileRoutes([{ name: 'edit', pattern: '/event/:eventId/edit' }]);
+        expect(matchPath(compiled, '/event/99/edit')).toEqual({
+            name: 'edit',
+            params: { eventId: '99' },
+        });
+    });
+    it('does not match when a literal segment differs', () => {
+        const compiled = compileRoutes([{ name: 'edit', pattern: '/event/:eventId/edit' }]);
+        expect(matchPath(compiled, '/event/99/delete')).toBeNull();
+    });
+    it('does not match when there are extra segments', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event/99/unexpected')).toBeNull();
+    });
+    it('differentiates routes with the same prefix by segment count', () => {
+        const compiled = compileRoutes([
+            { name: 'event', pattern: '/event/:eventId' },
+            { name: 'edit', pattern: '/event/:eventId/edit' },
+        ]);
+        expect(matchPath(compiled, '/event/99')?.name).toBe('event');
+        expect(matchPath(compiled, '/event/99/edit')?.name).toBe('edit');
+    });
+    it('URL-decodes param values', () => {
+        const compiled = compileRoutes([{ name: 'search', pattern: '/search/:query' }]);
+        expect(matchPath(compiled, '/search/hello%20world')?.params.query).toBe('hello world');
+    });
+});
+describe('matchPath — optional params', () => {
+    const compiled = compileRoutes([{ name: 'settings', pattern: '/settings/:page?' }]);
+    it('matches when the optional param is present', () => {
+        expect(matchPath(compiled, '/settings/account')).toEqual({
+            name: 'settings',
+            params: { page: 'account' },
+        });
+    });
+    it('matches when the optional param is absent', () => {
+        const result = matchPath(compiled, '/settings');
+        expect(result?.name).toBe('settings');
+        expect(result?.params).not.toHaveProperty('page');
+    });
+});
+// ─── buildPath ────────────────────────────────────────────────────────────────
+describe('buildPath — static patterns', () => {
+    it('returns the pattern as-is', () => {
+        expect(buildPath('/login')).toBe('/login');
+    });
+    it('returns / for an empty pattern', () => {
+        expect(buildPath('')).toBe('/');
+    });
+});
+describe('buildPath — required params', () => {
+    it('substitutes a single param', () => {
+        expect(buildPath('/event/:eventId', { eventId: '42' })).toBe('/event/42');
+    });
+    it('substitutes multiple params', () => {
+        expect(buildPath('/cal/:mm/:dd/:yyyy', { mm: '05', dd: '13', yyyy: '2026' }))
+            .toBe('/cal/05/13/2026');
+    });
+    it('substitutes params among literal segments', () => {
+        expect(buildPath('/event/:eventId/edit', { eventId: '99' })).toBe('/event/99/edit');
+    });
+    it('URL-encodes param values', () => {
+        expect(buildPath('/search/:query', { query: 'hello world' })).toBe('/search/hello%20world');
+    });
+    it('throws when a required param is missing', () => {
+        expect(() => buildPath('/event/:eventId', {})).toThrow('missing required param "eventId"');
+    });
+});
+describe('buildPath — optional params', () => {
+    it('inserts the value when the optional param is provided', () => {
+        expect(buildPath('/settings/:page?', { page: 'account' })).toBe('/settings/account');
+    });
+    it('drops the segment cleanly when the optional param is absent', () => {
+        expect(buildPath('/settings/:page?', {})).toBe('/settings');
+    });
+});

package/dist/router.svelte.d.ts

@@ -1,35 +1,31 @@
+import type { RouterConfig } from './types.js';
 export declare const page: import("svelte/store").Readable<{
     url: URL;
 }>;
 export declare function goto(path: string, { replaceState }?: {
     replaceState?: boolean | undefined;
 }): Promise<void>;
-export type Route = {
-    rootPath: string;
-    segments: ({
-        name?: string;
-        enforceVal?: string;
-        optional?: boolean;
-    })[];
-    routeGuards?: RouteGuard[];
-};
-export type RouteGuard = {
-    fn: () => boolean;
-    redirectTo: string;
+declare function _createRouter(): {
+    readonly route: string;
+    readonly params: Record<string, string>;
+    readonly searchParams: Record<string, string>;
+    readonly notFound: boolean;
+    is(route: string): boolean;
+    matches(routes: string[]): boolean;
+    parseUrl: (url: string) => void;
+    navigate(routeName: string, params?: Record<string, string>, searchParams?: Record<string, string>): Promise<void>;
+    init(config: RouterConfig): void;
 };
-export type RouteList = Record<string, Route>;
-export type Router = ReturnType<typeof _createRouter>;
-export declare function _createRouter(routeList?: RouteList): {
+export { _createRouter };
+export declare const router: {
     readonly route: string;
     readonly params: Record<string, string>;
     readonly searchParams: Record<string, string>;
     readonly notFound: boolean;
-    rootRoute: string;
     is(route: string): boolean;
     matches(routes: string[]): boolean;
     parseUrl: (url: string) => void;
-    navigate(route: string, params?: Record<string, string>, searchParams?: Record<string, string>): Promise<void>;
-    registerRoute(name: string, route: Route): void;
+    navigate(routeName: string, params?: Record<string, string>, searchParams?: Record<string, string>): Promise<void>;
+    init(config: RouterConfig): void;
 };
-export declare let router: Router;
-export declare function createRouter(RouteList: RouteList, defaultRoute: string): void;
+export declare function createRouter(config: RouterConfig): void;