`@noy-db/as-*` — Portable-artefact exports

How data leaves the vault — and, for most packages, comes back in. Each as-* package takes an open vault and produces a portable artefact — spreadsheet, structured text, SQL dump, encrypted bundle — or the reverse.

The as- prefix reads as "export as XLSX / CSV / NoyDB." This family is the read/write-side transform layer at the vault's edge: pure functions that turn decrypted records into a file-shaped artefact, and (for most formats) a symmetric reader that turns the artefact back into an import plan. Every call is gated by the caller's exportCapability / importCapability on their keyring — the per-user record holding role, permissions, and wrapped keys.

Two tiers, one gate

Every as-* artefact sits in one of two tiers, and both pass the same capability check on the caller's keyring. The plaintext tier emits decrypted records in an open, portable shape (CSV, XLSX, JSON, NDJSON, XML, SQL, …) — gated by exportCapability: 'plaintext'. The bundle tier is the encrypted, re-importable .noydb container (noydb), which never leaves ciphertext — gated by exportCapability: 'bundle' (and the matching importCapability to read one back). A role without the tier's capability cannot invoke the export at all. The cloud projection aws-s3 is the one exception — it writes an object projection and is not vault-gated.

What collections costs

vault.export(fmt, { collections: ['invoices'] }) always narrows what the artefact contains. Whether it also narrows what the hub reads depends on the hub version you have installed, so check yours before planning around it.

From @noy-db/hub 0.9.0 the scope is passed down into the read: the hub lists only the requested collections, so an excluded collection is neither fetched nor decrypted, and the option is the exposure control it reads like.

Through @noy-db/hub 0.8.x it does not. Each collection in the vault is read and decrypted, and the excluded ones are discarded afterwards.

::: warning On 0.8.x, this is an output filter and nothing more Passing collections on a large vault costs the same decryption work as exporting all of it. If you are reaching for it to keep a big collection out of a hot path, or to limit how much plaintext the export touches, on 0.8.x it does neither. Correct for shaping the artefact, ineffective as a performance or exposure control — upgrade to 0.9.0 or later if you need the narrower read. :::

To settle which behaviour your installed hub has, ask the compiler rather than any prose, this page included:

import type { ExportStreamOptions } from '@noy-db/hub'

// Compiles only on a hub whose export read narrows.
const scoped: ExportStreamOptions = { collections: ['invoices'] }

Where the read does not narrow, that line fails with TS2353 — 'collections' does not exist in type 'ExportStreamOptions'. ⛔ Do not answer this by grepping the type for the word: collections appears in that interface's own prose on versions that have no such field, so a text search says yes when the answer is no. The assignment is the test; excess-property checking is what makes it one.

Catalog

10 packages across five shapes:

Spreadsheet

Structured text

Database

Cloud

Composite

Encrypted bundle

Compare