@tinyfx/runtime 0.1.6 → 0.1.9

package/dist/http/data.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Error thrown for non-success HTTP responses.
+ *
+ * @example
+ * try {
+ *   await http.get("/posts");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.error(error.status, error.url);
+ *   }
+ * }
+ */
 export declare class HttpError extends Error {
     readonly status: number;
     readonly statusText: string;
@@ -6,15 +18,51 @@ export declare class HttpError extends Error {
     readonly response?: Response | undefined;
     constructor(status: number, statusText: string, url: string, method: string, response?: Response | undefined);
 }
+/**
+ * Error thrown when a request times out.
+ *
+ * @example
+ * try {
+ *   await http.get("/slow", { timeout: 100 });
+ * } catch (error) {
+ *   if (error instanceof HttpTimeoutError) {
+ *     console.error(error.timeout);
+ *   }
+ * }
+ */
 export declare class HttpTimeoutError extends Error {
     readonly url: string;
     readonly timeout: number;
     constructor(url: string, timeout: number);
 }
+/**
+ * Error thrown when a JSON response cannot be parsed.
+ *
+ * @example
+ * try {
+ *   await http.get("/broken-json");
+ * } catch (error) {
+ *   if (error instanceof HttpParseError) {
+ *     console.error(error.url);
+ *   }
+ * }
+ */
 export declare class HttpParseError extends Error {
     readonly url: string;
     constructor(message: string, url: string);
 }
+/**
+ * Hook that can rewrite an outgoing request before `fetch` runs.
+ *
+ * @example
+ * const addToken: RequestInterceptor = (url, options) => ({
+ *   url,
+ *   options: {
+ *     ...options,
+ *     headers: { ...options.headers, Authorization: "Bearer token" },
+ *   },
+ * });
+ */
 export interface RequestInterceptor {
     (url: string, options: RequestInit): Promise<{
         url: string;
@@ -24,9 +72,28 @@ export interface RequestInterceptor {
         options: RequestInit;
     };
 }
+/**
+ * Hook that can inspect or replace a response before TinyFX handles it.
+ *
+ * @example
+ * const logResponse: ResponseInterceptor = (response) => {
+ *   console.log(response.status);
+ *   return response;
+ * };
+ */
 export interface ResponseInterceptor {
     (response: Response): Promise<Response> | Response;
 }
+/**
+ * Default options for an HTTP client created by `createHttp()`.
+ *
+ * @example
+ * const config: HttpConfig = {
+ *   baseUrl: "/api",
+ *   timeout: 5000,
+ *   retries: 1,
+ * };
+ */
 export interface HttpConfig {
     baseUrl?: string;
     headers?: Record<string, string>;
@@ -36,6 +103,15 @@ export interface HttpConfig {
     requestInterceptors?: RequestInterceptor[];
     responseInterceptors?: ResponseInterceptor[];
 }
+/**
+ * Per-request overrides for an HTTP call.
+ *
+ * @example
+ * const options: RequestOptions = {
+ *   params: { page: 2 },
+ *   timeout: 1000,
+ * };
+ */
 export interface RequestOptions {
     headers?: Record<string, string>;
     timeout?: number;

package/dist/http/data.js

@@ -1,3 +1,15 @@
+/**
+ * Error thrown for non-success HTTP responses.
+ *
+ * @example
+ * try {
+ *   await http.get("/posts");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.error(error.status, error.url);
+ *   }
+ * }
+ */
 export class HttpError extends Error {
     constructor(status, statusText, url, method, response) {
         super(`HTTP ${status} ${statusText}: ${method} ${url}`);
@@ -9,6 +21,18 @@ export class HttpError extends Error {
         this.name = "HttpError";
     }
 }
+/**
+ * Error thrown when a request times out.
+ *
+ * @example
+ * try {
+ *   await http.get("/slow", { timeout: 100 });
+ * } catch (error) {
+ *   if (error instanceof HttpTimeoutError) {
+ *     console.error(error.timeout);
+ *   }
+ * }
+ */
 export class HttpTimeoutError extends Error {
     constructor(url, timeout) {
         super(`Request timeout after ${timeout}ms: ${url}`);
@@ -17,6 +41,18 @@ export class HttpTimeoutError extends Error {
         this.name = "HttpTimeoutError";
     }
 }
+/**
+ * Error thrown when a JSON response cannot be parsed.
+ *
+ * @example
+ * try {
+ *   await http.get("/broken-json");
+ * } catch (error) {
+ *   if (error instanceof HttpParseError) {
+ *     console.error(error.url);
+ *   }
+ * }
+ */
 export class HttpParseError extends Error {
     constructor(message, url) {
         super(message);

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

@@ -2,6 +2,19 @@
 // Thin, typed wrapper over fetch.
 import { HttpError, HttpParseError, HttpTimeoutError } 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 : "";

package/dist/http.d.ts

@@ -1,10 +1,2 @@
-export interface HttpConfig {
-    baseUrl?: string;
-    headers?: Record<string, string>;
-}
-export declare function createHttp(config?: HttpConfig): {
-    get: <T>(url: string) => Promise<T>;
-    post: <T>(url: string, body?: unknown) => Promise<T>;
-    put: <T>(url: string, body?: unknown) => Promise<T>;
-    del: <T>(url: string) => Promise<T>;
-};
+export { createHttp } from "./http/http";
+export type { HttpConfig } from "./http/data";

package/dist/http.js

@@ -1,38 +1 @@
-// @tinyfx/runtime — HTTP client
-// Thin, typed wrapper over fetch.
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-export function createHttp(config = {}) {
-    var _a, _b;
-    const base = (_a = config.baseUrl) !== null && _a !== void 0 ? _a : "";
-    const defaultHeaders = (_b = config.headers) !== null && _b !== void 0 ? _b : {};
-    function request(method, url, body) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const headers = Object.assign({}, defaultHeaders);
-            if (body !== undefined) {
-                headers["Content-Type"] = "application/json";
-            }
-            const res = yield fetch(base + url, {
-                method,
-                headers,
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-            });
-            if (!res.ok)
-                throw new Error(`${method} ${url}: ${res.status} ${res.statusText}`);
-            return res.json();
-        });
-    }
-    return {
-        get: (url) => request("GET", url),
-        post: (url, body) => request("POST", url, body),
-        put: (url, body) => request("PUT", url, body),
-        del: (url) => request("DELETE", url),
-    };
-}
+export { createHttp } from "./http/http";

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-export { signal, effect, Signal } from "./signals";
+export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
-export { createHttp } from "./http/http";
-export type { HttpConfig } from "./http/data";
-export { Container, createToken } from "./di";
-export type { Token, TinyFxContext } from "./di";
-export { initRouter } from "./router/index";
-export { getParam } from "./router/params";
+export { createHttp } from "./http";
+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 { initRouter, getParam, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";
-export { navigate, goBack } from "./router/navigate";
+export type { TinyFxContext } from "./context";
 export type { RouteMap, RouteMeta } from "./router/types";

package/dist/index.js

@@ -1,10 +1,14 @@
 // @tinyfx/runtime — barrel export
-export { signal, effect, Signal } from "./signals";
+export { signal, effect } from "./signals";
+export { registerInstance, destroyNode } from "./each";
 export { bindText, bindAttr, bindClass } from "./dom";
-export { createHttp } from "./http/http";
-export { Container, createToken } from "./di";
-// Router — hard file-based router
-export { initRouter } from "./router/index";
-export { getParam } from "./router/params";
+export { createHttp } from "./http";
+// 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 { initRouter, getParam, navigate, goBack } from "./router/index";
 export { onMount, onDestroy } from "./router/lifecycle";
-export { navigate, goBack } from "./router/navigate";

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,40 @@
+// @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/navigate";
+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);
+    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,5 +1,8 @@
 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.
  *
@@ -9,6 +12,7 @@ export type { RouteMap };
  * navigation links.
  *
  * @param routes - The route map emitted by `tinyfx build`.
+ * @returns Nothing
  *
  * @example
  * // tinyfx.gen.ts (auto-generated — do not edit)

package/dist/router/index.js

@@ -1,7 +1,9 @@
 // @tinyfx/runtime — router entry point
-import { resolveParams } from "./params";
+import { navigate, goBack } from "./navigate";
+import { getParam, resolveParams } from "./params";
 import { initLifecycle } from "./lifecycle";
 import { highlightActiveLinks } from "./active-links";
+export { navigate, goBack, getParam };
 /**
  * Initialise the TinyFX router for the current page.
  *
@@ -11,6 +13,7 @@ import { highlightActiveLinks } from "./active-links";
  * navigation links.
  *
  * @param routes - The route map emitted by `tinyfx build`.
+ * @returns Nothing
  *
  * @example
  * // tinyfx.gen.ts (auto-generated — do not edit)