@nifrajs/web 0.1.0-alpha.1

package/dist/router.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Request header that asks a nifra route's GET to return just the loader data as JSON (instead of
+ * the full HTML document). Set by client-side navigation; read by `createWebApp`'s GET handler.
+ */
+export declare const DATA_HEADER = "x-nifra-data";
+/**
+ * Global the server injects (`createWebApp({ prerenderedPaths })`) listing the SSG-prerendered paths.
+ * The client's default data fetch reads it: a soft-nav INTO a prerendered route fetches its static
+ * `<path>/_data.json` (a CDN file — no worker round-trip) instead of the dynamic header-GET.
+ */
+export declare const PRERENDERED_GLOBAL = "__NIFRA_PRERENDERED__";
+/**
+ * Response header a data-mode action POST uses to convey a redirect (`redirect(...)`) to the
+ * client — fetch would otherwise silently follow a 3xx to its HTML, losing the target. The
+ * client reads this and performs a client-side navigation instead.
+ */
+export declare const REDIRECT_HEADER = "x-nifra-redirect";
+/**
+ * Response header an action sets (via the `revalidate(paths, data)` helper) to tell the client which
+ * routes the mutation changed — a comma-separated list of paths. After the submit, the client marks
+ * those cached routes stale (refetching any that are mounted) so a mutation can refresh views beyond
+ * the active one. The client validates each path against the manifest matcher before acting on it.
+ */
+export declare const REVALIDATE_HEADER = "x-nifra-revalidate";
+/** A URL matched against the manifest patterns: which route + its extracted params. */
+export interface RouteMatch {
+    readonly routeId: string;
+    readonly params: Record<string, string>;
+}
+/** An in-flight client submit — the action it targets + the `FormData` being sent. Set while the
+ * submit is pending, cleared when it settles. A component reads `submission.formData` to render an
+ * **optimistic** view (the expected result) before the server responds. */
+export interface Submission {
+    readonly action: string;
+    readonly formData: FormData;
+}
+/** The router's observable state. A new object is published on every transition. */
+export interface RouterState {
+    readonly routeId: string;
+    readonly params: Record<string, string>;
+    /** The current URL path (used to revalidate the active loader after an action). */
+    readonly path: string;
+    readonly data: unknown;
+    /** An action's data return after a client-side submit (cleared on navigation). */
+    readonly actionData?: unknown;
+    /** True while a navigation or submit is in flight (drives loading UI). */
+    readonly pending: boolean;
+    /** The in-flight submit (set during a `submit`, cleared when it settles) — for optimistic UI. */
+    readonly submission?: Submission;
+}
+/** A route id paired with its nifra pattern (e.g. `":id"` segments) — the matcher input. */
+export interface RoutePattern {
+    readonly routeId: string;
+    readonly pattern: string;
+}
+/**
+ * Build a matcher from route patterns (built from the SAME manifest the server routes from, so
+ * client and server agree). Returns the first matching route + decoded params, or null. The
+ * query string is ignored for matching (it is not part of the route pattern).
+ */
+export declare function createMatcher(patterns: readonly RoutePattern[]): (path: string) => RouteMatch | null;
+/** How a router fetches a route's loader data on navigation. `signal` aborts a superseded fetch
+ * (and its deferred stream). */
+export type FetchRouteData = (path: string, match: RouteMatch, signal?: AbortSignal) => Promise<unknown>;
+/** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
+export interface SubmitOptions {
+    /** Re-run the active route's loader after the action settles (default `true`). Set `false` to
+     * keep the current `data` and rely on the action's `actionData` alone. */
+    readonly revalidate?: boolean;
+}
+/** A fetcher's observable state — independent of the main router. `pending` covers its in-flight
+ * load/submit; `data` is its last `load()` result; `actionData` its last `submit()` result;
+ * `submission` the in-flight submit (for optimistic UI). Client-only (never SSR'd). */
+export interface FetcherState {
+    readonly pending: boolean;
+    readonly data: unknown;
+    readonly actionData?: unknown;
+    readonly submission?: Submission;
+}
+/**
+ * An independent load/submit state machine, retrieved by `router.fetcher(key)`. Runs **concurrently**
+ * with the main router and with other fetchers — each is single-flight against *itself* (its own
+ * monotonic token), so N row-level mutations / side-channel loads can be in flight at once without
+ * disturbing the active view. Loads/submits write the shared cache and honor `X-Nifra-Revalidate`.
+ */
+export interface Fetcher {
+    /** Current state; stable reference between transitions. */
+    snapshot: () => FetcherState;
+    /** Subscribe to this fetcher's transitions; returns an unsubscribe fn. */
+    subscribe: (listener: () => void) => () => void;
+    /** Load a route path's loader data into this fetcher's own `data` (also writes the shared cache).
+     * A no-op for an unmatched path. */
+    load: (path: string) => Promise<void>;
+    /** Submit an action into this fetcher's own state; honors `X-Nifra-Revalidate` by refreshing the
+     * active route + any mounted fetcher showing a changed path. Rejects on failure (caller falls back).
+     * (No `revalidate` opt-out — a fetcher has no active loader of its own to skip.) */
+    submit: (action: string, body: NonNullable<RequestInit["body"]>) => Promise<void>;
+}
+/** The agnostic router store consumed by per-adapter Router bindings. */
+export interface ClientRouter {
+    /** Current state; stable reference between transitions (so `useSyncExternalStore` can bail). */
+    snapshot: () => RouterState;
+    /** Subscribe to transitions; returns an unsubscribe fn. */
+    subscribe: (listener: () => void) => () => void;
+    /** Navigate to a path: match → fetch loader data → publish. No-op for an unmatched path. */
+    navigate: (path: string) => Promise<void>;
+    /**
+     * Submit an action (POST `body` to `action` in data mode): a redirect becomes a client
+     * navigation; otherwise the data return is published as `actionData` and the active route's
+     * loader is revalidated so the mutation is reflected. Pass `{ revalidate: false }` to SKIP that
+     * revalidation — keep the current `data` and just publish the action's `actionData` (useful when
+     * the action already returned everything that changed, saving the extra round-trip). A redirect
+     * always loads its target regardless. Rejects on failure (caller falls back).
+     */
+    submit: (action: string, body: NonNullable<RequestInit["body"]>, opts?: SubmitOptions) => Promise<void>;
+    /**
+     * Mark cached route data stale and refresh the active view. With `paths`, target exactly those
+     * (e.g. the routes a mutation changed); without, invalidate the whole cache. The active route
+     * refreshes immediately — refetched + republished — whenever it's in scope (an explicit list that
+     * includes it, or an invalidate-all); other stale entries refetch lazily when next read (a
+     * fetcher, or the next navigation/access). Rejects if the active refetch fails (like `navigate`).
+     * The keyed substrate for targeted revalidation (the `X-Nifra-Revalidate` header) and fetchers.
+     */
+    invalidate: (paths?: readonly string[]) => Promise<void>;
+    /**
+     * Warm a path's chunk + loader data into a bounded one-shot cache without publishing state —
+     * a later `navigate` to it transitions with no network round-trip. Best-effort: failures and
+     * unmatched paths are no-ops. Wired to link hover/focus by `installHistory`.
+     */
+    prefetch: (path: string) => Promise<void>;
+    /**
+     * Get (lazily creating) the stable {@link Fetcher} for `key` — an independent, concurrent
+     * load/submit state machine for row-level mutations or side-channel loads that must not disturb
+     * the active view. The same `key` always returns the same fetcher (so a binding can subscribe to a
+     * stable store). Keys are app-chosen and typically stable (e.g. a row id).
+     */
+    fetcher: (key: string) => Fetcher;
+    /** All live fetchers — for a global busy view (e.g. a `useFetchers` binding). */
+    fetchers: () => readonly Fetcher[];
+    /** Subscribe to any-fetcher-changed (a transition on any fetcher, or a new one created) — backs a
+     * `useFetchers` binding; returns an unsubscribe fn. */
+    subscribeFetchers: (listener: () => void) => () => void;
+    /** Match a path against the manifest patterns (exposed for history/link wiring). */
+    match: (path: string) => RouteMatch | null;
+}
+export interface ClientRouterOptions {
+    readonly patterns: readonly RoutePattern[];
+    readonly initial: RouterState;
+    /** Override the loader-data fetch (tests inject a stub; defaults to a same-origin JSON GET). */
+    readonly fetchData?: FetchRouteData;
+    /** Ensure a route's code chunk is loaded before rendering (code-splitting). Awaited in parallel
+     * with the loader data, so `pending` covers both. Omit when the bundle isn't split. */
+    readonly loadModule?: (routeId: string) => Promise<void>;
+}
+/** Options for a per-adapter `mountRouter` (the Router binding that hydrates + re-renders). */
+export interface MountRouterOptions {
+    readonly router: ClientRouter;
+    /** routeId → layout chain (outermost layout → page); built by `generateClientEntry`. */
+    readonly routes: Record<string, readonly unknown[]>;
+    /** Hydration container (opaque — the adapter casts it to its DOM element type). */
+    readonly container: unknown;
+}
+/**
+ * Create the agnostic router store. `navigate` is guarded by a monotonic token so that when
+ * navigations overlap, only the latest result is applied (rapid clicks don't flash stale data).
+ * A failed fetch clears `pending` and rethrows so the caller can fall back to a full-page load.
+ */
+export declare function createClientRouter(options: ClientRouterOptions): ClientRouter;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}