stable

Run the showcases

Clone the docs repo and run the full showcase suite — every feature demonstrated as a vitest test that reads top-to-bottom as a tutorial.

Every capability documented on this site is backed by a showcase — a vitest test that exercises the feature end-to-end against the published @noy-db/* packages and reads top-to-bottom as a tutorial. Each file doubles as test, demo, and copy-paste source. If a claim on these pages matters to your decision, you can run its proof yourself in a couple of minutes.

Clone and run

git clone https://github.com/noy-db/docs
cd noy-db-docs
pnpm install
pnpm --filter @noy-db/showcases test

The full suite runs green with no credentials and no cloud account — every store and auth method is exercised locally. The handful of real-provider showcases (AWS, Google/Apple/LINE OIDC, SMTP) skip cleanly unless you set their variables in showcases/.env; see showcases/README.md for the list.

Run a single showcase by file:

cd showcases
pnpm vitest run src/16-with-crdt.showcase.test.ts

Catalog

132 files — 117 numbered showcases plus 15 recipe walkthroughs. Numbering is sparse by design (retired numbers are not reused).

Numbered showcases

#	What it demonstrates	File
00	Hello, vault	`00-hello-vault.showcase.test.ts`
01	Storage: in-memory	`01-storage-memory.showcase.test.ts`
02	Storage: JSON files on disk	`02-storage-file.showcase.test.ts`
03	Storage: IndexedDB (browser)	`03-storage-browser-idb.showcase.test.ts`
05	Storage: routing across two backends	`05-storage-routing.showcase.test.ts`
06	Multi-user: grant, revoke, role tiers	`06-multi-user.showcase.test.ts`
07	withHistory()	`07-with-history.showcase.test.ts`
08	withBlobs()	`08-with-blobs.showcase.test.ts`
09	withI18n()	`09-with-i18n.showcase.test.ts`
10	withReduce()	`10-with-aggregate.showcase.test.ts`
11	withIndexing()	`11-with-indexing.showcase.test.ts`
12	Joins (always-core today)	`12-with-joins.showcase.test.ts`
13	Live queries (always-core today)	`13-with-live.showcase.test.ts`
14	withCrdt() (Yjs interop)	`14-with-crdt.showcase.test.ts`
15	withSync()	`15-with-sync.showcase.test.ts`
16	withShadow() (read-only frames)	`16-with-shadow.showcase.test.ts`
17	withHistory() time-machine reads (`vault.at(t)`)	`17-with-history-time-machine.showcase.test.ts`
18	withPeriods()	`18-with-periods.showcase.test.ts`
19	withConsent()	`19-with-consent.showcase.test.ts`
20	withTransactions() (atomic multi-record ops)	`20-with-transactions.showcase.test.ts`
21	Bundle (.noydb container format)	`21-with-bundle.showcase.test.ts`
22	Secret unlock (always-on)	`22-on-secret.showcase.test.ts`
23	WebAuthn passkey unlock	`23-on-webauthn.showcase.test.ts`
24	OIDC split-key unlock	`24-on-oidc.showcase.test.ts`
25	Magic-link delegated access	`25-on-magic-link.showcase.test.ts`
26	Printable recovery codes	`26-on-recovery.showcase.test.ts`
27	Shamir secret sharing for KEK recovery	`27-on-shamir.showcase.test.ts`
28	TOTP (RFC 6238) second factor	`28-on-totp.showcase.test.ts`
29	Email OTP with transport abstraction	`29-on-email-otp.showcase.test.ts`
30	Session-resume PIN	`30-on-pin.showcase.test.ts`
31	Lockout, duress, honeypot	`31-on-threat.showcase.test.ts`
32	as-csv (plaintext export)	`32-as-csv.showcase.test.ts`
33	as-xlsx (Excel multi-sheet export)	`33-as-xlsx.showcase.test.ts`
34	as-json (structured multi-collection export)	`34-as-json.showcase.test.ts`
35	as-zip (composite records + attachments)	`35-as-zip.showcase.test.ts`
36	as-noydb (encrypted .noydb bundle)	`36-as-noydb.showcase.test.ts`
37	in-vue (Vue 3 composables)	`37-in-vue.showcase.test.ts`
38	in-pinia (defineNoydbStore)	`38-in-pinia.showcase.test.ts`
39	in-yjs (Y.Doc-typed collections)	`39-in-yjs.showcase.test.ts`
40	in-svelte (zero-dep Svelte stores)	`40-in-svelte.showcase.test.ts`
41	in-react (hooks)	`41-in-react.showcase.test.tsx`
42	in-solid (Signal-based reactivity)	`42-in-solid.showcase.test.ts`
43	in-zustand (StateCreator factory)	`43-in-zustand.showcase.test.ts`
44	in-tanstack-query (collectionListOptions etc.)	`44-in-tanstack-query.showcase.test.ts`
45	in-tanstack-table (table-state ↔ Query DSL bridge)	`45-in-tanstack-table.showcase.test.ts`
46	in-ai (LLM tool-calling adapter)	`46-in-ai.showcase.test.ts`
47	in-rest (HTTP ciphertext relay)	`47-in-rest.showcase.test.ts`
48	in-nextjs (cookie-session helpers)	`48-in-nextjs.showcase.test.ts`
49	by-tabs (BroadcastChannel multi-tab transport)	`49-by-tabs.showcase.test.ts`
50	as-json import (preview + apply with three policies)	`50-as-json-import.showcase.test.ts`
51	as-blob / as-xml / as-xlsx readers	`51-as-readers-import.showcase.test.ts`
52	`.noydb` bundle: per-recipient expiry + record filters	`52-as-noydb-bundle-extras.showcase.test.ts`
55	Storage: meter (drop-in metrics wrapper)	`55-storage-meter.showcase.test.ts`
56	Storage: probe (5-axis suitability check)	`56-storage-probe.showcase.test.ts`
70	User envelope: per-principal profile + preferences	`70-user-envelope.showcase.test.ts`
71	on-password tier-2 capability matrix	`71-on-password-tier2.showcase.test.ts`
72	on-webauthn real-provider via Playwright virtual authenticator	`72-on-webauthn-virtual.showcase.test.ts`
73	OIDC vault unlock via Sign in with Google (IdP bridge)	`73-on-oidc-google.showcase.test.ts`
74	OIDC vault unlock via Sign in with Apple (IdP bridge)	`74-on-oidc-apple.showcase.test.ts`
75	OIDC vault unlock via LINE Login (IdP bridge)	`75-on-oidc-line.showcase.test.ts`
76	TOTP (RFC 6238) interop with Google Authenticator	`76-on-totp-google-authenticator.showcase.test.ts`
77	on-email-otp delivered via real SMTP	`77-on-email-otp-smtp.showcase.test.ts`
78	on-magic-link delivered via real SMTP	`78-on-magic-link-smtp.showcase.test.ts`
79	withGuard (accounting end-to-end)	`79-with-guard.showcase.test.ts`
80	withDerivation (Dim 14)	`80-with-derivation.showcase.test.ts`
81	withMaterializedView, eager refresh (Dim 14 v2)	`81-with-mv-eager.showcase.test.ts`
82	withMaterializedView, lazy lifecycle (Dim 14 v2)	`82-with-mv-lazy.showcase.test.ts`
83	withOverlayedView (Dim 14 v2)	`83-with-overlay.showcase.test.ts`
84	declaredDeterministicPredicates (Dim 14 v2)	`84-with-mv-predicates.showcase.test.ts`
85	multi-key groupBy	`85-with-multikey-groupby.showcase.test.ts`
86	UNION MV (withMaterializedView reads multiple sibling collections)	`86-with-union-mv.showcase.test.ts`
87	`noy-db describe` audit pipeline	`87-noydb-describe.showcase.test.ts`
88	Transferable partition bundles (extract → adopt → own)	`88-transferable-partition.showcase.test.ts`
89	Document attestation: revocation publishing	`89-attestation-revocation.showcase.test.ts`
90	in-devtools (createInspector)	`90-in-devtools.showcase.test.ts`
91	in-devtools records paging + write monitor	`91-in-devtools-records-monitor.showcase.test.ts`
92	Cross-join query primitive	`92-with-cross-join.showcase.test.ts`
93	Snapshot lifecycle (withSnapshots)	`93-with-snapshots.showcase.test.ts`
94	i18n hardening (per-layer onMissing, substitute, script, dictKey parity)	`94-with-i18n-hardening.showcase.test.ts`
95	in-pinia reactive i18n	`95-in-pinia-i18n.showcase.test.ts`
96	automatic snapshot cadence (rolling auto key)	`96-snapshots-auto-cadence.showcase.test.ts`
97	AWS credential broker: enroll, rolling credentials, store wiring	`97-broker-aws.showcase.test.ts`
98	Storage: Google Drive (real provider, appDataFolder + bundle)	`98-storage-drive.showcase.test.ts`
99	Storage: iCloud Drive (real provider, macOS only)	`99-storage-icloud.showcase.test.ts`
100	erasable blobs (per-blob CEK crypto-shred)	`100-with-erasable-blobs.showcase.test.ts`
101	transitionGuard (state-machine lifecycle)	`101-transition-guard.showcase.test.ts`
102	formatted sequences (fiscal numbering)	`102-formatted-sequence.showcase.test.ts`
103	refArray (many-to-many integrity)	`103-ref-array.showcase.test.ts`
104	reverse-denormalization (FK derivation triggers)	`104-reverse-denorm.showcase.test.ts`
105	rollups (aggregate onto a parent field)	`105-rollup.showcase.test.ts`
106	in-pinia dynamic vault resolver (federation routing)	`106-in-pinia-dynamic-vault.showcase.test.ts`
107	vault.link (managed many-to-many junction)	`107-vault-link.showcase.test.ts`
108	staticDict() code-provided dictionary (#291)	`108-with-static-dict.showcase.test.ts`
111	Scan-mode full-text search (collection.search)	`111-scan-search.showcase.test.ts`
112	debug-plaintext store mode (#413)	`112-debug-plaintext-mode.showcase.test.ts`
113	external (direct-serve) blob fields (#412)	`113-external-blobs.showcase.test.ts`
114	as-xlsx smart workbook (#414 P1)	`114-as-xlsx-smart.showcase.test.ts`
115	as-xlsx global LANG cell (#414 P2)	`115-as-xlsx-lang-cell.showcase.test.ts`
116	as-xlsx groupBy summary sheets (#414 P3)	`116-as-xlsx-summary.showcase.test.ts`
117	as-xlsx smart import (#414 P4)	`117-as-xlsx-smart-import.showcase.test.ts`
118	as-xlsx Google-Sheets QUERY dialect (#414 P5)	`118-as-xlsx-sheets-query.showcase.test.ts`
119	as-xlsx schema inference (#414 P4 Mode B)	`119-as-xlsx-infer-schema.showcase.test.ts`
120	Client-initiated portability + withdrawal (#199)	`120-client-portability-withdrawal.showcase.test.ts`
121	densifyOnWrite + i18n:script-violation event (#435)	`121-with-i18n-densify.showcase.test.ts`
122	Client-side lexical retrieval (collection.retrieve) — #308 L1	`122-with-retrieve.showcase.test.ts`
123	Persisted lexical index (textIndexPersist) — #308 L1.5	`123-persisted-index.showcase.test.ts`
124	Semantic / vector retrieval (collection.retrieve mode:'semantic' + similarTo) — #308 L2	`124-semantic-retrieve.showcase.test.ts`
125	Hybrid retrieval (collection.retrieve mode:'hybrid' + fuseRetrieval) — #308 L3	`125-hybrid-retrieve.showcase.test.ts`
126	collection.describe() + fieldMeta: two consumers, one source (#483)	`126-describe-field-metadata.showcase.test.ts`
127	withArchive() cold-storage sweep	`127-with-archive.showcase.test.ts`
128	classified fields (seal, digest, reveal)	`128-with-classified.showcase.test.ts`
129	withCustody() — full operation, no ownership	`129-with-custody.showcase.test.ts`
130	withForget() crypto-shred	`130-with-forget.showcase.test.ts`
131	withLazy() bounded-memory reads	`131-with-lazy.showcase.test.ts`
132	deferred numbering (gap-free without CAS)	`132-deferred-numbering.showcase.test.ts`
133	withSealedRecord() single-record disclosure	`133-sealed-record.showcase.test.ts`
134	AWS credential broker rollover: rolling credentials across a session	`134-broker-aws-rollover.showcase.test.ts`

Recipe walkthroughs

#	What it demonstrates	File
·	Offline document-attestation verifier	`recipe-attestation-verifier.recipe.test.ts`
·	AWS-KMS PDF attestation (generation side, CI-safe slice)	`recipe-aws-kms-pdf-attestation.recipe.test.ts`
·	Browser durability	`recipe-browser-durability.recipe.test.ts`
·	Confidential HR records (record tiers end-to-end)	`recipe-confidential-hr.recipe.test.ts`
·	Passwordless tier-2 auth via a managed OIDC provider (AWS Cognito)	`recipe-passwordless-oidc.recipe.test.ts`
·	User preferences (the reference UserEnvelope shape)	`recipe-user-preferences.recipe.test.ts`
1	Personal encrypted notebook	`recipe-personal-notebook.recipe.test.ts`
2	Accounting application	`recipe-accounting-app.recipe.test.ts`
3	Real-time collaborative app	`recipe-realtime-crdt.recipe.test.ts`
4	Analytics-heavy querying	`recipe-analytics.recipe.test.ts`
8	React invoice app	`recipe-react-invoices.recipe.test.tsx`
9	Unlock ceremonies	`recipe-unlock-ceremonies.recipe.test.ts`
10	Export & portability	`recipe-export-portability.recipe.test.ts`
11	Search & RAG	`recipe-search-rag.recipe.test.ts`
12	Production cloud store	`recipe-cloud-store.recipe.test.ts`

Run the showcases

Clone and run

Catalog

Numbered showcases

Recipe walkthroughs

See also