Files

Florian Schroedl 55cddf751b 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.

2026-04-04 16:33:14 +02:00

3.1 KiB

Raw Blame History

Pocketbook

A Clojure-native synced atom. Offline-first key-value store with an atom interface that syncs to a SQLite-backed server over Transit.

(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

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)

(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:

(server/start! {:port 8090
                :users {"alice" {:token "abc123" :groups #{"todo" "settings"}}
                        "bob"   {:token "def456" :groups #{"todo"}}}})

Client passes token:

(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

# 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

3.1 KiB Raw Blame History