@tripod311/flow 0.0.0

package/README.md

@@ -0,0 +1,93 @@
+# Flow Router
+
+A minimalistic client-side router built on top of the native `history API`.  
+Perfect for SPAs, easy to embed into any project, and just a few kilobytes in size.
+
+---
+
+## Features
+
+- **Zero dependencies** — pure TypeScript/JavaScript.  
+- **Supports static, parametric, and wildcard routes.**  
+- **Automatic route prioritization (static > parametric > wildcard).**  
+- **Direct control over the history API (`pushState`, `replaceState`).**  
+- **Fallback handler for unmatched routes.**
+
+---
+
+## Installation
+
+```bash
+npm install flow-router
+```
+
+Or simply copy the file into your project.
+
+---
+
+## Example Usage
+
+```ts
+const router = new Flow();
+
+router.add("/", () => {
+  console.log("Home page");
+});
+
+router.add("/about", () => {
+  console.log("About page");
+});
+
+router.add("/user/:id", (params) => {
+  console.log("User page:", params.id);
+});
+
+router.add("/files/*", (params) => {
+  console.log("Files path:", params[0]);
+});
+
+router.setFallback(() => {
+  console.log("404 Not Found");
+});
+
+router.init();
+
+// Navigate programmatically:
+router.navigate("/about");
+router.navigate("/user/42");
+router.navigate("/files/images/avatar.png");
+```
+
+---
+
+## API
+
+### `router.init()`
+Starts listening to `popstate` events and performs the initial route matching for the current URL.
+
+### `router.deinit()`
+Stops listening to `popstate` events.
+
+### `router.add(path: string, handler: RouteHandler)`
+Registers a new route.  
+- `:param` — parametric segment.  
+- `*` — wildcard segment (must be the last one).  
+
+Examples:  
+- `/user/:id` → `{ id: "42" }`  
+- `/files/*` → `{ 0: "images/avatar.png" }`
+
+### `router.setFallback(handler: () => void)`
+Sets a fallback handler that runs when no routes match.
+
+### `router.match(path: string)`
+Performs a manual match of the given path (usually called internally).
+
+### `router.navigate(path: string, replace: boolean = false)`
+Changes the URL via `pushState` or `replaceState` and runs the matched route handler.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export type RouteHandler = (routeParams: Record<string, string>, urlParams: URLSearchParams) => void;
+export interface Route {
+    pathname: string;
+    pattern: RegExp;
+    keys: string[];
+    staticParts: number;
+    parametricParts: number;
+    handler: RouteHandler;
+}
+export declare class Flow {
+    private staticRoutes;
+    private parametricRoutes;
+    private wildcardRoutes;
+    private fallback?;
+    private stateListener;
+    constructor();
+    init(): void;
+    deinit(): void;
+    setFallback(handler: () => void): void;
+    add(path: string, handler: RouteHandler): void;
+    private injectRoute;
+    private static pathToRegex;
+    match(path: string): void;
+    navigate(path: string, replace?: boolean): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;AAErG,MAAM,WAAW,KAAK;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;CACtB;AAED,qBAAa,IAAI;IAChB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,gBAAgB,CAAe;IACvC,OAAO,CAAC,cAAc,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,aAAa,CAAa;;IAQlC,IAAI;IAMJ,MAAM;IAIN,WAAW,CAAE,OAAO,EAAE,MAAM,IAAI;IAIhC,GAAG,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;IAoCxC,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,MAAM,CAAC,WAAW;IAuB1B,KAAK,CAAE,IAAI,EAAE,MAAM;IA4CnB,QAAQ,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAe;CAShD"}

package/dist/index.js

@@ -0,0 +1,135 @@
+export class Flow {
+    staticRoutes = [];
+    parametricRoutes = [];
+    wildcardRoutes = [];
+    fallback;
+    stateListener;
+    constructor() {
+        this.stateListener = () => {
+            this.match(location.pathname);
+        };
+    }
+    init() {
+        window.addEventListener("popstate", this.stateListener);
+        this.match(location.pathname);
+    }
+    deinit() {
+        window.removeEventListener("popstate", this.stateListener);
+    }
+    setFallback(handler) {
+        this.fallback = handler;
+    }
+    add(path, handler) {
+        const { pattern, keys } = Flow.pathToRegex(path);
+        const route = {
+            pathname: path,
+            pattern: pattern,
+            keys: keys,
+            staticParts: 0,
+            parametricParts: 0,
+            handler: handler
+        };
+        let isWildCard = false;
+        const sp = path.split('/');
+        for (const hop of sp) {
+            if (hop === "*") {
+                if (sp.indexOf(hop) !== sp.length - 1) {
+                    console.warn(`Wildcard '*' should be last hop: ${path}`);
+                }
+                isWildCard = true;
+            }
+            else if (hop.charAt(0) === ':') {
+                route.parametricParts++;
+            }
+            else {
+                route.staticParts++;
+            }
+        }
+        if (isWildCard) {
+            this.injectRoute(route, this.wildcardRoutes);
+        }
+        else if (route.parametricParts > 0) {
+            this.injectRoute(route, this.parametricRoutes);
+        }
+        else {
+            this.injectRoute(route, this.staticRoutes);
+        }
+    }
+    injectRoute(route, collection) {
+        let index = 0;
+        while (index < collection.length) {
+            const r = collection[index];
+            if ((r.parametricParts < route.parametricParts) ||
+                (r.parametricParts === route.parametricParts && r.staticParts < route.staticParts)) {
+                collection.splice(index, 0, route);
+                return;
+            }
+            index++;
+        }
+        collection.push(route);
+    }
+    static pathToRegex(path) {
+        const keys = [];
+        const regex = path
+            .split("/")
+            .map(seg => {
+            if (seg.startsWith(":")) {
+                keys.push(seg.slice(1));
+                return "([^/]+)";
+            }
+            if (seg === "*") {
+                return "(.*)?";
+            }
+            return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // escape
+        })
+            .join("/");
+        return {
+            pattern: new RegExp("^" + regex + "$"),
+            keys
+        };
+    }
+    match(path) {
+        const [pathname, search = ""] = path.split("?");
+        const params = new URLSearchParams(search);
+        for (const route of this.staticRoutes) {
+            if (pathname === route.pathname) {
+                route.handler({}, params);
+                return;
+            }
+        }
+        for (const route of this.parametricRoutes) {
+            const match = pathname.match(route.pattern);
+            if (match !== null) {
+                const routeParams = {};
+                for (let i = 0; i < route.keys.length; i++) {
+                    routeParams[route.keys[i]] = match[i + 1];
+                }
+                route.handler(routeParams, params);
+                return;
+            }
+        }
+        for (const route of this.wildcardRoutes) {
+            const match = pathname.match(route.pattern);
+            if (match !== null) {
+                const routeParams = {};
+                for (let i = 0; i < route.keys.length; i++) {
+                    routeParams[route.keys[i]] = match[i + 1];
+                }
+                route.handler(routeParams, params);
+                return;
+            }
+        }
+        if (this.fallback !== undefined)
+            this.fallback();
+    }
+    navigate(path, replace = false) {
+        if (replace) {
+            history.replaceState(null, "", path);
+        }
+        else {
+            history.pushState(null, "", path);
+        }
+        this.match(path);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@tripod311/flow",
+  "version": "0.0.0",
+  "description": "Lightweight minimalistic router for single page applications",
+  "keywords": [
+    "js",
+    "ts"
+  ],
+  "license": "MIT",
+  "author": "Tripod ind.tripod@gmail.com",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tripod311/flow.git"
+  }
+}