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

docs: publish package usage examples for 0.2.24

Browse Source
This commit is contained in:
Clintchiz
2026-07-13 20:58:28 +05:30
parent b07ef5058a
commit 379553bdf7
79 changed files with 1542 additions and 894 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/pages/packages/db.wrn
+38 -13
View File
@@ -10,12 +10,12 @@ page wrnexusdb {
<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/db</h2><p>Database adapters, typed queries, models, migrations, and sessions.</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/db</h1><p>Database adapters, typed queries, models, migrations, and sessions.</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/db@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"><blockquote>The database layer for WRNexusJS: TS models as the single source of truth for DDL, validation, and result typing, plus a driver-based <code>Db</code> client, migrations, and a sqlc-style query generator.</blockquote>
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Data</span><h2>@wrnexus/db</h2><p>Database adapters, typed queries, models, migrations, and sessions.</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/db</h1><p>Database adapters, typed queries, models, migrations, and sessions.</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/db@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"><blockquote>The database layer for WRNexusJS: TS models as the single source of truth for DDL, validation, and result typing, plus a driver-based <code>Db</code> client, migrations, and a sqlc-style query generator.</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/db</code> is the server-side data layer. You describe tables as TypeScript models (the <code>v</code> column builder + <code>table()</code>); those models drive migrations, coerce raw DB rows into typed objects, and feed the query generator. A thin <code>Driver</code> interface is implemented by adapters for SQLite (<code>bun:sqlite</code>), Postgres/MySQL (<code>Bun.SQL</code>), and MongoDB. The <code>Db</code> client adds ergonomics — model-mapped <code>all</code>/<code>one</code>, transactions, <code>createTable</code>, pagination, and batched relation loading. A process-wide registry (<code>getDb</code>/<code>setDb</code>) exposes configured connections to pages and API routes. Reach for it whenever a WRNexusJS app needs persistence.</p>
@@ -303,20 +303,45 @@ interface RelationOptions&lt;C&gt; &#123;
declare function loadRelated&lt;P extends Row, C extends Row = Row&gt;(db: Db, parents: P[], opts: RelationOptions&lt;C&gt;): Promise&lt;(P &amp; Record&lt;string, C | C[] | null&gt;)[]&gt;;
export &#123; Db, Dialect, type Migration, Model, type ModelRef, type PageOptions, type Paginated, type QueryDef, type QueryKind, type RelationOptions, Row, appliedMigrations, closeDatabases, databaseNames, generateQueriesFile, getDb, hasDb, loadMigrations, loadRelated, migrate, paginate, parseMigration, parseQueries, registerDb, rollback, scaffoldMigration, setDb, status &#125;;
</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="bash"><code>bun add @wrnexus/db</code></pre></article><article class="example-card"><h3>Example 2</h3><pre data-language="ts"><code>import &#123; v, table &#125; from &quot;@wrnexus/db&quot;;
</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>Define models, connect, create tables, and query with typed results</h3><pre data-language="ts"><code>import &#123; v, table, createDb &#125; from &quot;@wrnexus/db&quot;;
import &#123; sqlite &#125; from &quot;@wrnexus/db/sqlite&quot;;
const users = table(&quot;users&quot;, &#123;
id: v.id(), // auto-increment primary key
const users = table&lt;&#123; id: number; email: string; name: string | null &#125;&gt;(&quot;users&quot;, &#123;
id: v.id(),
email: v.text().unique(),
name: v.text().optional(), // NULLable
age: v.int().default(0),
active: v.bool().default(true),
createdAt: v.timestamp().default(&quot;now&quot;), // CURRENT_TIMESTAMP
&#125;);</code></pre></article><article class="example-card"><h3>Example 3</h3><pre data-language="ts"><code>createDb(driver: Driver): Db</code></pre></article><article class="example-card"><h3>Example 4</h3><pre data-language="ts"><code>const users = await getDb().all(&quot;SELECT * FROM users&quot;);
const events = await getDb(&quot;analytics&quot;).all(&quot;SELECT * FROM hits&quot;);</code></pre></article></div></section></article>
name: v.text().optional(),
createdAt: v.timestamp().default(&quot;now&quot;),
&#125;);
const db = createDb(sqlite(&quot;file:./dev.db&quot;));
await db.createTable(users);
await db.exec(&quot;INSERT INTO users (email) VALUES (?)&quot;, [&quot;a@b.com&quot;]);
const list = await db.all(&quot;SELECT * FROM users&quot;, [], users); // rows typed + coerced
const one = await db.one(&quot;SELECT * FROM users WHERE id = ?&quot;, [1], users);
await db.tx(async (tx) =&gt; &#123;
await tx.exec(&quot;UPDATE users SET name = ? WHERE id = ?&quot;, [&quot;Ada&quot;, 1]);
&#125;);</code></pre></article><article class="example-card"><h3>Resolve a config to a live SQL Db, and register it</h3><pre data-language="ts"><code>import &#123; connectFromConfig &#125; from &quot;@wrnexus/db/connect&quot;;
import &#123; setDb, getDb &#125; from &quot;@wrnexus/db&quot;;
setDb(connectFromConfig(&#123; driver: &quot;sqlite&quot;, url: &quot;file:./dev.db&quot; &#125;, process.cwd()));
const rows = await getDb().all(&quot;SELECT * FROM users&quot;);</code></pre></article><article class="example-card"><h3>Run migrations and paginate</h3><pre data-language="ts"><code>import &#123; migrate, paginate &#125; from &quot;@wrnexus/db&quot;;
await migrate(db, &quot;app/db/migrations&quot;);
const pageTwo = await paginate(
db,
&#123; sql: &quot;SELECT * FROM users ORDER BY id&quot;, model: users &#125;,
&#123; page: 2 &#125;,
);</code></pre></article><article class="example-card"><h3>MongoDB (document API)</h3><pre data-language="ts"><code>import &#123; mongo &#125; from &quot;@wrnexus/db/mongo&quot;;
const mdb = await mongo(process.env.MONGO_URL!, &quot;app&quot;);
const repo = mdb.collection(users);
await repo.insert(&#123; email: &quot;a@b.com&quot; &#125;);
const active = await repo.find(&#123; active: true &#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="#api">API</a><a class="toc-level-4" href="#schema-v-table-column">Schema — v, table, Column</a><a class="toc-level-4" href="#driver-client-createdb-db-driver">Driver &amp; client — createDb, Db, Driver</a><a class="toc-level-4" href="#client-registry-getdb-setdb">Client registry — getDb / setDb</a><a class="toc-level-4" href="#adapters">Adapters</a><a class="toc-level-4" href="#migrations">Migrations</a><a class="toc-level-4" href="#query-generator-sqlc-style">Query generator (sqlc-style)</a><a class="toc-level-4" href="#query-helpers">Query helpers</a><a class="toc-level-4" href="#session-store">Session store</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-3" href="#configuration">Configuration</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>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>
}
}