@askrjs/askr 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,446 @@
+import { J as JSXElement, P as Props } from './types-DUDmnzD8.cjs';
+export { Fragment, jsx, jsxs } from './jsx/jsx-runtime.cjs';
+
+/**
+ * Context system: lexical scope + render-time snapshots
+ *
+ * CORE SEMANTIC (Option A — Snapshot-Based):
+ * ============================================
+ * An async resource observes the context of the render that created it.
+ * Context changes only take effect via re-render, not magically mid-await.
+ *
+ * This ensures:
+ * - Deterministic behavior
+ * - Concurrency safety
+ * - Replayable execution
+ * - Debuggability
+ *
+ * INVARIANTS:
+ * - readContext() only works during component render (has currentContextFrame)
+ * - Each render captures a context snapshot
+ * - Async continuations see the snapshot from render start (frozen)
+ * - Provider (Scope) creates a new frame that shadows parent
+ * - Context updates require re-render to take effect
+ */
+
+type ContextKey = symbol;
+interface Context<T> {
+    readonly key: ContextKey;
+    readonly defaultValue: T;
+    readonly Scope: (props: {
+        value: T;
+        children?: unknown;
+    }) => JSXElement;
+}
+interface ContextFrame {
+    parent: ContextFrame | null;
+    values: Map<ContextKey, unknown> | null;
+}
+declare function defineContext<T>(defaultValue: T): Context<T>;
+declare function readContext<T>(context: Context<T>): T;
+
+/**
+ * Component instance lifecycle management
+ * Internal only — users never see this
+ */
+
+type ComponentFunction = (props: Props, context?: {
+    signal: AbortSignal;
+}) => JSXElement | VNode$1 | string | number | null;
+type VNode$1 = {
+    type: string;
+    props?: Props;
+    children?: (string | VNode$1 | null | undefined | false)[];
+};
+interface ComponentInstance {
+    id: string;
+    fn: ComponentFunction;
+    props: Props;
+    target: Element | null;
+    mounted: boolean;
+    abortController: AbortController;
+    ssr?: boolean;
+    stateValues: State<unknown>[];
+    evaluationGeneration: number;
+    notifyUpdate: (() => void) | null;
+    _pendingFlushTask?: () => void;
+    _pendingRunTask?: () => void;
+    _enqueueRun?: () => void;
+    stateIndexCheck: number;
+    expectedStateIndices: number[];
+    firstRenderComplete: boolean;
+    mountOperations: Array<() => void | (() => void) | Promise<void | (() => void)>>;
+    cleanupFns: Array<() => void>;
+    hasPendingUpdate: boolean;
+    ownerFrame: ContextFrame | null;
+    isRoot?: boolean;
+    _currentRenderToken?: number;
+    lastRenderToken?: number;
+    _pendingReadStates?: Set<State<unknown>>;
+    _lastReadStates?: Set<State<unknown>>;
+}
+/**
+ * Get the abort signal for the current component
+ * Used to cancel async operations on unmount/navigation
+ *
+ * The signal is guaranteed to be aborted when:
+ * - Component unmounts
+ * - Navigation occurs (different route)
+ * - Parent is destroyed
+ *
+ * IMPORTANT: getSignal() must be called during component render execution.
+ * It captures the current component instance from context.
+ *
+ * @returns AbortSignal that will be aborted when component unmounts
+ * @throws Error if called outside component execution
+ *
+ * @example
+ * ```ts
+ * // ✅ Correct: called during render, used in async operation
+ * export async function UserPage({ id }: { id: string }) {
+ *   const signal = getSignal();
+ *   const user = await fetch(`/api/users/${id}`, { signal });
+ *   return <div>{user.name}</div>;
+ * }
+ *
+ * // ✅ Correct: passed to event handler
+ * export function Button() {
+ *   const signal = getSignal();
+ *   return {
+ *     type: 'button',
+ *     props: {
+ *       onClick: async () => {
+ *         const data = await fetch(url, { signal });
+ *       }
+ *     }
+ *   };
+ * }
+ *
+ * // ❌ Wrong: called outside component context
+ * const signal = getSignal(); // Error: not in component
+ * ```
+ */
+declare function getSignal(): AbortSignal;
+
+/**
+ * State primitive for Askr components
+ * Optimized for minimal overhead and fast updates
+ *
+ * INVARIANTS ENFORCED:
+ * - state() only callable during component render (currentInstance exists)
+ * - state() called at top-level only (indices must be monotonically increasing)
+ * - state values persist across re-renders (stored in stateValues array)
+ * - state.set() cannot be called during render (causes infinite loops)
+ * - state.set() always enqueues through scheduler (never direct mutation)
+ * - state.set() callback (notifyUpdate) always available
+ */
+
+/**
+ * State value holder - callable to read, has set method to update
+ * @example
+ * const count = state(0);
+ * count();           // read: 0
+ * count.set(1);      // write: triggers re-render
+ */
+interface State<T> {
+    (): T;
+    set(value: T): void;
+    _hasBeenRead?: boolean;
+    _readers?: Map<ComponentInstance, number>;
+}
+/**
+ * Creates a local state value for a component
+ * Optimized for:
+ * - O(1) read performance
+ * - Minimal allocation per state
+ * - Fast scheduler integration
+ *
+ * IMPORTANT: state() must be called during component render execution.
+ * It captures the current component instance from context.
+ * Calling outside a component function will throw an error.
+ *
+ * @example
+ * ```ts
+ * // ✅ Correct: called during render
+ * export function Counter() {
+ *   const count = state(0);
+ *   return { type: 'button', children: [count()] };
+ * }
+ *
+ * // ❌ Wrong: called outside component
+ * const count = state(0);
+ * export function BadComponent() {
+ *   return { type: 'div' };
+ * }
+ * ```
+ */
+declare function state<T>(initialValue: T): State<T>;
+
+declare function scheduleEventHandler(handler: EventListener): EventListener;
+
+interface DataResult<T> {
+    value: T | null;
+    pending: boolean;
+    error: Error | null;
+    refresh(): void;
+}
+/**
+ * Resource primitive — simple, deterministic async primitive
+ * Usage: resource(fn, deps)
+ * - fn receives { signal }
+ * - captures execution context once at creation (synchronous step only)
+ * - executes at most once per generation; stale async results are ignored
+ * - refresh() cancels in-flight execution, increments generation and re-runs
+ * - exposes { value, pending, error, refresh }
+ * - during SSR, async results are disallowed and will throw synchronously
+ */
+declare function resource<T>(fn: (opts: {
+    signal: AbortSignal;
+}) => Promise<T> | T, deps?: unknown[]): DataResult<T>;
+
+/**
+ * Route definition and matching
+ * Supports dynamic route registration for micro frontends
+ *
+ * Optimization: Index by depth but maintain insertion order within each depth
+ */
+interface RouteHandler {
+    (params: Record<string, string>, context?: {
+        signal: AbortSignal;
+    }): unknown;
+}
+interface Route {
+    path: string;
+    handler: RouteHandler;
+    namespace?: string;
+}
+/**
+ * RouteMatch, RouteQuery, RouteSnapshot
+ * These describe the read-only snapshot returned by the render-time route() accessor
+ */
+interface RouteMatch {
+    path: string;
+    params: Readonly<Record<string, string>>;
+    name?: string;
+    namespace?: string;
+}
+interface RouteQuery {
+    get(key: string): string | null;
+    getAll(key: string): string[];
+    has(key: string): boolean;
+    toJSON(): Record<string, string | string[]>;
+}
+interface RouteSnapshot {
+    path: string;
+    params: Readonly<Record<string, string>>;
+    query: Readonly<RouteQuery>;
+    hash: string | null;
+    name?: string;
+    namespace?: string;
+    matches: readonly RouteMatch[];
+}
+declare function setServerLocation(url: string | null): void;
+declare function route(path?: string, handler?: RouteHandler, namespace?: string): void | RouteSnapshot;
+/**
+ * Get all registered routes
+ */
+declare function getRoutes(): Route[];
+/**
+ * Get routes for a specific namespace
+ */
+declare function getNamespaceRoutes(namespace: string): Route[];
+/**
+ * Unload all routes from a namespace (for MFE unmounting)
+ */
+declare function unloadNamespace(namespace: string): number;
+/**
+ * Clear all registered routes (mainly for testing)
+ */
+declare function clearRoutes(): void;
+/**
+ * Get all loaded namespaces (MFE identifiers)
+ */
+declare function getLoadedNamespaces(): string[];
+
+/**
+ * App bootstrap and mount
+ */
+
+interface AppConfig {
+    root: Element | string;
+    component: ComponentFunction;
+}
+/**
+ * Bootstrap and mount app on client
+ * Supports both sync and async components
+ *
+ * If createApp is called multiple times on the same root, the existing instance
+ * is reused and its component function is updated. This ensures:
+ * - Generation tokens work correctly (old async renders don't overwrite new ones)
+ * - State is preserved across updates (if desired)
+ * - DOM is diffed/updated rather than replaced
+ */
+declare function createApp(config: AppConfig | SPAConfig): void;
+
+type IslandConfig = {
+    root: Element | string;
+    component: ComponentFunction;
+    routes?: never;
+};
+type SPAConfig = {
+    root: Element | string;
+    routes: Route[];
+    component?: never;
+};
+type HydrateSPAConfig = {
+    root: Element | string;
+    routes: Route[];
+};
+/**
+ * createIsland: Enhances existing DOM (no router, mounts once)
+ */
+declare function createIsland(config: IslandConfig): void;
+/**
+ * createSPA: Initializes router and mounts the app with provided route table
+ */
+declare function createSPA(config: SPAConfig): Promise<void>;
+/**
+ * hydrateSPA: Hydrate server-rendered HTML with explicit routes
+ */
+declare function hydrateSPA(config: HydrateSPAConfig): Promise<void>;
+/**
+ * Cleanup an app mounted on a root element (element or id).
+ * Safe to call multiple times — no-op when nothing is mounted.
+ */
+declare function cleanupApp(root: Element | string): void;
+/**
+ * Check whether an app is mounted on the given root
+ */
+declare function hasApp(root: Element | string): boolean;
+
+/**
+ * Small layout helper (centralized)
+ * Usage: const parent = layout(ParentLayout); route('/parent', () => parent(<Child />));
+ *
+ * A layout is simply a component that receives `children`.
+ * This helper intentionally avoids vnode inspection, heuristics, or double-invocation.
+ * Prefer boring, explicit code over cleverness.
+ *
+ * Example:
+ * const Parent = ({ children }: { children?: unknown }) => <div class="parent">{children}</div>;
+ * const parent = layout(Parent);
+ * route('/parent', () => parent(<div class="child">C</div>));
+ */
+type Component<P = object> = (props: P & {
+    children?: unknown;
+}) => unknown;
+declare function layout<P>(Layout: Component<P>): (children?: unknown) => unknown;
+
+/**
+ * Client-side navigation with History API
+ */
+
+/**
+ * Navigate to a new path
+ * Updates URL, resolves route, and re-mounts app with new handler
+ */
+declare function navigate(path: string): void;
+
+/**
+ * Link component for client-side navigation
+ */
+
+interface LinkProps {
+    href: string;
+    children?: unknown;
+}
+/**
+ * Link component that prevents default navigation and uses navigate()
+ * Provides declarative way to navigate between routes
+ *
+ * Respects:
+ * - Middle-click (opens in new tab)
+ * - Ctrl/Cmd+click (opens in new tab)
+ * - Shift+click (opens in new window)
+ * - Right-click context menu
+ */
+declare function Link({ href, children }: LinkProps): JSXElement;
+
+type SSRData = Record<string, unknown>;
+
+type ResourceDescriptor = {
+    key: string;
+    fn: (opts: {
+        signal?: AbortSignal;
+    }) => Promise<unknown> | unknown;
+    deps: unknown[];
+    index: number;
+};
+type ResourcePlan = {
+    resources: ResourceDescriptor[];
+};
+declare function resolvePlan(_plan: ResourcePlan): Promise<Record<string, unknown>>;
+declare function collectResources(_opts: {
+    url: string;
+    routes: SSRRoute[];
+}): ResourcePlan;
+declare const resolveResources: typeof resolvePlan;
+
+/**
+ * SSR - Server-Side Rendering
+ *
+ * Renders Askr components to static HTML strings for server-side rendering.
+ * SSR is synchronous: async components are not supported; async work should use
+ * `resource()` which is rejected during synchronous SSR. This module throws
+ * when an async component or async resource is encountered during sync SSR.
+ */
+
+type VNode = {
+    type: string;
+    props?: Props;
+    children?: (string | VNode | null | undefined | false)[];
+};
+/**
+ * Single synchronous SSR entrypoint: render a component to an HTML string.
+ * This is strictly synchronous and deterministic. Optionally provide a seed
+ * for deterministic randomness via `options.seed`.
+ */
+declare function renderToStringSync(component: (props?: Record<string, unknown>) => VNode | JSXElement | string | number | null, props?: Record<string, unknown>, options?: {
+    seed?: number;
+    data?: SSRData;
+}): string;
+declare function renderToStringSyncForUrl(opts: {
+    url: string;
+    routes: Array<{
+        path: string;
+        handler: RouteHandler;
+        namespace?: string;
+    }>;
+    options?: {
+        seed?: number;
+        data?: SSRData;
+    };
+}): string;
+
+type SSRRoute = {
+    path: string;
+    handler: RouteHandler;
+    namespace?: string;
+};
+declare function renderToString(component: (props?: Record<string, unknown>) => VNode | JSXElement | string | number | null): string;
+declare function renderToString(opts: {
+    url: string;
+    routes: SSRRoute[];
+    seed?: number;
+    data?: SSRData;
+}): string;
+declare function renderToStream(opts: {
+    url: string;
+    routes: SSRRoute[];
+    seed?: number;
+    data?: SSRData;
+    onChunk(html: string): void;
+    onComplete(): void;
+}): void;
+
+export { type Context, type DataResult, type HydrateSPAConfig, type IslandConfig, Link, type LinkProps, Props, type Route, type RouteHandler, type RouteMatch, type RouteSnapshot, type SPAConfig, type State, cleanupApp, clearRoutes, collectResources, createApp, createIsland, createSPA, defineContext, getLoadedNamespaces, getNamespaceRoutes, getRoutes, getSignal, hasApp, hydrateSPA, layout, navigate, readContext, renderToStream, renderToString, renderToStringSync, renderToStringSyncForUrl, resolveResources, resource, route, scheduleEventHandler, setServerLocation, state, unloadNamespace };