@marianmeres/simple-router 3.0.1 → 3.1.0

package/AGENTS.md

@@ -0,0 +1,358 @@
+# @marianmeres/simple-router - AI Agent Reference
+
+Machine-readable documentation for AI coding assistants.
+
+## Package Metadata
+
+```yaml
+name: "@marianmeres/simple-router"
+version: "2.2.3"
+runtime: ["deno", "node"]
+module_system: "ESM"
+entry_point: "src/mod.ts"
+npm_dist: ".npm-dist/"
+license: "MIT"
+```
+
+## Core Concepts
+
+```yaml
+purpose: "Framework-agnostic string pattern matcher and router"
+use_cases:
+  - "SPA client-side routing"
+  - "File path matching"
+  - "Command pattern matching"
+  - "Any string identifier matching"
+key_features:
+  - "Dynamic route parameters with optional regex constraints"
+  - "Wildcard and catch-all routes"
+  - "Spread parameters for multi-segment matching"
+  - "Query string parsing (toggleable per route)"
+  - "Reactive subscriptions (Svelte store compatible)"
+  - "First-match-wins routing"
+```
+
+## File Structure
+
+```yaml
+source_files:
+  - path: "src/mod.ts"
+    purpose: "Main entry point, re-exports public API"
+    exports: ["SimpleRoute", "SimpleRouter", "RouteConfig", "RouteParams", "Logger", "RouteCallback", "RouterConfig", "RouterCurrent", "RouterOnOptions", "RouterOptions", "RouterSubscriber", "RouterUnsubscribe"]
+
+  - path: "src/route.ts"
+    purpose: "Low-level pattern parser"
+    exports: ["SimpleRoute", "RouteConfig", "RouteParams"]
+    class: "SimpleRoute"
+
+  - path: "src/router.ts"
+    purpose: "High-level router with pub/sub"
+    exports: ["SimpleRouter", "RouteParams", "Logger", "RouteCallback", "RouterConfig", "RouterCurrent", "RouterOnOptions", "RouterOptions", "RouterSubscriber", "RouterUnsubscribe"]
+    class: "SimpleRouter"
+
+test_files:
+  - path: "tests/route.test.ts"
+    test_count: 63
+    coverage: "Pattern matching, query params, errors"
+
+  - path: "tests/router.test.ts"
+    test_count: 24
+    coverage: "Router lifecycle, subscriptions, logger, edge cases"
+
+build_files:
+  - path: "scripts/build-npm.ts"
+    purpose: "Deno-to-npm build script"
+```
+
+## Dependencies
+
+```yaml
+runtime:
+  - name: "@marianmeres/pubsub"
+    version: "^2.4.1"
+    registry: "jsr"
+    purpose: "Reactive subscriptions"
+
+dev_only:
+  - "@std/assert"
+  - "@std/fs"
+  - "@std/path"
+```
+
+## API Summary
+
+### SimpleRouter
+
+```yaml
+class: "SimpleRouter<T = unknown>"
+purpose: "Main router for pattern matching and state management"
+generic_param:
+  name: "T"
+  default: "unknown"
+  description: "Return type of route callbacks and exec() method"
+
+static_properties:
+  - name: "debug"
+    type: "boolean"
+    default: false
+    description: "Enable debug logging (uses logger if provided, else console.log)"
+
+constructor:
+  params:
+    - name: "config"
+      type: "RouterConfig<T> | RouterOptions<T> | null"
+      optional: true
+      description: "Route config or options object with routes and logger"
+
+methods:
+  - name: "on"
+    signature: "(routes: string | string[], cb: RouteCallback<T>, options?: RouterOnOptions) => void"
+    description: "Register route(s) with callback"
+    important: "Routes matched in registration order - first match wins"
+
+  - name: "exec"
+    signature: "(url: string, fallbackFn?: RouteCallback<T>) => T | false"
+    description: "Execute pattern matching"
+    returns: "Callback result (type T), or false if no match"
+
+  - name: "subscribe"
+    signature: "(subscription: RouterSubscriber) => RouterUnsubscribe"
+    description: "Subscribe to state changes (Svelte store compatible)"
+    behavior: "Called immediately with current state"
+    returns: "Unsubscribe function directly (not wrapped object)"
+
+  - name: "reset"
+    signature: "() => this"
+    description: "Clear all routes (except catch-all)"
+
+  - name: "info"
+    signature: "() => Record<string, string>"
+    description: "Get route-to-label mapping"
+
+properties:
+  - name: "current"
+    type: "RouterCurrent"
+    readonly: true
+    description: "Current router state"
+```
+
+### SimpleRoute
+
+```yaml
+class: SimpleRoute
+purpose: "Low-level pattern parser"
+
+static_properties:
+  - name: "SPLITTER"
+    type: "string"
+    default: "/"
+  - name: "WILDCARD"
+    type: "string"
+    default: "*"
+
+constructor:
+  params:
+    - name: "route"
+      type: "string"
+      description: "Pattern string"
+  throws: "Error if pattern invalid"
+
+static_methods:
+  - name: "parseQueryString"
+    signature: "(str: string) => RouteParams"
+    description: "Parse query string to object"
+
+methods:
+  - name: "parse"
+    signature: "(url: string, allowQueryParams?: boolean) => RouteParams | null"
+    description: "Match string against pattern"
+    returns: "Params object or null"
+```
+
+## Pattern Syntax Reference
+
+```yaml
+patterns:
+  exact:
+    syntax: "literal"
+    example: "foo"
+    matches: "foo"
+
+  named_param:
+    syntax: "[name]"
+    example: "[id]"
+    captures: "{ id: 'value' }"
+
+  regex_param:
+    syntax: "[name(regex)]"
+    example: "[id([0-9]+)]"
+    captures: "{ id: '123' }"
+    constraint: "Must match regex"
+
+  optional:
+    syntax: "[name]?"
+    example: "[id]?"
+    captures: "{} or { id: 'value' }"
+
+  spread:
+    syntax: "[...name]"
+    example: "[...path]"
+    captures: "{ path: 'a/b/c' }"
+    constraint: "Only one per route, cannot be optional"
+
+  wildcard:
+    syntax: "*"
+    example: "/foo/*"
+    constraint: "Must be last segment"
+    captures: "{}"
+```
+
+## Type Definitions
+
+```typescript
+type RouteParams = Record<string, any>;
+
+// Generic callback type - T is the return type
+type RouteCallback<T = unknown> = (params: RouteParams | null, route: string) => T;
+
+// Generic config type - T is the return type of all callbacks
+type RouterConfig<T = unknown> = Record<string, RouteCallback<T>>;
+
+interface Logger {
+  debug: (...args: unknown[]) => unknown;
+  log: (...args: unknown[]) => unknown;
+  warn: (...args: unknown[]) => unknown;
+  error: (...args: unknown[]) => unknown;
+}
+
+// Generic options type - T is the return type of route callbacks
+interface RouterOptions<T = unknown> {
+  routes?: RouterConfig<T> | null;
+  logger?: Logger | null;
+}
+
+interface RouterCurrent {
+  route: string | null;
+  params: RouteParams | null;
+  label: string | null;
+}
+
+interface RouterOnOptions {
+  label?: string | null;
+  allowQueryParams?: boolean;
+}
+
+type RouterSubscriber = (current: RouterCurrent) => void;
+
+type RouterUnsubscribe = () => void;
+
+interface RouteConfig {
+  segment: string;
+  name: string | null;
+  test: RegExp;
+  isOptional: boolean;
+  isSpread: boolean;
+}
+```
+
+## Common Usage Patterns
+
+### SPA Hash Routing (Typed)
+
+```typescript
+// Type-safe router - exec() returns Component | false
+const router = new SimpleRouter<Component>({
+  "/": () => HomePage,
+  "/user/[id]": (params) => UserPage(params?.id),
+  "*": () => NotFoundPage
+});
+
+window.addEventListener("hashchange", () => {
+  const path = location.hash.slice(1) || "/";
+  const result = router.exec(path); // Component | false
+  if (result !== false) render(result);
+});
+```
+
+### File Path Matching
+
+```typescript
+const router = new SimpleRouter({
+  "src/[module]/[file].ts": ({ module, file }) => process(module, file),
+  "assets/[...path]": ({ path }) => loadAsset(path)
+});
+```
+
+### Command Routing
+
+```typescript
+const router = new SimpleRouter({
+  "user:create": () => createUser(),
+  "user:delete:[id]": ({ id }) => deleteUser(id)
+});
+```
+
+## Important Behaviors
+
+```yaml
+behaviors:
+  - name: "First Match Wins"
+    description: "Routes matched in registration order"
+    implication: "Register specific routes before generic ones"
+
+  - name: "Separator Normalization"
+    description: "Multiple separators normalized, trimmed from ends"
+    example: "//foo//bar// matches foo/bar"
+
+  - name: "Query String Priority"
+    description: "Path params override same-name query params"
+
+  - name: "Catch-all Stored Separately"
+    description: "'*' route stored in #catchAll, not in #routes array"
+
+  - name: "Immediate Subscription Call"
+    description: "subscribe() calls callback immediately with current state"
+```
+
+## Error Conditions
+
+```yaml
+errors:
+  - condition: "Multiple spread segments"
+    message: "Multiple spread segments are invalid"
+
+  - condition: "Optional spread"
+    message: "Spread segment must not be marked as optional"
+
+  - condition: "Wildcard not last"
+    message: "Wildcard '*' can be used only as a last segment"
+
+  - condition: "Invalid regex in pattern"
+    message: "Invalid regex in route pattern '{segment}': {error}"
+
+  - condition: "Non-function subscriber"
+    throws: "TypeError: Subscription is not a function"
+```
+
+## Development Commands
+
+```yaml
+commands:
+  test: "deno task test"
+  build_npm: "deno task npm:build"
+  publish_npm: "deno task npm:publish"
+```
+
+## Code Modification Guidelines
+
+```yaml
+guidelines:
+  - "Maintain Svelte store contract compatibility for subscribe()"
+  - "subscribe() returns unsubscribe function directly (not wrapped object)"
+  - "First-match-wins is core behavior - do not change"
+  - "Query param parsing must remain toggleable per-route"
+  - "Keep catch-all ('*') handling separate from regular routes"
+  - "URL encoding/decoding must be handled for params"
+  - "Logger interface must remain compatible with @marianmeres/clog"
+  - "Tests cover 87 cases - run before any changes"
+```

