docs: update portal for WRNexusJS 0.3.0
This commit is contained in:
+151
-4
@@ -10,11 +10,11 @@ page wrnexuscore {
|
||||
<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/core</span></nav><section class="doc-intro"><span class="eyebrow">Core · Package reference</span><h1>@wrnexus/core</h1><p>Contexts, middleware, security, sessions, caching, JSX, and realtime.</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/core@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>The framework core: the request <code>Context</code>, middleware contract, and the security, session, caching, streaming, realtime, and JSX primitives every other WRNexusJS package builds on.</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/core</span></nav><section class="doc-intro"><span class="eyebrow">Core · Package reference</span><h1>@wrnexus/core</h1><p>Contexts, middleware, security, sessions, caching, JSX, and realtime.</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/core@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>The framework core: the request <code>Context</code>, middleware contract, and the security, session, caching, streaming, realtime, and JSX primitives every other WRNexusJS package builds on.</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/core</code> is the shared foundation of WRNexusJS. It defines the <code>Context</code> object that flows through every middleware, page, and API route, plus the <code>Middleware</code>/<code>Next</code> contract they implement. On top of that it ships the building blocks a real app needs: cookie-backed sessions, password auth, CSRF protection, rate limiting, request logging, HTTP + in-memory caching, file uploads, streaming/SSE responses, WebSocket "rooms", security headers/CORS, and a server-side JSX runtime that renders to HTML strings. Everything here is <strong>server-side</strong> and Bun-native (it uses <code>Bun.password</code>, <code>Bun.write</code>, the web-standard <code>Request</code>/<code>Response</code>, and <code>crypto</code>). You depend on it directly and transitively through the rest of the framework.</p>
|
||||
@@ -211,6 +211,54 @@ return new Response(html.toString(), { headers: { "content-type&q
|
||||
<p>for TypeScript's automatic JSX transform.</p>
|
||||
</ul></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>export { Fragment, Html, Component as JSXComponent, Props as JSXProps, Renderable, jsx, jsxs, mustache } from './jsx-runtime.js';
|
||||
|
||||
interface Tenant {
|
||||
id: string;
|
||||
slug?: string;
|
||||
name?: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
type TenantResolver = (ctx: Context) => Tenant | null | Promise<Tenant | null>;
|
||||
interface TenantMiddlewareOptions {
|
||||
required?: boolean;
|
||||
status?: number;
|
||||
}
|
||||
declare function tenantMiddleware(resolveTenant: TenantResolver, options?: TenantMiddlewareOptions): Middleware;
|
||||
declare function tenantFromSubdomain(lookup: (slug: string, ctx: Context) => Tenant | null | Promise<Tenant | null>, rootDomains?: string[]): TenantResolver;
|
||||
declare function requireTenant(ctx: Context): Tenant;
|
||||
/** Wrap a repository so every operation receives the current tenant id. */
|
||||
declare function tenantScope<T extends object>(tenant: Tenant, repository: T): T & {
|
||||
tenantId: string;
|
||||
};
|
||||
|
||||
interface SpanRecord {
|
||||
name: string;
|
||||
startTime: number;
|
||||
endTime?: number;
|
||||
durationMs?: number;
|
||||
status?: "ok" | "error";
|
||||
attributes: Record<string, string | number | boolean>;
|
||||
error?: unknown;
|
||||
}
|
||||
interface Tracer {
|
||||
startSpan(name: string, attributes?: SpanRecord["attributes"]): Span;
|
||||
records(): readonly SpanRecord[];
|
||||
}
|
||||
interface Span {
|
||||
setAttribute(name: string, value: string | number | boolean): void;
|
||||
end(status?: "ok" | "error", error?: unknown): SpanRecord;
|
||||
}
|
||||
declare function createTracer(clock?: () => number): Tracer;
|
||||
declare function withSpan<T>(tracer: Tracer, name: string, run: (span: Span) => T | Promise<T>, attributes?: SpanRecord["attributes"]): Promise<T>;
|
||||
interface TracingMiddlewareOptions {
|
||||
/** Include W3C Server-Timing response headers. Defaults to true. */
|
||||
serverTiming?: boolean;
|
||||
/** Fraction of requests to trace, from 0 to 1. Defaults to 1. */
|
||||
sampleRate?: number;
|
||||
/** Called after a traced response completes. */
|
||||
onComplete?: (ctx: Context, records: readonly SpanRecord[]) => void | Promise<void>;
|
||||
}
|
||||
declare function tracingMiddleware(tracerFactory?: (ctx: Context) => Tracer, options?: TracingMiddlewareOptions): Middleware;
|
||||
|
||||
interface CookieOptions {
|
||||
path?: string;
|
||||
domain?: string;
|
||||
@@ -315,6 +363,10 @@ type Context = {
|
||||
* by the `sessionAuth` middleware (or `logIn`); read via `getUser(ctx)`.
|
||||
*/
|
||||
user?: unknown;
|
||||
/** Active tenant/workspace resolved by tenant middleware. */
|
||||
tenant?: Tenant;
|
||||
/** Request tracer installed by observability middleware. */
|
||||
tracer?: Tracer;
|
||||
/**
|
||||
* The direct socket peer IP, set by the server from `server.requestIP`. This
|
||||
* is NOT spoofable by request headers — prefer it over `x-forwarded-for` for
|
||||
@@ -925,7 +977,102 @@ declare function createCorsPreflightResponse(req: Request, security?: SecurityCo
|
||||
declare function resolveRequestUrl(req: Request, trustProxy?: boolean): URL;
|
||||
declare function withSecurityHeaders(req: Request, res: Response, mode: Mode, security?: SecurityConfig, nonce?: string): Response;
|
||||
|
||||
export { type AsyncSessionBackend, type Bucket, CSRF_COOKIE, CSRF_HEADER, type CacheControlOptions, type ContentSecurityPolicyConfig, type Context, type CookieOptions, type CookieStore, type CorsConfig, type CorsOrigin, type CspDirectiveValue, type HstsConfig, type LocalStorageSnapshot, type Middleware, type Mode, type Next, type PageComponent, type PageMeta, type PermissionsPolicyConfig, type RateLimitOptions, type RateLimitStore, type RawSocket, type RealtimeBridge, type RealtimeBus, type RealtimeConnectMeta, type RealtimeEnvelope, type RealtimeHandler, type RealtimeRegistry, type RealtimeSocket, type RequestLoggerOptions, type RequestRecord, type RequireAuthOptions, type Room, type RoomAuthInfo, type RoomClient, type RoomDefinition, type RoomHandlers, SESSION_USER_KEY, type SaveUploadOptions, type SavedUpload, type SecurityConfig, type SeoConfig, type ServerSentEvent, type SessionBackend, type SessionEntry, type SessionStore, type StreamResponseInit, type TFunction, TTLCache, type Target, type TrustedTypesConfig, UploadError, bridgeRealtime, cacheControl, collectUploads, createContext, createCorsPreflightResponse, createRealtimeRegistry, csrfProtection, csrfToken, defaultKey, defineRoom, escapeHtml, etag, getUser, hashPassword, isRoomDefinition, isSafeIslandName, isSafeRequestPath, isWebSocketOriginAllowed, loadSession, logIn, logOut, notModified, peerKey, proxyKey, rateLimit, renderDevError, renderError, renderNotFound, renderProdError, renderStatusPage, requestLogger, requireAuth, resolveRequestUrl, sanitizeFilename, saveUpload, sessionAuth, setSessionBackend, sse, streamResponse, verifyCsrf, verifyPassword, withCacheControl, withContextHeaders, withSecurityHeaders };
|
||||
interface SchemaLike<T> {
|
||||
parse(input: unknown): T;
|
||||
}
|
||||
interface EndpointErrorBody {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: unknown;
|
||||
}
|
||||
declare class EndpointError extends Error {
|
||||
readonly status: number;
|
||||
readonly code: string;
|
||||
readonly details?: unknown | undefined;
|
||||
constructor(status: number, code: string, message: string, details?: unknown | undefined);
|
||||
}
|
||||
interface EndpointDefinition<I, O> {
|
||||
input?: SchemaLike<I>;
|
||||
output?: SchemaLike<O>;
|
||||
auth?: "optional" | "required";
|
||||
description?: string;
|
||||
tags?: string[];
|
||||
handler(input: I, ctx: Context): O | Promise<O>;
|
||||
}
|
||||
interface DefinedEndpoint<I, O> {
|
||||
readonly definition: EndpointDefinition<I, O>;
|
||||
(ctx: Context, input?: unknown): Promise<Response>;
|
||||
}
|
||||
/** Define a validated, typed endpoint that can also drive SDK/OpenAPI generation. */
|
||||
declare function defineEndpoint<I = unknown, O = unknown>(definition: EndpointDefinition<I, O>): DefinedEndpoint<I, O>;
|
||||
interface RpcClientOptions {
|
||||
baseUrl?: string;
|
||||
fetch?: typeof globalThis.fetch;
|
||||
headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
|
||||
}
|
||||
/** Create a tiny typed RPC caller for endpoints exposed by a WRNexusJS app. */
|
||||
declare function createRpcClient(options?: RpcClientOptions): <I, O>(path: string, input: I) => Promise<O>;
|
||||
|
||||
interface CachePolicy {
|
||||
ttlMs?: number;
|
||||
staleWhileRevalidateMs?: number;
|
||||
tags?: string[] | ((ctx: Context) => string[]);
|
||||
}
|
||||
interface LoaderDefinition<T> {
|
||||
cache?: CachePolicy;
|
||||
load(ctx: Context): T | Promise<T>;
|
||||
}
|
||||
interface ActionDefinition<I, O> {
|
||||
csrf?: boolean;
|
||||
run(input: I, ctx: Context): O | Promise<O>;
|
||||
invalidate?: string[] | ((output: O, ctx: Context) => string[]);
|
||||
}
|
||||
interface DefinedLoader<T> {
|
||||
readonly definition: LoaderDefinition<T>;
|
||||
(ctx: Context): Promise<T>;
|
||||
}
|
||||
interface DefinedAction<I, O> {
|
||||
readonly definition: ActionDefinition<I, O>;
|
||||
(input: I, ctx: Context): Promise<O>;
|
||||
}
|
||||
declare function defineLoader<T>(definition: LoaderDefinition<T>): DefinedLoader<T>;
|
||||
declare function defineAction<I, O>(definition: ActionDefinition<I, O>): DefinedAction<I, O>;
|
||||
/** Request-local fetch deduplication keyed by a stable string. */
|
||||
declare function dedupe<T>(ctx: Context, key: string, load: () => T | Promise<T>): Promise<T>;
|
||||
|
||||
type FeatureValue = boolean | string | number;
|
||||
type FeatureRule = FeatureValue | ((ctx: Context) => FeatureValue | Promise<FeatureValue>);
|
||||
interface FeatureFlags {
|
||||
get(name: string, ctx: Context): Promise<FeatureValue | undefined>;
|
||||
enabled(name: string, ctx: Context): Promise<boolean>;
|
||||
}
|
||||
declare function defineFeatureFlags(rules: Record<string, FeatureRule>): FeatureFlags;
|
||||
|
||||
interface PerformanceBudgets {
|
||||
routeJsBytes?: number;
|
||||
routeCssBytes?: number;
|
||||
htmlBytes?: number;
|
||||
imageBytes?: number;
|
||||
hydrationMs?: number;
|
||||
serverRenderMs?: number;
|
||||
}
|
||||
interface PerformanceMeasurement {
|
||||
routeJsBytes?: number;
|
||||
routeCssBytes?: number;
|
||||
htmlBytes?: number;
|
||||
imageBytes?: number;
|
||||
hydrationMs?: number;
|
||||
serverRenderMs?: number;
|
||||
}
|
||||
interface BudgetViolation {
|
||||
metric: keyof PerformanceBudgets;
|
||||
budget: number;
|
||||
actual: number;
|
||||
overBy: number;
|
||||
}
|
||||
declare function checkPerformanceBudgets(budgets: PerformanceBudgets, measurement: PerformanceMeasurement): BudgetViolation[];
|
||||
|
||||
export { type ActionDefinition, type AsyncSessionBackend, type Bucket, type BudgetViolation, CSRF_COOKIE, CSRF_HEADER, type CacheControlOptions, type CachePolicy, type ContentSecurityPolicyConfig, type Context, type CookieOptions, type CookieStore, type CorsConfig, type CorsOrigin, type CspDirectiveValue, type DefinedAction, type DefinedEndpoint, type DefinedLoader, type EndpointDefinition, EndpointError, type EndpointErrorBody, type FeatureFlags, type FeatureRule, type FeatureValue, type HstsConfig, type LoaderDefinition, type LocalStorageSnapshot, type Middleware, type Mode, type Next, type PageComponent, type PageMeta, type PerformanceBudgets, type PerformanceMeasurement, type PermissionsPolicyConfig, type RateLimitOptions, type RateLimitStore, type RawSocket, type RealtimeBridge, type RealtimeBus, type RealtimeConnectMeta, type RealtimeEnvelope, type RealtimeHandler, type RealtimeRegistry, type RealtimeSocket, type RequestLoggerOptions, type RequestRecord, type RequireAuthOptions, type Room, type RoomAuthInfo, type RoomClient, type RoomDefinition, type RoomHandlers, type RpcClientOptions, SESSION_USER_KEY, type SaveUploadOptions, type SavedUpload, type SchemaLike, type SecurityConfig, type SeoConfig, type ServerSentEvent, type SessionBackend, type SessionEntry, type SessionStore, type Span, type SpanRecord, type StreamResponseInit, type TFunction, TTLCache, type Target, type Tenant, type TenantMiddlewareOptions, type TenantResolver, type Tracer, type TrustedTypesConfig, UploadError, bridgeRealtime, cacheControl, checkPerformanceBudgets, collectUploads, createContext, createCorsPreflightResponse, createRealtimeRegistry, createRpcClient, createTracer, csrfProtection, csrfToken, dedupe, defaultKey, defineAction, defineEndpoint, defineFeatureFlags, defineLoader, defineRoom, escapeHtml, etag, getUser, hashPassword, isRoomDefinition, isSafeIslandName, isSafeRequestPath, isWebSocketOriginAllowed, loadSession, logIn, logOut, notModified, peerKey, proxyKey, rateLimit, renderDevError, renderError, renderNotFound, renderProdError, renderStatusPage, requestLogger, requireAuth, requireTenant, resolveRequestUrl, sanitizeFilename, saveUpload, sessionAuth, setSessionBackend, sse, streamResponse, tenantFromSubdomain, tenantMiddleware, tenantScope, tracingMiddleware, verifyCsrf, verifyPassword, withCacheControl, withContextHeaders, withSecurityHeaders, withSpan };
|
||||
</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>A minimal middleware chain</h3><pre data-language="ts"><code>import {
|
||||
createContext,
|
||||
withContextHeaders,
|
||||
@@ -989,7 +1136,7 @@ const registry = createRealtimeRegistry();
|
||||
bridgeRealtime(registry, createPubSub(redisDriver(process.env.REDIS_URL)));</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="#api">API</a><a class="toc-level-4" href="#context-middleware-wrnexus-core">Context & middleware — @wrnexus/core</a><a class="toc-level-4" href="#authentication-wrnexus-core">Authentication — @wrnexus/core</a><a class="toc-level-4" href="#csrf-wrnexus-core">CSRF — @wrnexus/core</a><a class="toc-level-4" href="#rate-limiting-wrnexus-core">Rate limiting — @wrnexus/core</a><a class="toc-level-4" href="#request-logging-wrnexus-core">Request logging — @wrnexus/core</a><a class="toc-level-4" href="#caching-wrnexus-core">Caching — @wrnexus/core</a><a class="toc-level-4" href="#file-uploads-wrnexus-core">File uploads — @wrnexus/core</a><a class="toc-level-4" href="#streaming-sse-wrnexus-core">Streaming & SSE — @wrnexus/core</a><a class="toc-level-4" href="#realtime-rooms-wrnexus-core">Realtime rooms — @wrnexus/core</a><a class="toc-level-4" href="#error-pages-wrnexus-core">Error pages — @wrnexus/core</a><a class="toc-level-4" href="#security-headers-cors-wrnexus-core">Security headers & CORS — @wrnexus/core</a><a class="toc-level-4" href="#storage-cookies-sessions-localstorage-wrnexus-core">Storage: cookies, sessions, localStorage — @wrnexus/core</a><a class="toc-level-4" href="#low-level-security-helpers-wrnexus-core">Low-level security helpers — @wrnexus/core</a><a class="toc-level-4" href="#jsx-runtime-wrnexus-core-wrnexus-core-jsx-runtime-wrnexus-core-jsx-dev-runtime">JSX runtime — @wrnexus/core, @wrnexus/core/jsx-runtime, @wrnexus/core/jsx-dev-runtime</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#a-minimal-middleware-chain">A minimal middleware chain</a><a class="toc-level-4" href="#password-auth">Password auth</a><a class="toc-level-4" href="#http-caching-with-etags">HTTP caching with ETags</a><a class="toc-level-4" href="#streaming-sse">Streaming SSE</a><a class="toc-level-4" href="#a-realtime-room">A realtime room</a><a class="toc-level-4" href="#jsx-rendering">JSX rendering</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>
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user