WorkRoot/WRNexusJSDoc
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update portal for WRNexusJS 0.3.0

Browse Source
This commit is contained in:
Clintchiz
2026-07-22 17:53:02 +05:30
parent 38ee481b8a
commit aac3998a78
980 changed files with 4987 additions and 4670 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/pages/packages/router.wrn
+36 -12
View File
@@ -10,11 +10,11 @@ page wrnexusrouter {
<header class="topbar">
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.79</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.3.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
</header>
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
<main class="portal-main docs-layout">
<article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/router</span></nav><section class="doc-intro"><span class="eyebrow">Core · Package reference</span><h1>@wrnexus/router</h1><p>Filesystem discovery, route matching, and typed route generation.</p><div class="doc-meta"><span>v0.2.79</span><span>Private registry</span><span>Core</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/router@0.2.79</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>File-based router that maps an <code>app/</code> directory onto route tables and matches request paths against them.</blockquote>
<article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/router</span></nav><section class="doc-intro"><span class="eyebrow">Core · Package reference</span><h1>@wrnexus/router</h1><p>Filesystem discovery, route matching, and typed route generation.</p><div class="doc-meta"><span>v0.3.0</span><span>Private registry</span><span>Core</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/router@0.3.0</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>File-based router that maps an <code>app/</code> directory onto route tables and matches request paths against them.</blockquote>
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
<h3 id="overview">Overview</h3>
<p><code>@wrnexus/router</code> scans an application's <code>app/</code> directory once at startup and builds route tables for pages, API endpoints, realtime channels, middleware, server-rendered <code>.wrn</code> components, layouts, and validation schemas. It also compiles URL patterns (<code>/users/[id]</code>) into RegExps and matches request paths against them. Request input is never turned into a file path, which makes the router immune to path traversal. This is a server-side package used by the WRNexusJS runtime to resolve incoming requests, plus a codegen helper for compile-time typed links.</p>
@@ -135,9 +135,18 @@ const m = matchRoute(routes, &quot;/posts/hello&quot;); // &#123; route, params:
/**
* Route compilation + matching.
*
* A &quot;route&quot; is a URL pattern compiled to a RegExp. We support static segments
* and dynamic `[param]` segments, e.g. `/users/[id]` -&gt; `&#123; id &#125;`.
* Supported segments:
* [id] required parameter
* [id?] optional parameter
* [[id]] optional parameter (directory-friendly form)
* [...slug] required catch-all
* [[...slug]] optional catch-all
*/
interface RouteParam &#123;
name: string;
optional: boolean;
catchAll: boolean;
&#125;
interface Route &#123;
/** The human-readable route pattern, e.g. `/users/[id]`. */
raw: string;
@@ -147,25 +156,33 @@ interface Route &#123;
regex: RegExp;
/** Ordered names of dynamic params captured by `regex`. */
paramNames: string[];
/** Rich parameter metadata. Optional for compatibility with old manifests. */
paramMeta?: RouteParam[];
&#125;
interface RouteMatch &#123;
route: Route;
params: Record&lt;string, string&gt;;
&#125;
/** Compile a `/users/[id]` style pattern into a RegExp + param names. */
declare function compileRoutePattern(raw: string): Pick&lt;Route, &quot;regex&quot; | &quot;paramNames&quot;&gt;;
/** Return parameter metadata without requiring callers to inspect the regex. */
declare function getRouteParams(raw: string): RouteParam[];
/** Compile a WRNexus route pattern into a RegExp + parameter metadata. */
declare function compileRoutePattern(raw: string): Pick&lt;Route, &quot;regex&quot; | &quot;paramNames&quot; | &quot;paramMeta&quot;&gt;;
/**
* Order routes so that static routes win over dynamic ones, and longer/more
* specific routes win over shorter ones. Sorting once keeps matching simple.
* Order routes so static and constrained routes win over optional/catch-all
* routes. The ordering remains deterministic for identical specificity.
*/
declare function sortRoutes(routes: Route[]): Route[];
/** Find duplicate URL patterns before request handling starts. */
declare function findRouteConflicts(routes: Route[]): Array&lt;&#123;
raw: string;
files: string[];
&#125;&gt;;
/** Find the first route whose pattern matches `pathname`. */
declare function matchRoute(routes: Route[], pathname: string): RouteMatch | null;
/**
* Typed-routes codegen. From the scanned page routes, emit `app/routes.gen.ts`
* with a `Routes` map (path → param types) and an `href()` builder — so links
* are checked at compile time (unknown path or missing param = type error).
* with a `Routes` map (path -&gt; param types) and an `href()` builder.
*/
declare function generateRoutesFile(pages: Route[]): string;
@@ -215,10 +232,17 @@ interface RouterOptions &#123;
*/
componentDirs?: string[];
&#125;
/**
* Convert a scanned file's relative path into a URL route pattern.
* - strips the extension
* - drops a trailing `index` segment
* - prefixes with `prefix` (e.g. &quot;/api&quot;)
*/
declare function fileToRoute(rel: string, prefix?: string): string;
/** Scan an app directory and build all route tables. */
declare function buildRouter(appDir: string, opts?: RouterOptions): Router;
export &#123; type ComponentRef, type Route, type RouteMatch, type Router, type RouterOptions, buildRouter, compileRoutePattern, generateRoutesFile, matchRoute, sortRoutes &#125;;
export &#123; type ComponentRef, type Route, type RouteMatch, type Router, type RouterOptions, buildRouter, compileRoutePattern, fileToRoute, findRouteConflicts, generateRoutesFile, getRouteParams, matchRoute, sortRoutes &#125;;
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>Typical usage</h3><pre data-language="ts"><code>import &#123; buildRouter &#125; from &quot;@wrnexus/router&quot;;
const router = buildRouter(&quot;./app&quot;, &#123;
@@ -249,7 +273,7 @@ const routes = sortRoutes([&#123; raw: &quot;/posts/[slug]&quot;, file: &quot;
const m = matchRoute(routes, &quot;/posts/hello&quot;); // &#123; route, params: &#123; slug: &quot;hello&quot; &#125; &#125;</code></pre></article></div></section></article>
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#directory-conventions">Directory conventions</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#buildrouter-appdir-opts-router">buildRouter(appDir, opts?): Router</a><a class="toc-level-4" href="#route-matching">Route matching</a><a class="toc-level-4" href="#typed-routes-codegen">Typed-routes codegen</a><a class="toc-level-4" href="#re-exports">Re-exports</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
</main>
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.2.79</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.3.0</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
<BackToTop />
</div>
}