feat: implement Pocketbook — a Clojure-native synced atom
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.
This commit is contained in:
102
README.md
Normal file
102
README.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user