docs: update portal for WRNexusJS 0.8.0
This commit is contained in:
@@ -10,11 +10,11 @@ page wrnexusuploader {
|
||||
<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="https://component.wrnexusjs.dev/">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.7.0</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.8.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="https://component.wrnexusjs.dev/">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/uploader</span></nav><section class="doc-intro"><span class="eyebrow">Data · Package reference</span><h1>@wrnexus/uploader</h1><p>Validated local/S3 uploads and secure file serving.</p><div class="doc-meta"><span>v0.7.0</span><span>Private registry</span><span>Data</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/uploader@0.7.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"><p>Config-driven file uploads + serving for <a href="https://www.npmjs.com/org/wrnexus" rel="noreferrer">WRNexusJS</a>. Declare named <strong>storage stores</strong> (local disk or any S3-compatible backend) in <code>wrnexus.config.ts</code>, upload with one function call, drop a drag-and-drop widget on a page, and serve files back — public or private. Zero external dependencies (S3 is signed with a built-in AWS SigV4 implementation, like the rest of the framework).</p>
|
||||
<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/uploader</span></nav><section class="doc-intro"><span class="eyebrow">Data · Package reference</span><h1>@wrnexus/uploader</h1><p>Validated local/S3 uploads and secure file serving.</p><div class="doc-meta"><span>v0.8.0</span><span>Private registry</span><span>Data</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/uploader@0.8.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"><p>Config-driven file uploads + serving for <a href="https://www.npmjs.com/org/wrnexus" rel="noreferrer">WRNexusJS</a>. Declare named <strong>storage stores</strong> (local disk or any S3-compatible backend) in <code>wrnexus.config.ts</code>, upload with one function call, drop a drag-and-drop widget on a page, and serve files back — public or private. Zero external dependencies (S3 is signed with a built-in AWS SigV4 implementation, like the rest of the framework).</p>
|
||||
<h3 id="usage">Usage</h3>
|
||||
<h4 id="configure-local-and-s3-stores">Configure local and S3 stores</h4>
|
||||
<pre data-language="ts"><code>// wrnexus.config.ts
|
||||
@@ -88,6 +88,7 @@ await getStore("docs").driver.delete(files[0].key);</code></pre>
|
||||
import { serveFromStore } from "@wrnexus/uploader";
|
||||
export const GET = serveFromStore("docs"); // your middleware decides who gets in</code></pre>
|
||||
<h3 id="api">API</h3>
|
||||
<p>Uploads can participate in security and media pipelines without changing storage drivers. Pass a <code>scan</code> hook to reject malware/DLP findings before storage, and <code>afterStore</code> to enqueue image/video processing or indexing. If post-processing throws, WRNexus deletes the newly written object so a partially accepted upload is never left behind.</p>
|
||||
<div class="table-wrap"><table>
|
||||
<thead><tr><th>Export</th><th>What</th></tr></thead>
|
||||
<tbody><tr><td><code>handleUpload(opts)</code></td><td>POST route handler → JSON <code>{ ok, files }</code></td></tr><tr><td><code>upload(store, req, opts)</code></td><td>Parse + validate + store; returns <code>{ files }</code></td></tr><tr><td><code>serveFromStore(store)</code></td><td>Route handler that streams an object back (gate it for private)</td></tr><tr><td><code>getStore(name?)</code> / <code>hasStorage(name?)</code></td><td>Reach a store's <code>driver</code> (<code>put</code>/<code>get</code>/<code>delete</code>/<code>publicUrl</code>)</td></tr><tr><td><code>configureStorage(config, root)</code></td><td>Build the registry (the framework calls this at startup)</td></tr><tr><td><code>s3Driver</code> / <code>localDriver</code> / <code>signS3</code></td><td>Lower-level building blocks</td></tr></tbody></table></div>
|
||||
@@ -97,7 +98,28 @@ export const GET = serveFromStore("docs"); // your middleware decides
|
||||
<li>SigV4 signing is implemented from scratch (no <code>@aws-sdk</code>); tested against local S3 semantics.</li>
|
||||
<p>Live AWS/R2 connectivity depends on your credentials + bucket policy.</p>
|
||||
<li>v1 buffers each file in memory up to its size cap (fine for images/docs up to tens of MB).</li>
|
||||
</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>import { Context } from '@wrnexus/core';
|
||||
</ul>
|
||||
<h3 id="helper-and-component-kit">Helper and component kit</h3>
|
||||
<p>Use <code>formatFileSize</code>, <code>uploadAccept</code>, <code>uploadedFileMap</code>, <code>uploaderAttributes</code>, and <code>assertUploadedFiles</code> to keep upload forms and server validation consistent.</p>
|
||||
<p>Enable <code>uploaderPlugin()</code> for:</p>
|
||||
<ul>
|
||||
<li><code><UploadDropzone /></code></li>
|
||||
<li><code><UploadStatus /></code></li>
|
||||
</ul>
|
||||
<p>The complete blocks compose <code>Card</code>, <code>Alert</code>, and <code>Badge</code> from <code>@wrnexus/ui</code>; the specialized upload runtime remains responsible for the native file input and secure transport behavior. Large files can use <code>createResumableUploadManager</code>. Sessions are bounded and expiring; chunks may arrive out of order, carry SHA-256 checksums, and are idempotent when retried. Conflicting retries reject, and the object is assembled only after every exact-sized chunk is present.</p>
|
||||
<pre data-language="ts"><code>const uploads = createResumableUploadManager({
|
||||
driver: getStore("documents").driver,
|
||||
sessions: redisUploadSessionStore,
|
||||
chunkSize: 5 * 1024 * 1024,
|
||||
maxBytes: 500 * 1024 * 1024,
|
||||
accept: ["application/pdf"],
|
||||
});
|
||||
|
||||
const session = await uploads.create({ name: "report.pdf", size, type });
|
||||
await uploads.uploadChunk(session.id, index, bytes, sha256);</code></pre>
|
||||
<p>The included memory session store is intended for one-process apps and tests. Multi-instance production deployments should implement <code>ResumableSessionStore</code> with shared durable storage and atomic session updates, and periodically call <code>prune()</code> for abandoned uploads.</p></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>import { Context } from '@wrnexus/core';
|
||||
export { UploaderPluginOptions, uploaderComponentsDir, default as uploaderPlugin } from './plugin.js';
|
||||
import '@wrnexus/plugin';
|
||||
|
||||
/**
|
||||
* Storage driver contract + config types.
|
||||
@@ -227,6 +249,25 @@ interface UploadOptions {
|
||||
accept?: string[];
|
||||
/** Key prefix, e.g. `"avatars"` → keys become `avatars/<yyyy>/<mm>/<rand>.<ext>`. */
|
||||
prefix?: string;
|
||||
/** Virus/DLP/content scanner invoked before bytes enter storage. Throw or return unsafe to reject. */
|
||||
scan?: (file: UploadScanInput) => UploadScanResult | Promise<UploadScanResult>;
|
||||
/** Image/video/indexing hook invoked after storage. Failure removes the just-written object. */
|
||||
afterStore?: (file: UploadedFile & {
|
||||
bytes: Uint8Array;
|
||||
store: Store;
|
||||
}) => void | Promise<void>;
|
||||
}
|
||||
interface UploadScanInput {
|
||||
name: string;
|
||||
type: string;
|
||||
size: number;
|
||||
bytes: Uint8Array;
|
||||
store: Store;
|
||||
}
|
||||
interface UploadScanResult {
|
||||
safe: boolean;
|
||||
reason?: string;
|
||||
scanner?: string;
|
||||
}
|
||||
/** A 4xx-carrying error so `handleUpload` can map it to a status. */
|
||||
declare class UploadError extends Error {
|
||||
@@ -401,7 +442,145 @@ interface SignedFileToken {
|
||||
declare function createSignedFileToken(input: SignedFileToken, secret: string): Promise<string>;
|
||||
declare function verifySignedFileToken(token: string, secret: string, now?: number): Promise<SignedFileToken | null>;
|
||||
|
||||
export { type LocalStoreConfig, type PutMeta, type S3StoreConfig, type SignedFileToken, type StorageConfig, type StorageDriver, type Store, type StoreAccess, type StoreConfig, type StoredObject, UPLOADS_PREFIX, UPLOAD_JS_HREF, UPLOAD_RUNTIME, UploadError, type UploadInspection, type UploadOptions, type UploadPolicy, UploadPolicyError, type UploadedFile, accepts, configureStorage, contentTypeOf, createSignedFileToken, encodeKey, enforceUploadPolicy, extForType, extOf, getStore, handleUpload, hasStorage, inspectUpload, localDriver, s3Driver, safeObjectKey, serveFromStore, serveStoredFile, sha256Hex, signS3, sniffContentType, storeNames, storedUrl, upload, verifySignedFileToken };
|
||||
declare function formatFileSize(bytes: number, locale?: string): string;
|
||||
declare function uploadAccept(value: string | readonly string[]): string;
|
||||
declare function uploadedFileMap(files: readonly UploadedFile[]): Record<string, UploadedFile>;
|
||||
declare function uploaderAttributes(options?: {
|
||||
store?: string;
|
||||
endpoint?: string;
|
||||
accept?: string | readonly string[];
|
||||
maxBytes?: number;
|
||||
multiple?: boolean;
|
||||
field?: string;
|
||||
label?: string;
|
||||
}): Record<string, string | boolean>;
|
||||
declare function assertUploadedFiles(files: readonly UploadedFile[], options?: {
|
||||
min?: number;
|
||||
max?: number;
|
||||
}): readonly UploadedFile[];
|
||||
|
||||
interface ResumableUploadSession {
|
||||
id: string;
|
||||
key: string;
|
||||
name: string;
|
||||
type: string;
|
||||
size: number;
|
||||
chunkSize: number;
|
||||
totalChunks: number;
|
||||
createdAt: number;
|
||||
expiresAt: number;
|
||||
chunks: Record<number, Uint8Array>;
|
||||
digests: Record<number, string>;
|
||||
}
|
||||
interface ResumableSessionStore {
|
||||
get(id: string): Promise<ResumableUploadSession | null>;
|
||||
put(session: ResumableUploadSession): Promise<void>;
|
||||
delete(id: string): Promise<void>;
|
||||
list(): Promise<ResumableUploadSession[]>;
|
||||
}
|
||||
declare function memoryResumableSessionStore(): ResumableSessionStore;
|
||||
interface ResumableUploadManagerOptions {
|
||||
driver: StorageDriver;
|
||||
sessions?: ResumableSessionStore;
|
||||
maxBytes?: number;
|
||||
chunkSize?: number;
|
||||
maxSessions?: number;
|
||||
ttlMs?: number;
|
||||
accept?: string[];
|
||||
prefix?: string;
|
||||
publicUrl?: (key: string) => string | null;
|
||||
now?: () => number;
|
||||
}
|
||||
interface CreateResumableUpload {
|
||||
name: string;
|
||||
type?: string;
|
||||
size: number;
|
||||
chunkSize?: number;
|
||||
}
|
||||
interface ResumableChunkResult {
|
||||
receivedChunks: number;
|
||||
totalChunks: number;
|
||||
complete: boolean;
|
||||
file?: UploadedFile;
|
||||
}
|
||||
interface ResumableUploadManager {
|
||||
create(input: CreateResumableUpload): Promise<ResumableUploadSession>;
|
||||
uploadChunk(id: string, index: number, data: Uint8Array, sha256?: string): Promise<ResumableChunkResult>;
|
||||
status(id: string): Promise<{
|
||||
received: number[];
|
||||
totalChunks: number;
|
||||
expiresAt: number;
|
||||
} | null>;
|
||||
cancel(id: string): Promise<boolean>;
|
||||
prune(): Promise<number>;
|
||||
}
|
||||
declare function createResumableUploadManager(options: ResumableUploadManagerOptions): ResumableUploadManager;
|
||||
|
||||
interface QuotaUsage {
|
||||
owner: string;
|
||||
bytes: number;
|
||||
objects: number;
|
||||
updatedAt: number;
|
||||
}
|
||||
interface QuotaStore {
|
||||
get(owner: string): Promise<QuotaUsage>;
|
||||
reserve(owner: string, bytes: number, limits: {
|
||||
bytes: number;
|
||||
objects?: number;
|
||||
}): Promise<boolean>;
|
||||
release(owner: string, bytes: number): Promise<void>;
|
||||
}
|
||||
declare function memoryQuotaStore(): QuotaStore;
|
||||
interface QuotaSqlClient {
|
||||
query<T = any>(sql: string, parameters?: unknown[]): Promise<{
|
||||
rows: T[];
|
||||
}>;
|
||||
}
|
||||
/** PostgreSQL quota accounting using a single atomic conditional upsert. */
|
||||
declare function postgresQuotaStore(db: QuotaSqlClient, table?: string): QuotaStore;
|
||||
declare const POSTGRES_QUOTA_SCHEMA = "CREATE TABLE IF NOT EXISTS wrnexus_storage_quota (owner text PRIMARY KEY, bytes bigint NOT NULL DEFAULT 0, objects integer NOT NULL DEFAULT 0, updated_at bigint NOT NULL);";
|
||||
interface MultipartObjectClient {
|
||||
create(key: string, meta: PutMeta): Promise<string>;
|
||||
uploadPart(uploadId: string, key: string, part: number, bytes: Uint8Array): Promise<string>;
|
||||
complete(uploadId: string, key: string, parts: Array<{
|
||||
part: number;
|
||||
etag: string;
|
||||
}>): Promise<void>;
|
||||
abort(uploadId: string, key: string): Promise<void>;
|
||||
}
|
||||
declare function multipartUpload(client: MultipartObjectClient, key: string, bytes: Uint8Array, meta: PutMeta, options?: {
|
||||
partBytes?: number;
|
||||
concurrency?: number;
|
||||
}): Promise<void>;
|
||||
interface TemporaryObject {
|
||||
key: string;
|
||||
expiresAt: number;
|
||||
}
|
||||
declare function createTemporaryObjectCleaner(driver: StorageDriver, options?: {
|
||||
now?: () => number;
|
||||
limit?: number;
|
||||
}): {
|
||||
track(key: string, ttlMs: number): void;
|
||||
cleanup(at?: number): Promise<number>;
|
||||
snapshot: () => {
|
||||
tracked: number;
|
||||
nextExpiry: number | undefined;
|
||||
};
|
||||
};
|
||||
interface VideoTranscodeOptions {
|
||||
format: "mp4" | "webm";
|
||||
width?: number;
|
||||
height?: number;
|
||||
videoBitrateKbps?: number;
|
||||
}
|
||||
declare function ffmpegVideoTranscoder(options?: {
|
||||
executable?: string;
|
||||
spawn?: (args: string[]) => {
|
||||
exited: Promise<number>;
|
||||
};
|
||||
}): (input: string, output: string, config: VideoTranscodeOptions) => Promise<void>;
|
||||
|
||||
export { type CreateResumableUpload, type LocalStoreConfig, type MultipartObjectClient, POSTGRES_QUOTA_SCHEMA, type PutMeta, type QuotaSqlClient, type QuotaStore, type QuotaUsage, type ResumableChunkResult, type ResumableSessionStore, type ResumableUploadManager, type ResumableUploadManagerOptions, type ResumableUploadSession, type S3StoreConfig, type SignedFileToken, type StorageConfig, type StorageDriver, type Store, type StoreAccess, type StoreConfig, type StoredObject, type TemporaryObject, UPLOADS_PREFIX, UPLOAD_JS_HREF, UPLOAD_RUNTIME, UploadError, type UploadInspection, type UploadOptions, type UploadPolicy, UploadPolicyError, type UploadScanInput, type UploadScanResult, type UploadedFile, type VideoTranscodeOptions, accepts, assertUploadedFiles, configureStorage, contentTypeOf, createResumableUploadManager, createSignedFileToken, createTemporaryObjectCleaner, encodeKey, enforceUploadPolicy, extForType, extOf, ffmpegVideoTranscoder, formatFileSize, getStore, handleUpload, hasStorage, inspectUpload, localDriver, memoryQuotaStore, memoryResumableSessionStore, multipartUpload, postgresQuotaStore, s3Driver, safeObjectKey, serveFromStore, serveStoredFile, sha256Hex, signS3, sniffContentType, storeNames, storedUrl, upload, uploadAccept, uploadedFileMap, uploaderAttributes, verifySignedFileToken };
|
||||
</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>Configure local and S3 stores</h3><pre data-language="ts"><code>// wrnexus.config.ts
|
||||
import type { AppConfig } from "@wrnexus/styles";
|
||||
|
||||
@@ -451,9 +630,9 @@ await getStore("docs").driver.delete(files[0].key);</code></pre></arti
|
||||
></div></code></pre></article><article class="example-card"><h3>Serve private files behind application authentication</h3><pre data-language="ts"><code>// app/api/files/[key].ts
|
||||
import { serveFromStore } from "@wrnexus/uploader";
|
||||
export const GET = serveFromStore("docs"); // your middleware decides who gets in</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="#usage">Usage</a><a class="toc-level-4" href="#configure-local-and-s3-stores">Configure local and S3 stores</a><a class="toc-level-4" href="#upload-from-an-api-route-or-server-function">Upload from an API route or server function</a><a class="toc-level-4" href="#add-a-client-upload-widget">Add a client upload widget</a><a class="toc-level-4" href="#serve-private-files-behind-application-authentication">Serve private files behind application authentication</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-3" href="#notes">Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
||||
<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="#usage">Usage</a><a class="toc-level-4" href="#configure-local-and-s3-stores">Configure local and S3 stores</a><a class="toc-level-4" href="#upload-from-an-api-route-or-server-function">Upload from an API route or server function</a><a class="toc-level-4" href="#add-a-client-upload-widget">Add a client upload widget</a><a class="toc-level-4" href="#serve-private-files-behind-application-authentication">Serve private files behind application authentication</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-3" href="#notes">Notes</a><a class="toc-level-3" href="#helper-and-component-kit">Helper and component kit</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.7.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>
|
||||
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.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