package/API.md

@@ -0,0 +1,570 @@
+# API Reference
+
+Full API documentation for `@marianmeres/simple-router`.
+
+## Table of Contents
+
+- [SimpleRouter](#simplerouter)
+  - [Constructor](#constructor)
+  - [Static Properties](#static-properties)
+  - [Instance Properties](#instance-properties)
+  - [Methods](#methods)
+- [SimpleRoute](#simpleroute)
+  - [Constructor](#simpleroute-constructor)
+  - [Static Properties](#simpleroute-static-properties)
+  - [Static Methods](#static-methods)
+  - [Instance Methods](#instance-methods)
+- [Types](#types)
+- [Pattern Syntax](#pattern-syntax)
+
+---
+
+## SimpleRouter
+
+The main router class for registering routes, executing pattern matching, and subscribing to state changes.
+
+`SimpleRouter` is generic over `T`, the return type of route callbacks. This allows for type-safe `exec()` return values.
+
+### Constructor
+
+```ts
+new SimpleRouter<T = unknown>(config?: RouterConfig<T> | RouterOptions<T> | null)
+```
+
+Creates a new router instance.
+
+**Type Parameters:**
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `T` | `unknown` | The return type of route callbacks |
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `config` | `RouterConfig<T> \| RouterOptions<T> \| null` | Optional route configuration or options object |
+
+**Example:**
+
+```ts
+// Empty router (T defaults to unknown)
+const router = new SimpleRouter();
+
+// Typed router - all callbacks must return Component
+const router = new SimpleRouter<Component>({
+  "/": () => HomePage,
+  "/about": () => AboutPage,
+  "*": () => NotFoundPage
+});
+
+// Simple config without explicit type (T inferred from callbacks)
+const router = new SimpleRouter({
+  "/": () => HomePage,
+  "/about": () => AboutPage,
+  "*": () => NotFoundPage
+});
+
+// With options object (for logger support)
+const router = new SimpleRouter<Component>({
+  routes: {
+    "/": () => HomePage,
+    "/about": () => AboutPage
+  },
+  logger: myLogger // optional, compatible with @marianmeres/clog
+});
+```
+
+### Static Properties
+
+#### `debug`
+
+```ts
+static debug: boolean = false
+```
+
+Enable/disable console debug logging for route matching. When enabled, logs detailed matching information using the logger instance (if provided) or falls back to `console.log`.
+
+**Example:**
+
+```ts
+SimpleRouter.debug = true;
+router.exec("/test"); // Logs: [SimpleRouter] '/test' -> matches '/' with {}
+```
+
+### Instance Properties
+
+#### `current`
+
+```ts
+get current(): RouterCurrent
+```
+
+Returns the current router state containing the last matched route, extracted parameters, and label.
+
+**Returns:** `RouterCurrent` - Current state object
+
+**Example:**
+
+```ts
+router.exec("/user/123");
+console.log(router.current);
+// { route: "/user/[id]", params: { id: "123" }, label: null }
+```
+
+### Methods
+
+#### `on()`
+
+```ts
+on(routes: string | string[], cb: RouteCallback<T>, options?: RouterOnOptions): void
+```
+
+Registers one or more route patterns with a callback function.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `routes` | `string \| string[]` | Single route pattern or array of patterns |
+| `cb` | `RouteCallback<T>` | Callback function executed when route matches (must return `T`) |
+| `options` | `RouterOnOptions` | Optional configuration object |
+
+**Options:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string \| null` | `null` | Label for debugging/identification |
+| `allowQueryParams` | `boolean` | `true` | Whether to parse query parameters |
+
+**Example:**
+
+```ts
+// Single route
+router.on("/users", () => UsersPage);
+
+// Multiple routes to same handler
+router.on(["/", "/home", "/index.html"], () => HomePage);
+
+// With dynamic parameters
+router.on("/user/[id]", (params) => UserPage(params?.id));
+
+// With regex constraint
+router.on("/post/[id([0-9]+)]", (params) => PostPage(params?.id));
+
+// With label for debugging
+router.on("/admin", () => AdminPage, { label: "admin-dashboard" });
+
+// Disable query parameter parsing
+router.on("/raw/[path]", (params) => RawPage(params), { allowQueryParams: false });
+
+// Catch-all route (must be registered last)
+router.on("*", () => NotFoundPage);
+```
+
+**Important:** Routes are matched in registration order. First match wins!
+
+---
+
+#### `exec()`
+
+```ts
+exec(url: string, fallbackFn?: RouteCallback<T>): T | false
+```
+
+Executes pattern matching against the provided string.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `url` | `string` | String to match against registered patterns |
+| `fallbackFn` | `RouteCallback<T>` | Optional fallback function if no route matches |
+
+**Returns:** `T | false` - The value returned by the matched callback (type `T`), or `false` if no match and no catch-all/fallback.
+
+**Match Priority:**
+1. First registered matching route
+2. Fallback function (if provided)
+3. Catch-all `"*"` route (if registered)
+4. Returns `false`
+
+**Example:**
+
+```ts
+// Basic usage
+const result = router.exec("/users");
+
+// With query parameters
+router.exec("/search?q=hello&page=1");
+
+// With fallback function
+router.exec("/unknown", (params, route) => {
+  console.log("No match found");
+  return NotFoundPage;
+});
+
+// Return values from callbacks
+const component = router.exec("/home");
+render(component);
+```
+
+---
+
+#### `subscribe()`
+
+```ts
+subscribe(subscription: RouterSubscriber): RouterUnsubscribe
+```
+
+Subscribes to router state changes. Follows the [Svelte store contract](https://svelte.dev/docs#Store_contract).
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `subscription` | `RouterSubscriber` | Callback function receiving state changes |
+
+**Returns:** `RouterUnsubscribe` - Unsubscribe function
+
+**Behavior:**
+- Subscriber is called immediately with current state
+- Subsequently called on every `exec()` call
+
+**Example:**
+
+```ts
+const unsubscribe = router.subscribe((state) => {
+  console.log("Route:", state.route);
+  console.log("Params:", state.params);
+  console.log("Label:", state.label);
+});
+
+// In Svelte
+$: currentRoute = $router;
+
+// Cleanup
+unsubscribe();
+```
+
+---
+
+#### `reset()`
+
+```ts
+reset(): this
+```
+
+Clears all registered routes except the catch-all (`*`).
+
+**Returns:** The router instance for method chaining
+
+**Example:**
+
+```ts
+router.reset().on("/new-route", () => NewPage);
+```
+
+---
+
+#### `info()`
+
+```ts
+info(): Record<string, string>
+```
+
+Returns a map of registered route patterns to their labels.
+
+**Returns:** Object mapping route patterns to labels (empty string if no label)
+
+**Example:**
+
+```ts
+router.on("/users", () => {}, { label: "users-list" });
+router.on("/posts", () => {}, { label: "posts-list" });
+
+console.log(router.info());
+// { "/users": "users-list", "/posts": "posts-list" }
+```
+
+---
+
+## SimpleRoute
+
+Low-level route pattern parser. Use this directly only when you need pattern matching without the full router functionality.
+
+<a id="simpleroute-constructor"></a>
+### Constructor
+
+```ts
+new SimpleRoute(pattern: string)
+```
+
+Creates a new route pattern parser.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pattern` | `string` | Route pattern to match against |
+
+**Throws:** `Error` if pattern is invalid (e.g., multiple spread segments, invalid regex)
+
+**Example:**
+
+```ts
+const route = new SimpleRoute("/user/[id([0-9]+)]");
+const route2 = new SimpleRoute("/files/[...path]");
+```
+
+<a id="simpleroute-static-properties"></a>
+### Static Properties
+
+#### `SPLITTER`
+
+```ts
+static SPLITTER: string = "/"
+```
+
+Separator used to split paths into segments.
+
+#### `WILDCARD`
+
+```ts
+static WILDCARD: string = "*"
+```
+
+Wildcard symbol for catch-all routes. Must be used as the last segment.
+
+### Static Methods
+
+#### `parseQueryString()`
+
+```ts
+static parseQueryString(str: string): RouteParams
+```
+
+Parses a query string into an object of key-value pairs.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `str` | `string` | Query string (without leading "?") |
+
+**Returns:** `RouteParams` - Object with parsed query parameters
+
+**Example:**
+
+```ts
+SimpleRoute.parseQueryString("foo=bar&baz=123");
+// { foo: "bar", baz: "123" }
+
+SimpleRoute.parseQueryString("name=John%20Doe&city=New%20York");
+// { name: "John Doe", city: "New York" }
+
+SimpleRoute.parseQueryString("empty=&flag");
+// { empty: "", flag: "" }
+```
+
+### Instance Methods
+
+#### `parse()`
+
+```ts
+parse(url: string, allowQueryParams?: boolean): RouteParams | null
+```
+
+Parses a string against this route pattern.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `url` | `string` | - | String to test against the pattern |
+| `allowQueryParams` | `boolean` | `true` | Whether to parse query string parameters |
+
+**Returns:** `RouteParams` object with extracted parameters, or `null` if no match
+
+**Example:**
+
+```ts
+const route = new SimpleRoute("/user/[id]");
+
+route.parse("/user/123");
+// { id: "123" }
+
+route.parse("/user/123?tab=profile");
+// { id: "123", tab: "profile" }
+
+route.parse("/user/123?tab=profile", false);
+// { id: "123?tab=profile" }
+
+route.parse("/post/456");
+// null
+```
+
+---
+
+## Types
+
+### RouteParams
+
+```ts
+type RouteParams = Record<string, any>;
+```
+
+Object containing extracted route parameters. Keys are parameter names, values are the extracted string values.
+
+### RouteCallback\<T\>
+
+```ts
+type RouteCallback<T = unknown> = (params: RouteParams | null, route: string) => T;
+```
+
+Callback function executed when a route matches.
+
+**Type Parameters:**
+- `T` - The return type of the callback (default: `unknown`)
+
+**Parameters:**
+- `params` - Extracted route parameters (or `null` if no params)
+- `route` - The matched route pattern string
+
+**Returns:** `T` - The value to be returned by `exec()`
+
+### RouterConfig\<T\>
+
+```ts
+type RouterConfig<T = unknown> = Record<string, RouteCallback<T>>;
+```
+
+Configuration object mapping route patterns to callbacks.
+
+**Type Parameters:**
+- `T` - The return type of all route callbacks (default: `unknown`)
+
+### RouterCurrent
+
+```ts
+interface RouterCurrent {
+  route: string | null;   // Matched pattern, "*" for catch-all, null if no match
+  params: RouteParams | null;
+  label: string | null;
+}
+```
+
+Current router state object.
+
+### RouterOnOptions
+
+```ts
+interface RouterOnOptions {
+  label?: string | null;      // Optional label for debugging
+  allowQueryParams?: boolean; // Whether to parse query params (default: true)
+}
+```
+
+Options for the `on()` method.
+
+### Logger
+
+```ts
+interface Logger {
+  debug: (...args: unknown[]) => unknown;
+  log: (...args: unknown[]) => unknown;
+  warn: (...args: unknown[]) => unknown;
+  error: (...args: unknown[]) => unknown;
+}
+```
+
+Logger interface compatible with `@marianmeres/clog`. Provides console-compatible logging methods.
+
+### RouterOptions\<T\>
+
+```ts
+interface RouterOptions<T = unknown> {
+  routes?: RouterConfig<T> | null;  // Route configuration
+  logger?: Logger | null;           // Optional logger instance
+}
+```
+
+Options object for the constructor (alternative to plain `RouterConfig`).
+
+**Type Parameters:**
+- `T` - The return type of route callbacks (default: `unknown`)
+
+### RouterSubscriber
+
+```ts
+type RouterSubscriber = (current: RouterCurrent) => void;
+```
+
+Callback function for route subscriptions.
+
+### RouterUnsubscribe
+
+```ts
+type RouterUnsubscribe = () => void;
+```
+
+Unsubscribe function returned by `subscribe()`.
+
+### RouteConfig (Internal)
+
+```ts
+interface RouteConfig {
+  segment: string;
+  name: string | null;
+  test: RegExp;
+  isOptional: boolean;
+  isSpread: boolean;
+}
+```
+
+Internal configuration for a parsed route segment. Exported for advanced use cases.
+
+---
+
+## Pattern Syntax
+
+### Segment Types
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `exact` | Literal match | `foo` matches "foo" |
+| `[name]` | Named parameter | `[id]` captures any segment |
+| `[name(regex)]` | Regex constrained | `[id([0-9]+)]` captures digits only |
+| `[name]?` | Optional segment | `[id]?` matches with or without |
+| `[...name]` | Spread parameter | `[...path]` captures multiple segments |
+| `*` | Wildcard catch-all | Matches any remaining path |
+
+### Key Behaviors
+
+1. **Separator Normalization:** Multiple separators normalized to single; trimmed from ends
+2. **First Match Wins:** Routes matched in registration order
+3. **Query String Parsing:** Enabled by default, can disable per-route
+4. **Path Params Priority:** Path params override query params with same name
+5. **URL Decoding:** Both param names and values are URL-decoded
+
+### Pattern Constraints
+
+- Spread segments cannot be optional (`[...path]?` throws error)
+- Only one spread segment allowed per route
+- Wildcard `*` must be the last segment
+- Regex in `[name(regex)]` must be valid JavaScript regex
+
+### Examples
+
+| Pattern | Input | Result |
+|---------|-------|--------|
+| `/foo` | `/bar` | `null` |
+| `/foo` | `/foo` | `{}` |
+| `/[foo]` | `/bar` | `{ foo: "bar" }` |
+| `/[id([0-9]+)]` | `/123` | `{ id: "123" }` |
+| `/[id([0-9]+)]` | `/abc` | `null` |
+| `/foo/[bar]?` | `/foo` | `{}` |
+| `/foo/[bar]?` | `/foo/baz` | `{ bar: "baz" }` |
+| `/[...path]/[file]` | `/a/b/c.js` | `{ path: "a/b", file: "c.js" }` |
+| `/*` | `/any/path` | `{}` |
+| `/[foo]/*` | `/bar/baz` | `{ foo: "bar" }` |

package/README.md

@@ -255,17 +255,43 @@ SimpleRoute.parseQueryString("foo=bar&baz=123");
 
 ## TypeScript
 
-Full TypeScript support with exported types:
+Full TypeScript support with generic types for type-safe route callbacks and `exec()` return values.
+
+### Generic Router
+
+`SimpleRouter<T>` is generic over `T`, the return type of route callbacks:
+
+```ts
+// Typed router - all callbacks must return Component, exec() returns Component | false
+const router = new SimpleRouter<Component>({
+	"/": () => HomePage,
+	"/about": () => AboutPage,
+	"*": () => NotFoundPage,
+});
+
+const result = router.exec("/about"); // Component | false
+if (result !== false) {
+	render(result); // result is Component
+}
+
+// Without explicit type - T is inferred from callbacks (or defaults to unknown)
+const router2 = new SimpleRouter({
+	"/": () => "home",
+	"/about": () => "about",
+});
+```
+
+### Exported Types
 
 ```ts
 import type {
 	Logger,
 	RouteParams,
-	RouteCallback,
-	RouterConfig,
+	RouteCallback,     // RouteCallback<T = unknown>
+	RouterConfig,      // RouterConfig<T = unknown>
 	RouterCurrent,
 	RouterOnOptions,
-	RouterOptions,
+	RouterOptions,     // RouterOptions<T = unknown>
 	RouterSubscriber,
 	RouterUnsubscribe,
 } from "@marianmeres/simple-router";
@@ -276,21 +302,24 @@ import type {
 ### SPA with Hash Routing
 
 ```ts
-const router = new SimpleRouter({
+// Type-safe router with Component return type
+const router = new SimpleRouter<Component>({
 	"/": () => HomePage,
 	"/about": () => AboutPage,
 	"/user/[id]": (params) => UserPage(params?.id),
 	"*": () => NotFoundPage,
 });
 
-function render(component) {
-	document.getElementById("app").innerHTML = component;
+function render(component: Component) {
+	document.getElementById("app").innerHTML = component.render();
 }
 
 window.addEventListener("hashchange", () => {
 	const path = location.hash.slice(1) || "/";
-	const component = router.exec(path);
-	render(component);
+	const component = router.exec(path); // Component | false
+	if (component !== false) {
+		render(component);
+	}
 });
 
 // Trigger initial render

package/dist/router.d.ts

@@ -12,19 +12,20 @@ export type RouteParams = Record<string, any>;
 /**
  * Callback function executed when a route matches.
  *
+ * @typeParam T - The return type of the callback
  * @param params - Extracted route parameters (null if no match)
  * @param route - The matched route pattern string
  * @returns Any value - useful for returning components, data, or control flow values
  *
  * @example
  * ```ts
- * const callback: RouteCallback = (params, route) => {
+ * const callback: RouteCallback<MyComponent> = (params, route) => {
  *   console.log(`Matched ${route} with params:`, params);
  *   return MyComponent;
  * };
  * ```
  */
-export type RouteCallback = (params: RouteParams | null, route: string) => any;
+export type RouteCallback<T = unknown> = (params: RouteParams | null, route: string) => T;
 /**
  * Represents the current router state including the matched route,
  * extracted parameters, and optional label.
@@ -50,16 +51,18 @@ export interface RouterOnOptions {
  * Configuration object for initializing the router with routes.
  * Maps route patterns to their callback functions.
  *
+ * @typeParam T - The return type of route callbacks
+ *
  * @example
  * ```ts
- * const config: RouterConfig = {
+ * const config: RouterConfig<Component> = {
  *   "/": () => HomePage,
  *   "/user/[id]": (params) => UserPage(params?.id),
  *   "*": () => NotFoundPage
  * };
  * ```
  */
-export type RouterConfig = Record<string, RouteCallback>;
+export type RouterConfig<T = unknown> = Record<string, RouteCallback<T>>;
 /**
  * Logger interface compatible with `@marianmeres/clog`.
  * Provides console-compatible logging methods.
@@ -76,10 +79,12 @@ export interface Logger {
 }
 /**
  * Options for the SimpleRouter factory/constructor.
+ *
+ * @typeParam T - The return type of route callbacks
  */
-export interface RouterOptions {
+export interface RouterOptions<T = unknown> {
     /** Route configuration mapping patterns to callbacks */
-    routes?: RouterConfig | null;
+    routes?: RouterConfig<T> | null;
     /** Optional logger instance for debug output (compatible with @marianmeres/clog) */
     logger?: Logger | null;
 }
@@ -123,8 +128,10 @@ export type RouterSubscriber = (current: RouterCurrent) => void;
  *
  * cmdRouter.exec("user:delete:123");
  * ```
+ *
+ * @typeParam T - The return type of route callbacks (default: unknown)
  */
-export declare class SimpleRouter {
+export declare class SimpleRouter<T = unknown> {
     #private;
     /**
      * Enable/disable console debug logging for route matching.
@@ -140,14 +147,14 @@ export declare class SimpleRouter {
      *
      * @example
      * ```ts
-     * // Simple config (backwards compatible)
-     * const router = new SimpleRouter({
+     * // Typed router - exec() returns Component | false
+     * const router = new SimpleRouter<Component>({
      *   "/": () => HomePage,
      *   "/about": () => AboutPage
      * });
      *
      * // With options object
-     * const router = new SimpleRouter({
+     * const router = new SimpleRouter<Component>({
      *   routes: {
      *     "/": () => HomePage,
      *     "/about": () => AboutPage
@@ -156,7 +163,7 @@ export declare class SimpleRouter {
      * });
      * ```
      */
-    constructor(config?: RouterConfig | RouterOptions | null);
+    constructor(config?: RouterConfig<T> | RouterOptions<T> | null);
     /**
      * Returns a map of registered route patterns to their labels.
      * Useful for debugging and introspection.
@@ -224,38 +231,36 @@ export declare class SimpleRouter {
      * router.on("*", () => NotFoundPage);
      * ```
      */
-    on(routes: string | string[], cb: RouteCallback, options?: RouterOnOptions): void;
+    on(routes: string | string[], cb: RouteCallback<T>, options?: RouterOnOptions): void;
     /**
      * Executes pattern matching against the provided string.
-     * Returns the value returned by the matched route's callback.
+     * Returns the value returned by the matched route's callback (type `T`).
      * Routes are tested in registration order - first match wins.
      *
      * @param url - String to match against registered patterns (can be a URL, file path, command, etc.)
      * @param fallbackFn - Optional fallback function if no route matches
-     * @returns The value returned by the matched callback, or false if no match
+     * @returns `T | false` - The value returned by the matched callback, or `false` if no match
      *
      * @example
      * ```ts
-     * // URL matching
-     * router.exec("/users"); // Returns result of callback
+     * // Type-safe routing
+     * const router = new SimpleRouter<Component>({ "/home": () => HomePage });
+     * const result = router.exec("/home"); // Component | false
      *
      * // With query parameters
      * router.exec("/users?sort=name");
      *
-     * // File path matching
-     * router.exec("src/components/Button.ts");
-     *
-     * // Command matching
-     * router.exec("user:delete:123");
-     *
      * // With fallback
-     * router.exec("/unknown", () => console.log("Not found"));
+     * router.exec("/unknown", () => NotFoundPage);
      *
-     * // Can return components, values, etc.
-     * const component = router.exec("/home");
+     * // Check for no match
+     * const component = router.exec("/path");
+     * if (component !== false) {
+     *   render(component);
+     * }
      * ```
      */
-    exec(url: string, fallbackFn?: RouteCallback): unknown;
+    exec(url: string, fallbackFn?: RouteCallback<T>): T | false;
     /**
      * Subscribes to router state changes.
      * Follows the Svelte store contract - subscriber is called immediately with current state.

package/dist/router.js

@@ -30,6 +30,8 @@ const PUBSUB_TOPIC = "current";
  *
  * cmdRouter.exec("user:delete:123");
  * ```
+ *
+ * @typeParam T - The return type of route callbacks (default: unknown)
  */
 export class SimpleRouter {
     /**
@@ -55,14 +57,14 @@ export class SimpleRouter {
      *
      * @example
      * ```ts
-     * // Simple config (backwards compatible)
-     * const router = new SimpleRouter({
+     * // Typed router - exec() returns Component | false
+     * const router = new SimpleRouter<Component>({
      *   "/": () => HomePage,
      *   "/about": () => AboutPage
      * });
      *
      * // With options object
-     * const router = new SimpleRouter({
+     * const router = new SimpleRouter<Component>({
      *   routes: {
      *     "/": () => HomePage,
      *     "/about": () => AboutPage
@@ -196,32 +198,30 @@ export class SimpleRouter {
     }
     /**
      * Executes pattern matching against the provided string.
-     * Returns the value returned by the matched route's callback.
+     * Returns the value returned by the matched route's callback (type `T`).
      * Routes are tested in registration order - first match wins.
      *
      * @param url - String to match against registered patterns (can be a URL, file path, command, etc.)
      * @param fallbackFn - Optional fallback function if no route matches
-     * @returns The value returned by the matched callback, or false if no match
+     * @returns `T | false` - The value returned by the matched callback, or `false` if no match
      *
      * @example
      * ```ts
-     * // URL matching
-     * router.exec("/users"); // Returns result of callback
+     * // Type-safe routing
+     * const router = new SimpleRouter<Component>({ "/home": () => HomePage });
+     * const result = router.exec("/home"); // Component | false
      *
      * // With query parameters
      * router.exec("/users?sort=name");
      *
-     * // File path matching
-     * router.exec("src/components/Button.ts");
-     *
-     * // Command matching
-     * router.exec("user:delete:123");
-     *
      * // With fallback
-     * router.exec("/unknown", () => console.log("Not found"));
+     * router.exec("/unknown", () => NotFoundPage);
      *
-     * // Can return components, values, etc.
-     * const component = router.exec("/home");
+     * // Check for no match
+     * const component = router.exec("/path");
+     * if (component !== false) {
+     *   render(component);
+     * }
      * ```
      */
     exec(url, fallbackFn) {
@@ -233,7 +233,7 @@ export class SimpleRouter {
             if (params !== null) {
                 this.#publishCurrent(route.route, params, label);
                 this.#dbg(`${dbgPrefix}matches '${route.route}' with`, params);
-                return typeof cb === "function" ? cb(params, route.route) : true;
+                return cb(params, route.route);
             }
         }
         if (typeof fallbackFn === "function") {

package/package.json

@@ -1,20 +1,25 @@
 {
 	"name": "@marianmeres/simple-router",
-	"version": "3.0.1",
+	"version": "3.1.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
 	"author": "Marian Meres",
 	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/pubsub": "^2.4.4"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/simple-router.git"
 	},
 	"bugs": {
 		"url": "https://github.com/marianmeres/simple-router/issues"
-	},
-	"dependencies": {
-		"@marianmeres/pubsub": "^2.2.0",
-		"@marianmeres/clog": "^2.3.3"
 	}
-}
+}