docs: publish package usage examples for 0.2.24
This commit is contained in:
@@ -10,13 +10,14 @@ 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="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.23</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.2.24</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="/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="page package-page">
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Data</span><h2>@wrnexus/uploader</h2><p>Validated local/S3 uploads and secure file serving.</p><span class="status status-beta">Private preview · 0.2.23</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Data · Preview</span><h1>@wrnexus/uploader</h1><p>Validated local/S3 uploads and secure file serving.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/uploader@0.2.23</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" class="prose"><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="configure">Configure</h3>
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Data</span><h2>@wrnexus/uploader</h2><p>Validated local/S3 uploads and secure file serving.</p><span class="status status-beta">Private preview · 0.2.24</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Data · Preview</span><h1>@wrnexus/uploader</h1><p>Validated local/S3 uploads and secure file serving.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/uploader@0.2.24</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" class="prose"><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
|
||||
import type { AppConfig } from "@wrnexus/styles";
|
||||
|
||||
@@ -46,7 +47,7 @@ const config: AppConfig = {
|
||||
},
|
||||
};
|
||||
export default config;</code></pre>
|
||||
<h3 id="upload-server">Upload (server)</h3>
|
||||
<h4 id="upload-from-an-api-route-or-server-function">Upload from an API route or server function</h4>
|
||||
<pre data-language="ts"><code>// app/api/upload.ts — one-liner
|
||||
import { handleUpload } from "@wrnexus/uploader";
|
||||
export const POST = handleUpload({ store: "public" });
|
||||
@@ -56,7 +57,7 @@ import { upload, getStore } from "@wrnexus/uploader";
|
||||
const { files } = await upload("docs", ctx.req, { prefix: "invoices" });
|
||||
await getStore("docs").driver.delete(files[0].key);</code></pre>
|
||||
<p>Uploads are validated (size + type), stored under a random, collision-proof, path-safe key (the client filename is never used as a path), and — for public stores — returned with a servable <code>url</code>.</p>
|
||||
<h3 id="widget-client">Widget (client)</h3>
|
||||
<h4 id="add-a-client-upload-widget">Add a client upload widget</h4>
|
||||
<p>Drop the element anywhere; the runtime (drag-and-drop, per-file progress, success/failed states) is auto-injected on pages that contain <code>data-uploader</code>:</p>
|
||||
<pre data-language="html"><code><div
|
||||
data-uploader="public"
|
||||
@@ -78,7 +79,7 @@ await getStore("docs").driver.delete(files[0].key);</code></pre>
|
||||
<li><code>wrnexus:upload</code> — <code>detail: { file, result: { key, url, name, size, type } }</code></li>
|
||||
<li><code>wrnexus:upload-error</code> — <code>detail: { file, error }</code></li>
|
||||
</ul>
|
||||
<h3 id="serve-files">Serve files</h3>
|
||||
<h4 id="serve-private-files-behind-application-authentication">Serve private files behind application authentication</h4>
|
||||
<ul>
|
||||
<li><strong>Public + local</strong> → served automatically at <code>/__wrnexus/uploads/<store>/<key></code> (immutable cache).</li>
|
||||
<li><strong>Public + S3</strong> → <code>url</code> is the bucket/CDN URL directly.</li>
|
||||
@@ -372,7 +373,7 @@ declare function accepts(accept: string[] | undefined, file: {
|
||||
}): boolean;
|
||||
|
||||
export { type LocalStoreConfig, type PutMeta, type S3StoreConfig, type StorageConfig, type StorageDriver, type Store, type StoreAccess, type StoreConfig, type StoredObject, UPLOADS_PREFIX, UPLOAD_JS_HREF, UPLOAD_RUNTIME, UploadError, type UploadOptions, type UploadedFile, accepts, configureStorage, contentTypeOf, encodeKey, extForType, extOf, getStore, handleUpload, hasStorage, localDriver, s3Driver, serveFromStore, serveStoredFile, sha256Hex, signS3, storeNames, storedUrl, upload };
|
||||
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Examples are taken from this package's installed documentation and must be evaluated with its requirements and stability notes.</p><div class="example-grid"><article class="example-card"><h3>Example 1</h3><pre data-language="ts"><code>// wrnexus.config.ts
|
||||
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Examples are taken from this package's installed documentation and must be evaluated with its requirements and stability notes.</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";
|
||||
|
||||
const config: AppConfig = {
|
||||
@@ -400,22 +401,30 @@ const config: AppConfig = {
|
||||
},
|
||||
},
|
||||
};
|
||||
export default config;</code></pre></article><article class="example-card"><h3>Example 2</h3><pre data-language="ts"><code>// app/api/upload.ts — one-liner
|
||||
export default config;</code></pre></article><article class="example-card"><h3>Upload from an API route or server function</h3><pre data-language="ts"><code>// app/api/upload.ts — one-liner
|
||||
import { handleUpload } from "@wrnexus/uploader";
|
||||
export const POST = handleUpload({ store: "public" });
|
||||
// → { ok: true, files: [{ key, url, name, type, size }] }</code></pre></article><article class="example-card"><h3>Example 3</h3><pre data-language="ts"><code>// or drive it yourself, anywhere you have the request
|
||||
// → { ok: true, files: [{ key, url, name, type, size }] }</code></pre></article><article class="example-card"><h3>Upload from an API route or server function</h3><pre data-language="ts"><code>// or drive it yourself, anywhere you have the request
|
||||
import { upload, getStore } from "@wrnexus/uploader";
|
||||
const { files } = await upload("docs", ctx.req, { prefix: "invoices" });
|
||||
await getStore("docs").driver.delete(files[0].key);</code></pre></article><article class="example-card"><h3>Example 4</h3><pre data-language="html"><code><div
|
||||
await getStore("docs").driver.delete(files[0].key);</code></pre></article><article class="example-card"><h3>Add a client upload widget</h3><pre data-language="html"><code><div
|
||||
data-uploader="public"
|
||||
data-endpoint="/api/upload"
|
||||
data-accept="image/*"
|
||||
data-max="10000000"
|
||||
data-multiple
|
||||
></div></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="#configure">Configure</a><a class="toc-level-3" href="#upload-server">Upload (server)</a><a class="toc-level-3" href="#widget-client">Widget (client)</a><a class="toc-level-3" href="#serve-files">Serve files</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>
|
||||
></div></code></pre></article><article class="example-card"><h3>Add a client upload widget</h3><pre data-language="html"><code><div
|
||||
data-component="file-upload"
|
||||
store="public"
|
||||
endpoint="/api/upload"
|
||||
accept="image/*"
|
||||
multiple="true"
|
||||
></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>
|
||||
</main>
|
||||
<footer>WRNexusJS 0.2.23 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
<footer>WRNexusJS 0.2.24 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
</div>
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user