Jason Tudisco
63ce105114
Root README: updated variant table, API docs with joinRoom/leaveRoom, Nostr events, build instructions. Paste README: added paste-nostr description and cross-device sync info. Nostr README: full documentation for dual-sync architecture. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
141 lines
5.0 KiB
Markdown
141 lines
5.0 KiB
Markdown
# Paste -- Demo App
|
|
|
|
A minimal paste-bin app used to test and compare all five IndexSyncFile storage variants. Each version compiles to a single self-contained HTML file.
|
|
|
|
## What it does
|
|
|
|
1. You type or paste text into a text area
|
|
2. It saves automatically to a local database
|
|
3. You pick a sync folder on disk
|
|
4. Open the same HTML file in another browser window, point it at the same folder
|
|
5. Both windows stay in sync (auto-sync every 3 seconds)
|
|
|
|
That's it. No server, no accounts, no network. Just two browser windows and a folder.
|
|
|
|
The Nostr variant adds optional **cross-device sync** over public Nostr relays via WebSocket. Enter a shared room key and devices sync over the internet too.
|
|
|
|
## Five versions
|
|
|
|
| File | Storage engine | Sync transport | Opens from `file://`? | Size |
|
|
|------|---------------|----------------|----------------------|------|
|
|
| `paste-indexeddb.html` | IndexedDB (browser built-in) | Folder | Yes | ~23 KB |
|
|
| `paste-nedb.html` | NeDB (in-memory, MongoDB-style) | Folder | Yes | ~115 KB |
|
|
| `paste-sql-js.html` | sql.js (SQLite via asm.js) | Folder | Yes | ~1.9 MB |
|
|
| `paste-sqlite.html` | SQLite WASM (official build) | Folder | No (needs HTTP) | ~1.4 MB |
|
|
| `paste-nostr.html` | IndexedDB | **Folder + Nostr** | Yes | ~75 KB |
|
|
|
|
### paste-indexeddb.html
|
|
|
|
Uses the browser's built-in IndexedDB. Smallest file, fastest startup, zero dependencies. The best choice for most use cases.
|
|
|
|
### paste-nedb.html
|
|
|
|
Uses NeDB (`@seald-io/nedb`) running in-memory. Persists NDJSON snapshots to `/data/` in the selected folder for fast reload. Useful if you need MongoDB-style query operators (`$gt`, `$in`, `$regex`).
|
|
|
|
### paste-sql-js.html
|
|
|
|
Uses sql.js, which is SQLite compiled to pure JavaScript (asm.js, not WebAssembly). The full SQLite database is exported as a binary file to `/data/store.sqlite` in the selected folder. You can open that file with any SQLite tool. Larger bundle but works from `file://` with no special setup.
|
|
|
|
### paste-sqlite.html
|
|
|
|
Uses the official `@sqlite.org/sqlite-wasm` package. Requires an HTTP server because the browser must `fetch()` the `.wasm` binary at runtime. May also need COOP/COEP headers for OPFS persistence. Run `bun run serve.ts` to test this variant.
|
|
|
|
### paste-nostr.html
|
|
|
|
Uses IndexedDB for local cache (same as the indexeddb variant) plus **Nostr relay sync** for cross-device reach. Has both a folder picker and a room key input. Use either or both:
|
|
|
|
- **Folder only** — local multi-browser sync (works offline)
|
|
- **Room only** — cross-device sync via Nostr relays (no folder needed)
|
|
- **Both** — folder for local speed + Nostr for internet reach
|
|
|
|
WebSocket connections to public Nostr relays work from `file://` origins, so no server is needed.
|
|
|
|
## How to test
|
|
|
|
### Quick (three variants)
|
|
|
|
Double-click or drag any of these into Chrome:
|
|
|
|
```
|
|
dist/paste-indexeddb.html
|
|
dist/paste-nedb.html
|
|
dist/paste-sql-js.html
|
|
dist/paste-nostr.html
|
|
```
|
|
|
|
They work directly from `file://`.
|
|
|
|
### SQLite WASM variant (needs HTTP)
|
|
|
|
```bash
|
|
bun run serve.ts
|
|
```
|
|
|
|
Then open `http://localhost:4040/paste-sqlite.html`.
|
|
|
|
### Multi-browser sync test
|
|
|
|
1. Open `paste-indexeddb.html` in Chrome
|
|
2. Click "Select sync folder" and pick an empty folder
|
|
3. Type something
|
|
4. Open the same `paste-indexeddb.html` in a second Chrome window
|
|
5. Click "Select sync folder" and pick the **same folder**
|
|
6. Wait a few seconds -- the text should appear in the second window
|
|
7. Edit in either window -- changes propagate both ways
|
|
|
|
## Building
|
|
|
|
Requires [Bun](https://bun.sh/) 1.3.10+.
|
|
|
|
```bash
|
|
bun run build.ts
|
|
```
|
|
|
|
This produces five single-file HTMLs in `dist/`. The build script:
|
|
1. Runs `Bun.build()` for each variant (bundles TypeScript, minifies)
|
|
2. Inlines all JS and CSS chunks into the HTML
|
|
3. Copies `sqlite3.wasm` to `dist/` for the WASM variant
|
|
|
|
## Project structure
|
|
|
|
```
|
|
paste/
|
|
indexeddb/ source for IndexedDB paste app
|
|
app.ts
|
|
index.html
|
|
nedb/ source for NeDB paste app
|
|
app.ts
|
|
index.html
|
|
sql-js/ source for sql.js paste app
|
|
app.ts
|
|
index.html
|
|
sqlite/ source for SQLite WASM paste app
|
|
app.ts
|
|
index.html
|
|
nostr/ source for Nostr + Folder paste app
|
|
app.ts
|
|
index.html
|
|
shared.ts shared UI logic (all variants import this)
|
|
styles.css shared styles
|
|
build.ts bun build script
|
|
serve.ts dev server for SQLite WASM variant
|
|
dist/ built output (single HTML files)
|
|
```
|
|
|
|
## Folder layout on disk
|
|
|
|
After selecting a sync folder, you'll see:
|
|
|
|
```
|
|
your-folder/
|
|
events/
|
|
1710000000000_a1b2c3d4e5f6.json
|
|
1710000001000_f6e5d4c3b2a1.json
|
|
data/ (nedb and sql-js only)
|
|
kv.db (nedb: NDJSON)
|
|
docs.db (nedb: NDJSON)
|
|
store.sqlite (sql-js: SQLite binary)
|
|
```
|
|
|
|
The `events/` folder is shared by all variants. If you point two different variant HTMLs at the same folder, they will sync with each other (the event format is identical across all five).
|