navigation-kit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kris Papercut
+
+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,194 @@
+# navigation-kit
+
+Framework-agnostic typed routing utility for TypeScript. Wraps your route definitions into a type-safe interface for URL generation, path matching, and navigation — without depending on any specific router library.
+
+[![npm version](https://img.shields.io/npm/v/navigation-kit.svg)](https://www.npmjs.com/package/navigation-kit)
+[![Publish](https://github.com/kearisp/navigation-kit/actions/workflows/publish-latest.yml/badge.svg?event=release)](https://github.com/kearisp/navigation-kit/actions/workflows/publish-latest.yml)
+[![License](https://img.shields.io/npm/l/navigation-kit)](https://github.com/kearisp/navigation-kit/blob/master/LICENSE)
+
+[![npm total downloads](https://img.shields.io/npm/dt/navigation-kit.svg)](https://www.npmjs.com/package/navigation-kit)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/navigation-kit)](https://bundlephobia.com/package/navigation-kit)
+![Coverage](https://gist.githubusercontent.com/kearisp/f17f46c6332ea3bb043f27b0bddefa9f/raw/coverage-navigation-kit-latest.svg)
+
+## Installation
+
+```bash
+npm install navigation-kit
+```
+
+## Quick start
+
+```ts
+import { createRouter } from "navigation-kit";
+
+const routes = {
+    home:    "/",
+    about:   "/about",
+    user:    "/users/:id",
+    post:    "/users/:userId/posts/:postId",
+} as const; // as const is required — see note below
+
+const router = createRouter(routes);
+
+router.path("user");                           // "/users/:id"
+router.url("about");                           // "/about"
+router.url("user", { id: "42" });             // "/users/42"
+router.url("post", { userId: "1", postId: "99" }); // "/users/1/posts/99"
+router.match("user", "/users/42");            // PathMatch | null
+```
+
+> **`as const` is required.** Without it TypeScript widens string values to `string` and loses the ability to infer route parameters. Always declare your routes object with `as const`.
+
+## API
+
+### `createRouter(routes, adapter?)`
+
+Creates a typed router object from a route map.
+
+```ts
+const router = createRouter(routes);
+```
+
+**Type parameters:**
+
+```ts
+createRouter<TRoutes, TNavigateOptions = void>(routes, adapter?)
+```
+
+- `TRoutes` — inferred from the routes argument; use `as const` on your routes object
+- `TNavigateOptions` — type of the `options` argument forwarded to `navigate` (e.g. `NavigateOptions` from react-router). Defaults to `void`.
+
+---
+
+#### `router.pattern(route)`
+
+Returns the `PathPattern` for a named route.
+
+```ts
+router.pattern("user"); // { path: "/users/:id" }
+```
+
+Route values can also be `PathPattern` objects directly:
+
+```ts
+const routes = {
+    users: { path: "/users", caseSensitive: true, end: false },
+} as const;
+```
+
+---
+
+#### `router.path(route)`
+
+Returns the raw path string.
+
+```ts
+router.path("user"); // "/users/:id"
+```
+
+---
+
+#### `router.url(route, params?)`
+
+Generates a URL. TypeScript enforces that `params` is **required** for routes with dynamic segments and **forbidden** for static routes.
+
+```ts
+router.url("about");                    // ok — no params needed
+router.url("user", { id: "42" });      // ok
+router.url("user");                     // TS error — params required
+router.url("about", { id: "42" });     // TS error — no params expected
+```
+
+Optional segments and wildcards are supported:
+
+```ts
+const routes = {
+    lang:  "/:lang?/articles",
+    files: "/files/*",
+} as const;
+
+router.url("lang", { lang: "en" });    // "/en/articles"
+router.url("lang", { lang: null });    // "/articles"
+router.url("files", { "*": "img/logo.png" }); // "/files/img/logo.png"
+```
+
+---
+
+#### `router.match(route, pathname)`
+
+Matches a pathname against a route pattern. Returns a `PathMatch` object or `null`.
+
+```ts
+const match = router.match("user", "/users/42");
+match?.params.id; // "42"
+```
+
+---
+
+#### `router.useRouter(navigate, pathname)`
+
+Creates navigation helpers by injecting a `navigate` function and the current `pathname`. Designed to be called inside a framework hook.
+
+```ts
+const { to, match, path } = router.useRouter(navigate, pathname);
+
+to("about");                          // navigates to "/about"
+to("user", { id: "42" });            // navigates to "/users/42"
+match("user");                        // matches against current pathname
+path("user");                         // "/users/:id"
+```
+
+`to()` follows the same overloads as `url()` — params are required/forbidden based on the route.
+
+## Integration with react-router
+
+This package has no dependency on `react-router`. Integration lives in a separate adapter package:
+
+```ts
+import { createRouter } from "navigation-kit";
+import { useNavigate, useLocation, generatePath, matchPath } from "react-router";
+import { useMemo } from "react";
+
+export const makeRouter = <const TRoutes extends RouteMap>(routes: TRoutes) => {
+    const router = createRouter(routes, { generatePath, matchPath });
+
+    return {
+        ...router,
+        useRouter: () => {
+            const navigate = useNavigate();
+            const { pathname } = useLocation();
+            return useMemo(
+                () => router.useRouter(navigate, pathname),
+                [navigate, pathname]
+            );
+        },
+    };
+};
+```
+
+## Custom adapter
+
+Override `generatePath` and/or `matchPath` with your own implementations:
+
+```ts
+const router = createRouter(routes, {
+    generatePath: (path, params) => myGeneratePath(path, params),
+    matchPath: (pattern, pathname) => myMatchPath(pattern, pathname),
+});
+```
+
+Both have built-in defaults (implementations copied from react-router, no runtime dependency).
+
+## Navigate options
+
+Pass a second type parameter to type the options forwarded through `to()`:
+
+```ts
+import { NavigateOptions } from "react-router";
+
+const router = createRouter<typeof routes, NavigateOptions>(routes);
+
+const { to } = router.useRouter(navigate, pathname);
+to("about", undefined, { replace: true });
+to("user", { id: "42" }, { state: { from: "/" } });
+```

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./utils";

package/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);

package/lib/types/PathMatch.d.ts

@@ -0,0 +1,9 @@
+import { PathPattern } from "./PathPattern";
+export interface PathMatch<ParamKey extends string = string> {
+    params: {
+        readonly [K in ParamKey]: string | undefined;
+    };
+    pathname: string;
+    pathnameBase: string;
+    pattern: PathPattern;
+}

package/lib/types/PathMatch.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/PathParam.d.ts

@@ -0,0 +1,22 @@
+type _GetParam<Param extends string> = Param extends `${infer Name}?` ? {
+    [K in Name]?: string | null | undefined;
+} : {
+    [K in Param]: string;
+};
+type _ParseParams<Path extends string> = Path extends `${infer _Prefix}:${infer Param}/${infer Suffix}` ? _GetParam<Param> & _ParseParams<`/${Suffix}`> : Path extends `${infer _Prefix}:${infer Param}` ? _GetParam<Param> : {};
+export type ParseParams<Path extends string> = Path extends "*" ? {
+    "*": string;
+} : Path extends `${infer Rest}/*` ? {
+    "*": string;
+} & ParseParams<Rest> : _ParseParams<Path>;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type ParsedParams<Path extends string> = Simplify<ParseParams<Path> & {
+    [key in string]: string | null | undefined;
+}>;
+export type PathParam<Path extends string> = keyof ParseParams<Path> & string;
+export type ParamParseKey<Segment extends string> = [
+    PathParam<Segment>
+] extends [never] ? string : PathParam<Segment>;
+export {};

package/lib/types/PathParam.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/PathPattern.d.ts

@@ -0,0 +1,5 @@
+export type PathPattern<P extends string = string> = {
+    path: P;
+    caseSensitive?: boolean;
+    end?: boolean;
+};

package/lib/types/PathPattern.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/RouteMap.d.ts

@@ -0,0 +1,4 @@
+import { PathPattern } from "./PathPattern";
+export type RouteMap = {
+    [key: string]: string | PathPattern;
+};

package/lib/types/RouteMap.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/RouterAdapter.d.ts

@@ -0,0 +1,6 @@
+import { PathPattern } from "./PathPattern";
+import { PathMatch } from "./PathMatch";
+export interface RouterAdapter {
+    generatePath: (path: string, params?: Record<string, string | number | null | undefined>) => string;
+    matchPath: (pattern: PathPattern, pathname: string) => PathMatch | null;
+}

package/lib/types/RouterAdapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { RouteMap } from "./RouteMap";
+export type { PathPattern } from "./PathPattern";
+export type { PathParam, ParamParseKey, ParsedParams } from "./PathParam";
+export type { PathMatch } from "./PathMatch";
+export type { RouterAdapter } from "./RouterAdapter";

package/lib/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/createRouter.d.ts

@@ -0,0 +1,34 @@
+import { RouteMap, PathPattern, PathMatch, PathParam, RouterAdapter } from "../types";
+type RouteParams<T extends string | PathPattern> = T extends string ? {
+    [K in PathParam<T>]: string | number | null;
+} : T extends PathPattern ? {
+    [K in PathParam<T["path"]>]: string | number | null;
+} : never;
+type RoutesWithParams<T extends RouteMap> = {
+    [K in keyof T]: T[K] extends string ? [PathParam<T[K]>] extends [never] ? never : K : T[K] extends PathPattern ? [PathParam<T[K]["path"]>] extends [never] ? never : K : never;
+}[keyof T];
+type RoutesWithoutParams<T extends RouteMap> = {
+    [K in keyof T]: T[K] extends string ? [PathParam<T[K]>] extends [never] ? K : never : T[K] extends PathPattern ? [PathParam<T[K]["path"]>] extends [never] ? K : never : never;
+}[keyof T];
+export declare const createRouter: <const TRoutes extends RouteMap>(routes: TRoutes, adapter?: Partial<RouterAdapter>) => {
+    pattern: <R extends keyof TRoutes>(route: R) => PathPattern;
+    path: <R extends keyof TRoutes>(route: R) => string;
+    url: {
+        <R extends RoutesWithoutParams<TRoutes>>(route: R): string;
+        <R extends RoutesWithParams<TRoutes>>(route: R, params: RouteParams<TRoutes[R]>): string;
+    };
+    match: <R extends keyof TRoutes>(route: R, pathname: string) => PathMatch | null;
+    useRouter: <TNavigateOptions = void>(navigate: (path: string, options?: TNavigateOptions) => void, pathname: string) => {
+        to: {
+            <R extends RoutesWithoutParams<TRoutes>>(route: R, params?: never, options?: TNavigateOptions): void;
+            <R extends RoutesWithParams<TRoutes>>(route: R, params: RouteParams<TRoutes[R]>, options?: TNavigateOptions): void;
+        };
+        match: <R extends keyof TRoutes>(route: R, path?: string) => PathMatch<string> | null;
+        path: <R extends keyof TRoutes>(route: R) => string;
+        url: {
+            <R extends RoutesWithoutParams<TRoutes>>(route: R): string;
+            <R extends RoutesWithParams<TRoutes>>(route: R, params: RouteParams<TRoutes[R]>): string;
+        };
+    };
+};
+export {};

package/lib/utils/createRouter.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouter = void 0;
+const generatePath_1 = require("./generatePath");
+const matchPath_1 = require("./matchPath");
+const createRouter = (routes, adapter = {}) => {
+    var _a, _b;
+    const _generatePath = (_a = adapter.generatePath) !== null && _a !== void 0 ? _a : generatePath_1.generatePath;
+    const _matchPath = (_b = adapter.matchPath) !== null && _b !== void 0 ? _b : matchPath_1.matchPath;
+    const handlePattern = (route) => {
+        const pattern = routes[route];
+        return typeof pattern === "string" ? { path: pattern } : pattern;
+    };
+    const handlePath = (route) => {
+        return handlePattern(route).path;
+    };
+    function handleUrl(route, params) {
+        return _generatePath(handlePattern(route).path, params);
+    }
+    const handleMatch = (route, pathname) => {
+        return _matchPath(handlePattern(route), pathname);
+    };
+    const handleUseRouter = (navigate, pathname) => {
+        function handleTo(route, params, options) {
+            navigate(_generatePath(handlePattern(route).path, params), options);
+        }
+        return {
+            to: handleTo,
+            match: (route, path = pathname) => handleMatch(route, path),
+            path: handlePath,
+            url: handleUrl
+        };
+    };
+    return {
+        pattern: handlePattern,
+        path: handlePath,
+        url: handleUrl,
+        match: handleMatch,
+        useRouter: handleUseRouter
+    };
+};
+exports.createRouter = createRouter;

package/lib/utils/generatePath.d.ts

@@ -0,0 +1,2 @@
+import { ParsedParams } from "../types";
+export declare function generatePath<Path extends string>(originalPath: Path, params?: ParsedParams<Path>): string;

package/lib/utils/generatePath.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePath = generatePath;
+function generatePath(originalPath, params = {}) {
+    let path = originalPath;
+    if (path.endsWith("*") && path !== "*" && !path.endsWith("/*")) {
+        path = path.replace(/\*$/, "/*");
+    }
+    const prefix = path.startsWith("/") ? "/" : "";
+    const stringify = (p) => p == null ? "" : typeof p === "string" ? p : String(p);
+    const paramsMap = params;
+    return (prefix +
+        path.split(/\/+/)
+            .map((segment, index, array) => {
+            if (index === array.length - 1 && segment === "*") {
+                return stringify(paramsMap["*"]);
+            }
+            const keyMatch = segment.match(/^:([\w-]+)(\??)(.*)/);
+            if (keyMatch) {
+                const [, key, optional, suffix] = keyMatch;
+                const param = paramsMap[key];
+                if (optional !== "?" && param == null) {
+                    throw new Error(`Missing ":${key}" param`);
+                }
+                return encodeURIComponent(stringify(param)) + suffix;
+            }
+            return segment.replace(/\?$/g, "");
+        })
+            .filter(Boolean)
+            .join("/"));
+}

package/lib/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./createRouter";
+export * from "./generatePath";
+export * from "./matchPath";

package/lib/utils/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./createRouter"), exports);
+__exportStar(require("./generatePath"), exports);
+__exportStar(require("./matchPath"), exports);

package/lib/utils/matchPath.d.ts

@@ -0,0 +1,2 @@
+import { PathPattern, PathMatch, ParamParseKey } from "../types";
+export declare function matchPath<Path extends string>(pattern: PathPattern<Path> | Path, pathname: string): PathMatch<ParamParseKey<Path>> | null;

package/lib/utils/matchPath.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPath = matchPath;
+function compilePath(path, caseSensitive = false, end = true) {
+    const params = [];
+    let regexpSource = "^" + path
+        .replace(/\/*\*?$/, "")
+        .replace(/^\/*/, "/")
+        .replace(/[\\.*+^${}|()[\]]/g, "\\$&")
+        .replace(/\/:([\w-]+)(\?)?/g, (match, paramName, isOptional, index, str) => {
+        params.push({ paramName, isOptional: isOptional != null });
+        if (isOptional) {
+            const nextChar = str.charAt(index + match.length);
+            if (nextChar && nextChar !== "/")
+                return "/([^\\/]*)";
+            return "(?:/([^\\/]*))?";
+        }
+        return "/([^\\/]+)";
+    })
+        .replace(/\/([\w-]+)\?(\/|$)/g, "(/$1)?$2");
+    if (path.endsWith("*")) {
+        params.push({ paramName: "*" });
+        regexpSource += path === "*" || path === "/*" ? "(.*)$" : "(?:\\/(.+)|\\/*)$";
+    }
+    else if (end) {
+        regexpSource += "\\/*$";
+    }
+    else if (path !== "" && path !== "/") {
+        regexpSource += "(?:(?=\\/|$))";
+    }
+    return [
+        !caseSensitive ? new RegExp(regexpSource, "i") : new RegExp(regexpSource),
+        params
+    ];
+}
+function matchPath(pattern, pathname) {
+    if (typeof pattern === "string") {
+        pattern = { path: pattern, caseSensitive: false, end: true };
+    }
+    const [matcher, compiledParams] = compilePath(pattern.path, pattern.caseSensitive, pattern.end);
+    const match = pathname.match(matcher);
+    if (!match)
+        return null;
+    const matchedPathname = match[0];
+    let pathnameBase = matchedPathname.replace(/(.)\/+$/, "$1");
+    const captureGroups = match.slice(1);
+    const params = compiledParams.reduce((memo, { paramName, isOptional }, index) => {
+        if (paramName === "*") {
+            const splatValue = captureGroups[index] || "";
+            pathnameBase = matchedPathname
+                .slice(0, matchedPathname.length - splatValue.length)
+                .replace(/(.)\/+$/, "$1");
+        }
+        const value = captureGroups[index];
+        memo[paramName] = isOptional && !value
+            ? undefined
+            : (value || "").replace(/%2F/g, "/");
+        return memo;
+    }, {});
+    return {
+        params: params,
+        pathname: matchedPathname,
+        pathnameBase,
+        pattern: pattern
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "navigation-kit",
+    "type": "commonjs",
+    "version": "0.0.1",
+    "author": "Kris Papercut <krispcut@gmail.com>",
+    "description": "",
+    "license": "MIT",
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "homepage": "https://github.com/kearisp/navigation-kit#readme",
+    "bugs": {
+        "url": "https://github.com/kearisp/navigation-kit/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kearisp/navigation-kit.git"
+    },
+    "scripts": {
+        "prepublishOnly": "npm run build",
+        "build": "tsc --project tsconfig.build.json",
+        "watch": "tsc -w --project tsconfig.build.json",
+        "test": "jest --colors",
+        "test-watch": "jest --colors --watchAll --coverage",
+        "make-coverage-badge": "make-coverage-badge"
+    },
+    "ts-node": {
+        "compilerOptions": {
+            "module": "CommonJS"
+        }
+    },
+    "devDependencies": {
+        "@types/jest": "^30.0.0",
+        "@types/node": "^26.0.0",
+        "jest": "^30.4.2",
+        "make-coverage-badge": "^1.2.0",
+        "ts-jest": "^29.4.11",
+        "ts-node": "^10.9.2",
+        "typescript": "^6.0.3"
+    }
+}