55cddf751b
Offline-first key-value store with atom interface (swap!, deref, add-watch) that syncs to a SQLite-backed server over Transit. Server (CLJ): - SQLite storage with Nippy serialization preserving all Clojure types - GET /sync?group=G&since=T pull endpoint with prefix-based groups - POST /sync push endpoint with per-document version checking - Conflict detection (stale write rejection) - Token-based auth with per-user group access - CORS support, soft deletes, purge compaction Client (CLJS): - IndexedDB wrapper with Transit serialization - SyncedAtom implementing IAtom (IDeref, ISwap, IReset, IWatchable) - Write-through to IndexedDB on every swap! - Background sync loop (pull + push) with configurable interval - Online/offline detection with reconnect sync - Conflict resolution (accept server value) - ready? channel for initial load - Custom cache atom support (Reagent ratom compatible) 25 tests, 77 assertions across db, transit, server, and auth.
103 lines
3.1 KiB
Markdown
103 lines
3.1 KiB
Markdown
# Pocketbook
|
|
|
|
A Clojure-native synced atom. Offline-first key-value store with an `atom` interface that syncs to a SQLite-backed server over Transit.
|
|
|
|
```clojure
|
|
(def conn (<! (pocketbook/open "my-app")))
|
|
(def todos (pocketbook/synced-atom conn "todo" {:server "http://localhost:8090/sync"}))
|
|
|
|
(swap! todos assoc "todo:1" {:text "Buy milk" :tags #{:groceries}})
|
|
@todos ;=> {"todo:1" {:text "Buy milk" :tags #{:groceries}}}
|
|
```
|
|
|
|
## What it does
|
|
|
|
- **Preserves Clojure types**: keywords, sets, UUIDs, instants — no lossy JSON
|
|
- **Works offline**: reads/writes hit IndexedDB immediately, syncs when online
|
|
- **Atom interface**: `swap!`, `deref`, `add-watch` — works with Reagent, Rum, or raw CLJS
|
|
- **~500 lines**: client (~300) + server (~200), no opaque dependencies
|
|
|
|
## Quick start
|
|
|
|
### Server
|
|
|
|
```bash
|
|
clj -M:server
|
|
# or: clj -M:server 8090 my-data.db
|
|
```
|
|
|
|
Starts on `http://localhost:8090` with a SQLite file at `pocketbook.db`.
|
|
|
|
### Client (CLJS)
|
|
|
|
```clojure
|
|
(ns my-app.core
|
|
(:require [pocketbook.core :as pb]
|
|
[cljs.core.async :refer [go <!]]))
|
|
|
|
(go
|
|
(let [conn (<! (pb/open "my-app"))
|
|
todos (pb/synced-atom conn "todo"
|
|
{:server "http://localhost:8090/sync"})]
|
|
(<! (pb/ready? todos))
|
|
(swap! todos assoc "todo:1" {:text "Buy milk" :done false})
|
|
(add-watch todos :log (fn [_ _ _ new] (println (count new) "todos")))))
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser Server
|
|
┌─────────────┐ ┌──────────────┐
|
|
│ SyncedAtom │ ── Transit/HTTP ──▶ │ http-kit │
|
|
│ ↕ atom │ │ ↕ Transit │
|
|
│ ↕ IndexedDB│ ◀── Transit/HTTP ── │ ↕ Nippy │
|
|
│ (Transit) │ │ ↕ SQLite │
|
|
└─────────────┘ └──────────────┘
|
|
```
|
|
|
|
## Sync protocol
|
|
|
|
- **Pull**: `GET /sync?group=todo&since=<epoch-ms>` — returns changed docs
|
|
- **Push**: `POST /sync` — sends local changes with version numbers
|
|
- **Conflicts**: server rejects stale writes, client accepts server value
|
|
|
|
## Auth
|
|
|
|
Optional token-based auth:
|
|
|
|
```clojure
|
|
(server/start! {:port 8090
|
|
:users {"alice" {:token "abc123" :groups #{"todo" "settings"}}
|
|
"bob" {:token "def456" :groups #{"todo"}}}})
|
|
```
|
|
|
|
Client passes token:
|
|
|
|
```clojure
|
|
(pb/synced-atom conn "todo" {:server "http://localhost:8090/sync"
|
|
:token "abc123"})
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
| Layer | Library | Purpose |
|
|
|--------|---------|---------|
|
|
| Server | next.jdbc + sqlite-jdbc | SQLite storage |
|
|
| Server | nippy | Binary serialization |
|
|
| Server | transit-clj | Wire format |
|
|
| Server | http-kit | HTTP server |
|
|
| Client | transit-cljs | Serialization (IDB + wire) |
|
|
| Client | core.async | Sync coordination |
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
# All server tests
|
|
clj -M:dev -e '(require (quote pocketbook.db-test) (quote pocketbook.transit-test) (quote pocketbook.server-test) (quote pocketbook.auth-test)) (clojure.test/run-all-tests #"pocketbook\..*")'
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|