@tinyfx/runtime 0.1.6 → 0.1.9

package/dist/router/lifecycle.d.ts

@@ -4,21 +4,47 @@ type LifecycleCallback = () => void;
  *
  * - 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 declare function onMount(fn: LifecycleCallback): void;
 /**
  * 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 declare function onDestroy(fn: LifecycleCallback): void;
 /**
  * Trigger all registered `onMount` callbacks.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * flushMount();
  */
 export declare function flushMount(): void;
 /**
  * Wire up registered `onDestroy` callbacks to the `pagehide` event.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * initLifecycle();
  */
 export declare function initLifecycle(): void;
 export {};

package/dist/router/lifecycle.js

@@ -6,13 +6,33 @@ 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) {
-    mountCallbacks.push(fn);
+    if (document.readyState === "loading") {
+        mountCallbacks.push(fn);
+        return;
+    }
+    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);
@@ -20,6 +40,11 @@ export function onDestroy(fn) {
 /**
  * Trigger all registered `onMount` callbacks.
  * Called by `initRouter` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * flushMount();
  */
 export function flushMount() {
     const run = () => mountCallbacks.forEach((fn) => fn());
@@ -33,6 +58,11 @@ export function flushMount() {
 /**
  * Wire up registered `onDestroy` callbacks to the `pagehide` event.
  * Called by `initRouter` 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

@@ -6,13 +6,33 @@
  *
  * Static segments must match exactly; `:param` segments match any non-empty
  * path segment.
+ *
+ * @param pattern - The route pattern produced by the compiler
+ * @param pathname - The current browser pathname
+ * @returns `true` when the pathname matches the pattern, otherwise `false`
+ *
+ * @example
+ * resolveParams("/blog/:slug", "/blog/hello-world");
  */
 export declare function resolveParams(pattern: string, pathname: string): boolean;
 /**
  * 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

@@ -9,6 +9,13 @@ let currentParams = {};
  *
  * Static segments must match exactly; `:param` segments match any non-empty
  * path segment.
+ *
+ * @param pattern - The route pattern produced by the compiler
+ * @param pathname - The current browser pathname
+ * @returns `true` when the pathname matches the pattern, otherwise `false`
+ *
+ * @example
+ * resolveParams("/blog/:slug", "/blog/hello-world");
  */
 export function resolveParams(pattern, pathname) {
     const patternParts = pattern.split("/").filter(Boolean);
@@ -33,6 +40,9 @@ export function resolveParams(pattern, pathname) {
 /**
  * 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,3 +50,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,3 +1,16 @@
+/**
+ * Reactive value container used by TinyFX signals.
+ *
+ * Reading the value through {@link Signal.get} during an active effect records
+ * that effect as a subscriber. Writing through {@link Signal.set} re-runs the
+ * affected subscribers.
+ *
+ * @example
+ * const count = new Signal(0);
+ * console.log(count.get());
+ * count.set(1);
+ * console.log(count.get());
+ */
 export declare class Signal<T> {
     private value;
     private subs;
@@ -5,7 +18,35 @@ export declare class Signal<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,6 +1,19 @@
 // @tinyfx/runtime — signals
 // Minimal, explicit reactivity — no proxies, no magic.
 const effectStack = [];
+/**
+ * Reactive value container used by TinyFX signals.
+ *
+ * Reading the value through {@link Signal.get} during an active effect records
+ * that effect as a subscriber. Writing through {@link Signal.set} re-runs the
+ * affected subscribers.
+ *
+ * @example
+ * const count = new Signal(0);
+ * console.log(count.get());
+ * count.set(1);
+ * console.log(count.get());
+ */
 export class Signal {
     constructor(v) {
         this.subs = new Set();
@@ -20,12 +33,40 @@ export class Signal {
         this.subs.forEach((fn) => fn());
     }
 }
+/**
+ * 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) {
     const s = new Signal(v);
     const fn = () => s.get();
     fn.set = (v) => s.set(v);
     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.6",
+  "version": "0.1.9",
   "description": "Minimal frontend runtime — signals, DOM helpers, typed HTTP, DTO mapping",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,6 @@
     "./signals": "./dist/signals.js",
     "./dom": "./dist/dom.js",
     "./http": "./dist/http.js",
-    "./di": "./dist/di.js",
     "./router": "./dist/router/index.js"
   },
   "files": [
@@ -18,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"
 }