@tinyfx/runtime 0.1.8 → 0.2.0

package/dist/router/lifecycle.js

@@ -6,6 +6,14 @@ const destroyCallbacks = [];
  *
  * - If the document is still loading, the callback runs after DOMContentLoaded.
  * - If the document is already loaded, the callback runs immediately.
+ *
+ * @param fn - The callback to run on mount
+ * @returns Nothing
+ *
+ * @example
+ * onMount(() => {
+ *   console.log("page ready");
+ * });
  */
 export function onMount(fn) {
     if (document.readyState === "loading") {
@@ -17,13 +25,26 @@ export function onMount(fn) {
 /**
  * Register a callback to run when the user navigates away from this page.
  * Fires on the browser's `pagehide` event.
+ *
+ * @param fn - The callback to run during page teardown
+ * @returns Nothing
+ *
+ * @example
+ * onDestroy(() => {
+ *   console.log("page leaving");
+ * });
  */
 export function onDestroy(fn) {
     destroyCallbacks.push(fn);
 }
 /**
  * Trigger all registered `onMount` callbacks.
- * Called by `initRouter` after matching the current route.
+ * Called by `init()` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * flushMount();
  */
 export function flushMount() {
     const run = () => mountCallbacks.forEach((fn) => fn());
@@ -36,7 +57,12 @@ export function flushMount() {
 }
 /**
  * Wire up registered `onDestroy` callbacks to the `pagehide` event.
- * Called by `initRouter` after matching the current route.
+ * Called by `init()` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * initLifecycle();
  */
 export function initLifecycle() {
     flushMount();

package/dist/router/navigate.d.ts

@@ -2,11 +2,19 @@
  * Navigate to the given path.
  * This is a full browser navigation — not a DOM swap.
  *
+ * @param path - The destination pathname or URL
+ * @returns Nothing
+ *
  * @example
  * navigate("/blog/hello-world");
  */
 export declare function navigate(path: string): void;
 /**
  * Go back one step in the browser history.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * goBack();
  */
 export declare function goBack(): void;

package/dist/router/navigate.js

@@ -4,6 +4,9 @@
  * Navigate to the given path.
  * This is a full browser navigation — not a DOM swap.
  *
+ * @param path - The destination pathname or URL
+ * @returns Nothing
+ *
  * @example
  * navigate("/blog/hello-world");
  */
@@ -12,6 +15,11 @@ export function navigate(path) {
 }
 /**
  * Go back one step in the browser history.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * goBack();
  */
 export function goBack() {
     window.history.go(-1);

package/dist/router/params.d.ts

@@ -1,19 +1,27 @@
 /**
- * Match `pattern` (e.g. "/blog/:slug") against `pathname` (e.g. "/blog/hello").
+ * Set resolved route params (called internally by init()).
  *
- * Returns true if they match, and stores any `:param` captures in the
- * module-level store so `getParam()` can retrieve them.
- *
- * Static segments must match exactly; `:param` segments match any non-empty
- * path segment.
+ * @param params - The resolved URL parameters
  */
-export declare function resolveParams(pattern: string, pathname: string): boolean;
+export declare function setParams(params: Record<string, string>): void;
 /**
  * Retrieve a URL parameter resolved for the current page.
  *
+ * @param key - The route parameter name to read
+ * @returns The decoded parameter value, or `undefined` when it is missing
+ *
  * @example
  * // On the page with route "/blog/:slug" and URL "/blog/hello-world"
  * getParam("slug"); // → "hello-world"
  */
 export declare function getParam(key: string): string | undefined;
+/**
+ * Returns a shallow copy of all currently resolved route params.
+ *
+ * @returns An object containing the current route parameters
+ *
+ * @example
+ * const params = getParams();
+ * console.log(params.slug);
+ */
 export declare function getParams(): Record<string, string>;

package/dist/router/params.js

@@ -2,37 +2,19 @@
 /** Module-level store for the current page's resolved params. */
 let currentParams = {};
 /**
- * Match `pattern` (e.g. "/blog/:slug") against `pathname` (e.g. "/blog/hello").
+ * Set resolved route params (called internally by init()).
  *
- * Returns true if they match, and stores any `:param` captures in the
- * module-level store so `getParam()` can retrieve them.
- *
- * Static segments must match exactly; `:param` segments match any non-empty
- * path segment.
+ * @param params - The resolved URL parameters
  */
-export function resolveParams(pattern, pathname) {
-    const patternParts = pattern.split("/").filter(Boolean);
-    const pathParts = pathname.split("/").filter(Boolean);
-    if (patternParts.length !== pathParts.length)
-        return false;
-    const captured = {};
-    for (let i = 0; i < patternParts.length; i++) {
-        const seg = patternParts[i];
-        if (seg.startsWith(":")) {
-            // Dynamic segment — capture the value
-            captured[seg.slice(1)] = decodeURIComponent(pathParts[i]);
-        }
-        else if (seg !== pathParts[i]) {
-            // Static segment mismatch
-            return false;
-        }
-    }
-    currentParams = captured;
-    return true;
+export function setParams(params) {
+    currentParams = params;
 }
 /**
  * Retrieve a URL parameter resolved for the current page.
  *
+ * @param key - The route parameter name to read
+ * @returns The decoded parameter value, or `undefined` when it is missing
+ *
  * @example
  * // On the page with route "/blog/:slug" and URL "/blog/hello-world"
  * getParam("slug"); // → "hello-world"
@@ -40,6 +22,15 @@ export function resolveParams(pattern, pathname) {
 export function getParam(key) {
     return currentParams[key];
 }
+/**
+ * Returns a shallow copy of all currently resolved route params.
+ *
+ * @returns An object containing the current route parameters
+ *
+ * @example
+ * const params = getParams();
+ * console.log(params.slug);
+ */
 export function getParams() {
     return Object.assign({}, currentParams);
 }

package/dist/router/path-matcher.d.ts

@@ -0,0 +1,30 @@
+export interface RouteDef {
+    /** Static segment values (null for dynamic segments) */
+    staticSegments: (string | null)[];
+    /** Param names at dynamic positions */
+    paramNames: string[];
+}
+/**
+ * Match a pre-compiled route definition against path segments.
+ *
+ * @param def - The route definition from the compiler
+ * @param pathSegments - Pre-split path segments from splitPath()
+ * @returns Captured params on match, null on mismatch
+ *
+ * @example
+ * const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+ * matchPath(def, ["blog", "hello-world"]);
+ * // Returns: { slug: "hello-world" }
+ */
+export declare function matchPath(def: RouteDef, pathSegments: string[]): Record<string, string> | null;
+/**
+ * Split a pathname into segments for matching.
+ *
+ * @param pathname - The browser pathname (e.g., "/blog/hello")
+ * @returns Array of non-empty segments
+ *
+ * @example
+ * splitPath("/blog/hello-world");
+ * // Returns: ["blog", "hello-world"]
+ */
+export declare function splitPath(pathname: string): string[];

package/dist/router/path-matcher.js

@@ -0,0 +1,45 @@
+// @tinyfx/runtime — path matcher
+// Unified path resolution with pre-split array support for compiler optimization.
+/**
+ * Match a pre-compiled route definition against path segments.
+ *
+ * @param def - The route definition from the compiler
+ * @param pathSegments - Pre-split path segments from splitPath()
+ * @returns Captured params on match, null on mismatch
+ *
+ * @example
+ * const def = { staticSegments: ["blog", null], paramNames: ["slug"] };
+ * matchPath(def, ["blog", "hello-world"]);
+ * // Returns: { slug: "hello-world" }
+ */
+export function matchPath(def, pathSegments) {
+    const { staticSegments, paramNames } = def;
+    if (staticSegments.length !== pathSegments.length)
+        return null;
+    const params = {};
+    let paramIdx = 0;
+    for (let i = 0; i < staticSegments.length; i++) {
+        const expected = staticSegments[i];
+        const actual = pathSegments[i];
+        if (expected === null) {
+            params[paramNames[paramIdx++]] = decodeURIComponent(actual);
+        }
+        else if (expected !== actual) {
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * Split a pathname into segments for matching.
+ *
+ * @param pathname - The browser pathname (e.g., "/blog/hello")
+ * @returns Array of non-empty segments
+ *
+ * @example
+ * splitPath("/blog/hello-world");
+ * // Returns: ["blog", "hello-world"]
+ */
+export function splitPath(pathname) {
+    return pathname.split("/").filter(Boolean);
+}

package/dist/router/types.d.ts

@@ -1,9 +1,22 @@
-/** Metadata for a single route, produced by the compiler. */
+/**
+ * Metadata for a single route produced by the compiler.
+ *
+ * @example
+ * const route: RouteMeta = { page: "blog-post", path: "/blog/:slug" };
+ */
 export interface RouteMeta {
     /** The page name, derived from the source filename. */
     page: string;
     /** The declared URL pattern, e.g. "/blog/:slug". */
     path: string;
 }
-/** The full route map emitted by `tinyfx build` into tinyfx.gen.ts. */
+/**
+ * The full route map emitted by `tinyfx build` into `tinyfx.gen.ts`.
+ *
+ * @example
+ * const routes: RouteMap = {
+ *   "/": { page: "index", path: "/" },
+ *   "/blog/:slug": { page: "blog-post", path: "/blog/:slug" },
+ * };
+ */
 export type RouteMap = Record<string, RouteMeta>;

package/dist/signals.d.ts

@@ -1,11 +1,32 @@
-export declare class Signal<T> {
-    private value;
-    private subs;
-    constructor(v: T);
-    get(): T;
-    set(v: T): void;
-}
+/**
+ * Creates a reactive signal function.
+ *
+ * @param v - The initial value stored by the signal
+ * @returns A callable signal that reads the current value and exposes `.set()`
+ *          to update it
+ *
+ * @example
+ * const count = signal(0);
+ * console.log(count());
+ * count.set(1);
+ */
 export declare function signal<T>(v: T): (() => T) & {
     set(v: T): void;
 };
+/**
+ * Registers and runs a reactive effect.
+ *
+ * Every signal read while `fn` runs is tracked, and the effect is re-run when
+ * any of those signal values change.
+ *
+ * @param fn - The reactive callback to execute and subscribe
+ * @returns Nothing
+ *
+ * @example
+ * const count = signal(0);
+ * effect(() => {
+ *   console.log(`count = ${count()}`);
+ * });
+ * count.set(1);
+ */
 export declare function effect(fn: () => void): void;

package/dist/signals.js

@@ -1,31 +1,51 @@
 // @tinyfx/runtime — signals
 // Minimal, explicit reactivity — no proxies, no magic.
 const effectStack = [];
-export class Signal {
-    constructor(v) {
-        this.subs = new Set();
-        this.value = v;
-    }
-    get() {
+/**
+ * Creates a reactive signal function.
+ *
+ * @param v - The initial value stored by the signal
+ * @returns A callable signal that reads the current value and exposes `.set()`
+ *          to update it
+ *
+ * @example
+ * const count = signal(0);
+ * console.log(count());
+ * count.set(1);
+ */
+export function signal(v) {
+    let value = v;
+    const subs = new Set();
+    const fn = () => {
         const running = effectStack[effectStack.length - 1];
-        if (running) {
-            this.subs.add(running);
-        }
-        return this.value;
-    }
-    set(v) {
-        if (Object.is(v, this.value))
+        if (running)
+            subs.add(running);
+        return value;
+    };
+    fn.set = (next) => {
+        if (Object.is(next, value))
             return;
-        this.value = v;
-        this.subs.forEach((fn) => fn());
-    }
-}
-export function signal(v) {
-    const s = new Signal(v);
-    const fn = () => s.get();
-    fn.set = (v) => s.set(v);
+        value = next;
+        subs.forEach((s) => s());
+    };
     return fn;
 }
+/**
+ * Registers and runs a reactive effect.
+ *
+ * Every signal read while `fn` runs is tracked, and the effect is re-run when
+ * any of those signal values change.
+ *
+ * @param fn - The reactive callback to execute and subscribe
+ * @returns Nothing
+ *
+ * @example
+ * const count = signal(0);
+ * effect(() => {
+ *   console.log(`count = ${count()}`);
+ * });
+ * count.set(1);
+ */
 export function effect(fn) {
     const run = () => {
         effectStack.push(run);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyfx/runtime",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Minimal frontend runtime — signals, DOM helpers, typed HTTP, DTO mapping",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,10 +17,14 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "@vitest/coverage-v8": "^4.1.2",
+    "jsdom": "^29.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
   },
   "license": "MIT"
 }