@tinyfx/runtime 0.1.8 → 0.2.0

package/dist/http/data.js

@@ -1,26 +1,18 @@
-export class HttpError extends Error {
-    constructor(status, statusText, url, method, response) {
-        super(`HTTP ${status} ${statusText}: ${method} ${url}`);
-        this.status = status;
-        this.statusText = statusText;
-        this.url = url;
-        this.method = method;
-        this.response = response;
-        this.name = "HttpError";
-    }
+export function httpError(status, statusText, url, method, response) {
+    return { kind: "http", status, statusText, url, method, response };
 }
-export class HttpTimeoutError extends Error {
-    constructor(url, timeout) {
-        super(`Request timeout after ${timeout}ms: ${url}`);
-        this.url = url;
-        this.timeout = timeout;
-        this.name = "HttpTimeoutError";
-    }
+export function timeoutError(url, timeout) {
+    return { kind: "timeout", url, timeout };
 }
-export class HttpParseError extends Error {
-    constructor(message, url) {
-        super(message);
-        this.url = url;
-        this.name = "HttpParseError";
-    }
+export function parseError(message, url) {
+    return { kind: "parse", message, url };
+}
+export function isHttpError(err) {
+    return typeof err === "object" && err !== null && "kind" in err && err.kind === "http";
+}
+export function isTimeoutError(err) {
+    return typeof err === "object" && err !== null && "kind" in err && err.kind === "timeout";
+}
+export function isParseError(err) {
+    return typeof err === "object" && err !== null && "kind" in err && err.kind === "parse";
 }

package/dist/http/helper.d.ts

@@ -1,2 +1,22 @@
+/**
+ * Builds a request URL by combining a base path with optional query params.
+ *
+ * @param url - The request path or URL fragment
+ * @param base - The configured base URL prefix
+ * @param params - Optional query parameters to append
+ * @returns The final request URL string
+ *
+ * @example
+ * buildUrl("/posts", "/api", { page: 2, published: true });
+ */
 export declare function buildUrl(url: string, base: string, params?: Record<string, string | number | boolean>): string;
+/**
+ * Waits for a number of milliseconds.
+ *
+ * @param ms - The delay duration in milliseconds
+ * @returns A promise that resolves after the delay completes
+ *
+ * @example
+ * await sleep(250);
+ */
 export declare function sleep(ms: number): Promise<void>;

package/dist/http/helper.js

@@ -1,3 +1,14 @@
+/**
+ * Builds a request URL by combining a base path with optional query params.
+ *
+ * @param url - The request path or URL fragment
+ * @param base - The configured base URL prefix
+ * @param params - Optional query parameters to append
+ * @returns The final request URL string
+ *
+ * @example
+ * buildUrl("/posts", "/api", { page: 2, published: true });
+ */
 export function buildUrl(url, base, params) {
     const fullUrl = base + url;
     if (!params || Object.keys(params).length === 0)
@@ -8,6 +19,15 @@ export function buildUrl(url, base, params) {
     });
     return urlObj.toString().replace(urlObj.origin, '');
 }
+/**
+ * Waits for a number of milliseconds.
+ *
+ * @param ms - The delay duration in milliseconds
+ * @returns A promise that resolves after the delay completes
+ *
+ * @example
+ * await sleep(250);
+ */
 export async function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }

package/dist/http/http.d.ts

@@ -1,4 +1,17 @@
 import { HttpConfig, RequestOptions } from "./data";
+/**
+ * Creates a typed HTTP client around `fetch`.
+ *
+ * The client exposes `get`, `post`, `put`, `patch`, `del`, and `delete`
+ * helpers and applies the default configuration to every request.
+ *
+ * @param config - Default HTTP configuration such as base URL, headers, and retry policy
+ * @returns An object containing typed request methods
+ *
+ * @example
+ * const http = createHttp({ baseUrl: "/api", timeout: 5000 });
+ * const posts = await http.get<{ id: number; title: string }[]>("/posts");
+ */
 export declare function createHttp(config?: HttpConfig): {
     get: <T>(url: string, options?: RequestOptions) => Promise<T>;
     post: <T>(url: string, body?: unknown, options?: RequestOptions) => Promise<T>;

package/dist/http/http.js

@@ -1,7 +1,20 @@
 // @tinyfx/runtime — HTTP client
 // Thin, typed wrapper over fetch.
-import { HttpError, HttpParseError, HttpTimeoutError } from "./data";
+import { httpError, timeoutError, parseError, isHttpError } from "./data";
 import { buildUrl, sleep } from "./helper";
+/**
+ * Creates a typed HTTP client around `fetch`.
+ *
+ * The client exposes `get`, `post`, `put`, `patch`, `del`, and `delete`
+ * helpers and applies the default configuration to every request.
+ *
+ * @param config - Default HTTP configuration such as base URL, headers, and retry policy
+ * @returns An object containing typed request methods
+ *
+ * @example
+ * const http = createHttp({ baseUrl: "/api", timeout: 5000 });
+ * const posts = await http.get<{ id: number; title: string }[]>("/posts");
+ */
 export function createHttp(config = {}) {
     var _a, _b, _c, _d, _e, _f, _g;
     const base = (_a = config.baseUrl) !== null && _a !== void 0 ? _a : "";
@@ -60,7 +73,7 @@ export function createHttp(config = {}) {
                         if ((_b = options.signal) === null || _b === void 0 ? void 0 : _b.aborted) {
                             throw err; // User cancelled
                         }
-                        throw new HttpTimeoutError(requestUrl, timeoutMs);
+                        throw timeoutError(requestUrl, timeoutMs);
                     }
                     throw err;
                 }
@@ -72,7 +85,7 @@ export function createHttp(config = {}) {
                     res = await interceptor(res);
                 }
                 if (!res.ok) {
-                    throw new HttpError(res.status, res.statusText, requestUrl, method, res);
+                    throw httpError(res.status, res.statusText, requestUrl, method, res);
                 }
                 // Parse response based on content type
                 const contentType = res.headers.get("content-type") || "";
@@ -85,7 +98,7 @@ export function createHttp(config = {}) {
                         return JSON.parse(text);
                     }
                     catch (err) {
-                        throw new HttpParseError(`Failed to parse JSON response: ${err instanceof Error ? err.message : "Unknown error"}`, requestUrl);
+                        throw parseError(`Failed to parse JSON response: ${err instanceof Error ? err.message : "Unknown error"}`, requestUrl);
                     }
                 }
                 if (contentType.includes("text/")) {
@@ -102,8 +115,8 @@ export function createHttp(config = {}) {
             }
             catch (err) {
                 // Retry logic for network errors or 5xx errors
-                const shouldRetry = attempts < maxAttempts &&
-                    (!(err instanceof HttpError) || (err.status >= 500 && err.status < 600));
+                const is5xx = isHttpError(err) && err.status >= 500 && err.status < 600;
+                const shouldRetry = attempts < maxAttempts && (!isHttpError(err) || is5xx);
                 if (shouldRetry) {
                     await sleep(retryDelay * attempts);
                     continue;

package/dist/index.d.ts

@@ -1,7 +1,15 @@
 export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
 export { createHttp } from "./http";
-export { initRouter, getParam, navigate, goBack } from "./router/index";
+export { registerComponent, getComponentFactory, mountComponents } from "./registry";
+export { registerPage, getPageModule, runPageInit } from "./page-registry";
+export { markMounted, isMounted } from "./mount-state";
+export { matchPath, splitPath } from "./router/path-matcher";
+export type { RouteDef } from "./router/path-matcher";
+export { init } from "./init";
+export type { InitConfig } from "./init";
+export { getParam, getParams, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";
 export type { TinyFxContext } from "./context";
-export type { RouteMap, RouteMeta } from "./router/types";
+export type { RouteMap, RouteMeta } from "./router/index";

package/dist/index.js

@@ -1,6 +1,14 @@
 // @tinyfx/runtime — barrel export
 export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
 export { createHttp } from "./http";
-export { initRouter, getParam, navigate, goBack } from "./router/index";
+// New decoupled APIs
+export { registerComponent, getComponentFactory, mountComponents } from "./registry";
+export { registerPage, getPageModule, runPageInit } from "./page-registry";
+export { markMounted, isMounted } from "./mount-state";
+export { matchPath, splitPath } from "./router/path-matcher";
+export { init } from "./init";
+// Keep existing router exports
+export { getParam, getParams, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";

package/dist/init.d.ts

@@ -0,0 +1,12 @@
+import type { TinyFxContext } from "./context";
+import type { RouteDef } from "./router/path-matcher";
+export interface InitConfig {
+    routes: Record<string, RouteDef>;
+    setupDirectives?: (ctx: TinyFxContext) => void;
+}
+export interface InitResult {
+    matchedPath: string;
+    params: Record<string, string>;
+    instances: any[];
+}
+export declare function init(config: InitConfig): InitResult | null;

package/dist/init.js

@@ -0,0 +1,42 @@
+// @tinyfx/runtime — unified initialization
+// Single entry point for TinyFX bootstrap.
+import { matchPath, splitPath } from "./router/path-matcher";
+import { initLifecycle } from "./router/lifecycle";
+import { highlightActiveLinks } from "./router/active-links";
+import { navigate } from "./router/index";
+import { setParams } from "./router/params";
+import { mountComponents } from "./registry";
+import { runPageInit } from "./page-registry";
+let initialized = false;
+export function init(config) {
+    if (initialized)
+        return null;
+    initialized = true;
+    const pathname = window.location.pathname;
+    const pathSegments = splitPath(pathname);
+    let matchedPath = null;
+    let params = {};
+    for (const [path, def] of Object.entries(config.routes)) {
+        const result = matchPath(def, pathSegments);
+        if (result) {
+            matchedPath = path;
+            params = result;
+            break;
+        }
+    }
+    if (!matchedPath) {
+        console.warn(`[tinyfx] No route matched for pathname: "${pathname}". ` +
+            "Check that a page file exists for this URL in src/pages/.");
+        return null;
+    }
+    initLifecycle();
+    highlightActiveLinks(pathname);
+    setParams(params);
+    const ctx = { params, navigate };
+    const instances = mountComponents(ctx);
+    if (config.setupDirectives) {
+        config.setupDirectives(ctx);
+    }
+    runPageInit(matchedPath, ctx);
+    return { matchedPath, params, instances };
+}

package/dist/mount-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mark an element as mounted. Returns false if already mounted.
+ *
+ * @param el - The element to mark
+ * @returns true if newly marked, false if already mounted
+ *
+ * @example
+ * if (!markMounted(el)) return undefined;
+ */
+export declare function markMounted(el: HTMLElement): boolean;
+/**
+ * Check if an element has been marked as mounted.
+ *
+ * @param el - The element to check
+ * @returns true if the element is marked as mounted
+ */
+export declare function isMounted(el: HTMLElement): boolean;

package/dist/mount-state.js

@@ -0,0 +1,27 @@
+// @tinyfx/runtime — mount state tracking
+// WeakSet-based mount tracking that is safe for minifier mangling.
+const mounted = new WeakSet();
+/**
+ * Mark an element as mounted. Returns false if already mounted.
+ *
+ * @param el - The element to mark
+ * @returns true if newly marked, false if already mounted
+ *
+ * @example
+ * if (!markMounted(el)) return undefined;
+ */
+export function markMounted(el) {
+    if (mounted.has(el))
+        return false;
+    mounted.add(el);
+    return true;
+}
+/**
+ * Check if an element has been marked as mounted.
+ *
+ * @param el - The element to check
+ * @returns true if the element is marked as mounted
+ */
+export function isMounted(el) {
+    return mounted.has(el);
+}

package/dist/page-registry.d.ts

@@ -0,0 +1,31 @@
+import type { TinyFxContext } from "./context";
+type PageModule = {
+    init?: (el: HTMLElement, ctx: TinyFxContext) => void;
+};
+/**
+ * Register a page module by its route path.
+ *
+ * @param path - The route path (e.g., "/blog/:slug")
+ * @param module - The page module object with optional init()
+ * @returns Nothing
+ *
+ * @example
+ * registerPage("/blog/:slug", PageModule);
+ */
+export declare function registerPage(path: string, module: PageModule): void;
+/**
+ * Retrieve a registered page module.
+ *
+ * @param path - The route path to look up
+ * @returns The page module, or undefined if not registered
+ */
+export declare function getPageModule(path: string): PageModule | undefined;
+/**
+ * Run the init() function for a registered page module.
+ *
+ * @param path - The route path of the page to initialize
+ * @param ctx - The TinyFx context to pass to page init
+ * @returns Nothing
+ */
+export declare function runPageInit(path: string, ctx: TinyFxContext): void;
+export {};

package/dist/page-registry.js

@@ -0,0 +1,38 @@
+// @tinyfx/runtime — page module registry
+// Decoupled page module registration for tree-shakable bundles.
+const modules = new Map();
+/**
+ * Register a page module by its route path.
+ *
+ * @param path - The route path (e.g., "/blog/:slug")
+ * @param module - The page module object with optional init()
+ * @returns Nothing
+ *
+ * @example
+ * registerPage("/blog/:slug", PageModule);
+ */
+export function registerPage(path, module) {
+    modules.set(path, module);
+}
+/**
+ * Retrieve a registered page module.
+ *
+ * @param path - The route path to look up
+ * @returns The page module, or undefined if not registered
+ */
+export function getPageModule(path) {
+    return modules.get(path);
+}
+/**
+ * Run the init() function for a registered page module.
+ *
+ * @param path - The route path of the page to initialize
+ * @param ctx - The TinyFx context to pass to page init
+ * @returns Nothing
+ */
+export function runPageInit(path, ctx) {
+    const mod = modules.get(path);
+    if (typeof (mod === null || mod === void 0 ? void 0 : mod.init) === "function") {
+        mod.init(document.body, ctx);
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,31 @@
+import type { TinyFxContext } from "./context";
+type ComponentFactory = (el: HTMLElement, ctx: TinyFxContext) => any;
+/**
+ * Register a component factory by name.
+ *
+ * @param name - The component name (matches `data-component` attribute)
+ * @param factory - A function that mounts the component and returns an instance
+ * @returns Nothing
+ *
+ * @example
+ * registerComponent("Button", (el, ctx) => {
+ *   return ButtonModule.mount(el, ctx);
+ * });
+ */
+export declare function registerComponent(name: string, factory: ComponentFactory): void;
+/**
+ * Retrieve a registered component factory.
+ *
+ * @param name - The component name to look up
+ * @returns The factory function, or undefined if not registered
+ */
+export declare function getComponentFactory(name: string): ComponentFactory | undefined;
+/**
+ * Mount all registered components found within a root element.
+ *
+ * @param ctx - The TinyFx context to pass to each component
+ * @param root - The root element to scan (defaults to document)
+ * @returns Array of mounted component instances
+ */
+export declare function mountComponents(ctx: TinyFxContext, root?: Document | HTMLElement): any[];
+export {};

package/dist/registry.js

@@ -0,0 +1,49 @@
+// @tinyfx/runtime — component registry
+// Decoupled component registration for tree-shakable bundles.
+const factories = new Map();
+/**
+ * Register a component factory by name.
+ *
+ * @param name - The component name (matches `data-component` attribute)
+ * @param factory - A function that mounts the component and returns an instance
+ * @returns Nothing
+ *
+ * @example
+ * registerComponent("Button", (el, ctx) => {
+ *   return ButtonModule.mount(el, ctx);
+ * });
+ */
+export function registerComponent(name, factory) {
+    factories.set(name, factory);
+}
+/**
+ * Retrieve a registered component factory.
+ *
+ * @param name - The component name to look up
+ * @returns The factory function, or undefined if not registered
+ */
+export function getComponentFactory(name) {
+    return factories.get(name);
+}
+/**
+ * Mount all registered components found within a root element.
+ *
+ * @param ctx - The TinyFx context to pass to each component
+ * @param root - The root element to scan (defaults to document)
+ * @returns Array of mounted component instances
+ */
+export function mountComponents(ctx, root = document) {
+    const instances = [];
+    root.querySelectorAll("[data-component]").forEach((el) => {
+        const name = el.getAttribute("data-component");
+        if (!name)
+            return;
+        const factory = factories.get(name);
+        if (!factory)
+            return;
+        const inst = factory(el, ctx);
+        if (inst)
+            instances.push(inst);
+    });
+    return instances;
+}

package/dist/router/active-links.d.ts

@@ -5,6 +5,9 @@
  * Only the pathname portion of each href is compared (query strings and
  * fragments are ignored).
  *
+ * @param pathname - The pathname to compare each link against
+ * @returns Nothing
+ *
  * @example
  * // In a nav: <a href="/blog">Blog</a>
  * // On the /blog page this element will get data-active="true"

package/dist/router/active-links.js

@@ -6,6 +6,9 @@
  * Only the pathname portion of each href is compared (query strings and
  * fragments are ignored).
  *
+ * @param pathname - The pathname to compare each link against
+ * @returns Nothing
+ *
  * @example
  * // In a nav: <a href="/blog">Blog</a>
  * // On the /blog page this element will get data-active="true"

package/dist/router/index.d.ts

@@ -1,24 +1,23 @@
-import type { RouteMap } from "./types";
-import { navigate, goBack } from "./navigate";
-import { getParam } from "./params";
-export type { RouteMap };
-export { navigate, goBack, getParam };
 /**
- * Initialise the TinyFX router for the current page.
- *
- * Called automatically from the compiler-generated `tinyfx.gen.ts` on every
- * page load.  Matches `window.location.pathname` against the compiled route
- * map, resolves URL params, starts lifecycle hooks, and highlights active
- * navigation links.
- *
- * @param routes - The route map emitted by `tinyfx build`.
- *
- * @example
- * // tinyfx.gen.ts (auto-generated — do not edit)
- * initRouter({
- *   "/":          { page: "home",      path: "/" },
- *   "/blog":      { page: "blog",      path: "/blog" },
- *   "/blog/:slug":{ page: "blog-post", path: "/blog/:slug" },
- * });
+ * Metadata for a single route produced by the compiler.
  */
-export declare function initRouter(routes: RouteMap): void;
+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`.
+ */
+export type RouteMap = Record<string, RouteMeta>;
+/**
+ * Navigate to the given path.
+ * This is a full browser navigation — not a DOM swap.
+ */
+export declare function navigate(path: string): void;
+/**
+ * Go back one step in the browser history.
+ */
+export declare function goBack(): void;
+export { getParam, getParams } from "./params";

package/dist/router/index.js

@@ -1,38 +1,15 @@
-// @tinyfx/runtime — router entry point
-import { navigate, goBack } from "./navigate";
-import { getParam, resolveParams } from "./params";
-import { initLifecycle } from "./lifecycle";
-import { highlightActiveLinks } from "./active-links";
-export { navigate, goBack, getParam };
+// @tinyfx/runtime — router utilities
 /**
- * Initialise the TinyFX router for the current page.
- *
- * Called automatically from the compiler-generated `tinyfx.gen.ts` on every
- * page load.  Matches `window.location.pathname` against the compiled route
- * map, resolves URL params, starts lifecycle hooks, and highlights active
- * navigation links.
- *
- * @param routes - The route map emitted by `tinyfx build`.
- *
- * @example
- * // tinyfx.gen.ts (auto-generated — do not edit)
- * initRouter({
- *   "/":          { page: "home",      path: "/" },
- *   "/blog":      { page: "blog",      path: "/blog" },
- *   "/blog/:slug":{ page: "blog-post", path: "/blog/:slug" },
- * });
+ * Navigate to the given path.
+ * This is a full browser navigation — not a DOM swap.
  */
-export function initRouter(routes) {
-    const pathname = window.location.pathname;
-    for (const pattern of Object.keys(routes)) {
-        if (resolveParams(pattern, pathname)) {
-            // Match found
-            initLifecycle();
-            highlightActiveLinks(pathname);
-            return;
-        }
-    }
-    // No route matched — log a warning and do nothing else.
-    console.warn(`[tinyfx] No route matched for pathname: "${pathname}". ` +
-        "Check that a page file exists for this URL in src/pages/.");
+export function navigate(path) {
+    window.location.href = path;
 }
+/**
+ * Go back one step in the browser history.
+ */
+export function goBack() {
+    window.history.go(-1);
+}
+export { getParam, getParams } from "./params";

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.
+ * Called by `init()` 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.
+ * Called by `init()` after matching the current route.
+ *
+ * @returns Nothing
+ *
+ * @example
+ * initLifecycle();
  */
 export declare function initLifecycle(): void;
 export {};