@aqwas/core

Vanilla TypeScript client for Aqwas — a distributed, real-time state service built on CRDT. Multiple clients, zero conflicts, offline-first.

Works in Node.js, browsers, Deno, and Bun.

Install

npm install @aqwas/core
# or
pnpm add @aqwas/core
# or
bun add @aqwas/core

Deno (JSR)

import { AqwasClient } from "jsr:@aqwas/core";

Quick Start

import { AqwasClient } from "@aqwas/core";

const client = new AqwasClient({
  url: "ws://localhost:3000/ws",
  storeId: "my-app/room-1",
});

await client.connect();

// Write state — applies locally instantly, syncs to server async
client.set("score", 100);
client.set("player", { name: "Alice", level: 5 });

// Read state
console.log(client.get("score")); // 100
console.log(client.getAll()); // { score: 100, player: { ... } }

// Subscribe to a specific key
const unsub = client.subscribe("score", (value, oldValue) => {
  console.log(`score: ${oldValue} → ${value}`);
});

// Listen to any change (local or from another client)
client.on("change", (key, value, oldValue) => {
  console.log(key, "changed");
});

unsub();
client.disconnect();

How It Works

Optimistic updates. set() writes to the local Yjs CRDT document immediately — the UI never waits for a server round-trip. The binary update is sent to the server in the background.

Automatic conflict resolution. Concurrent writes from multiple clients are merged by the CRDT. There are no "resolve conflict" dialogs and no last-write-wins data loss. All clients converge to the same state.

Offline buffering. Writes made while disconnected are queued. On reconnect, all pending updates are merged into a single CRDT update and flushed — no data is lost.

Automatic reconnect. Exponential backoff with configurable limits. connect() resolves again after each successful reconnect.

API

new AqwasClient(config)

const client = new AqwasClient({
  url: "ws://your-server/ws",
  storeId: "app/room-42",
  token: "aq_live_...", // optional auth token
  persist: true, // persist store to DB (server default if omitted)
  ttl: "24h", // store TTL: "30m", "7d", etc.
  exclude: ["localDraft"], // keys that stay local, never sent to server
  reconnect: {
    initialDelayMs: 1000, // default
    maxDelayMs: 30000, // default
    multiplier: 2, // default
    maxAttempts: Infinity, // default
  },
});

Option	Type	Description
url	string	WebSocket URL of the Aqwas server
storeId	string	Unique store identifier, e.g. "game/lobby-42"
token	string	Auth token for permission-scoped access
persist	boolean	Whether the server persists this store to the database
ttl	string	How long the server keeps the store alive after last connection
exclude	string[]	Keys that are written locally but never sent to the server
reconnect	ReconnectConfig	Backoff settings for automatic reconnection

---

client.connect(): Promise<void>

Opens the WebSocket and resolves once the initial state has been received from the server. Always await this before reading or writing if you need the latest server state.

await client.connect();
// state is now in sync

client.disconnect(): void

Closes the connection permanently. No further reconnects.

---

client.set(key, value): void

Writes value for key. Applies to the local CRDT immediately; syncs to the server asynchronously. If the client is offline, the update is buffered until reconnect.

client.set("position", { x: 10, y: 20 });
client.set("count", client.get<number>("count")! + 1);

client.get<T>(key): T | undefined

Returns the current local value for key.

const pos = client.get<{ x: number; y: number }>("position");

client.delete(key): void

Removes key from the store locally and on the server.

client.getAll(): Record<string, unknown>

Returns a shallow snapshot of the entire store as a plain object.

---

client.subscribe(key, callback): () => void

Fires callback(value, oldValue) whenever key changes — from local writes or incoming server updates. Returns an unsubscribe function.

const unsub = client.subscribe("cursor", (pos) => renderCursor(pos));

// stop listening
unsub();

client.on(event, callback): () => void

Listens for lifecycle events. Returns an unsubscribe function.

client.on("connect", () => console.log("synced"));
client.on("disconnect", () => showOfflineBanner());
client.on("change", (key, value, oldValue) => console.log(key, value));
client.on("error", (code, message) => console.error(code, message));
client.on("destroyed", (reason) => console.warn("store destroyed:", reason));

Event	Callback	Fires when
connect	() => void	Connected and initial sync complete
disconnect	() => void	Connection lost (reconnect may follow)
sync	(state: Record<string, unknown>) => void	Full state snapshot received
change	(key, value, oldValue) => void	Any key changed, local or remote
error	(code: string, message: string) => void	Server sent an error
destroyed	(reason: string) => void	Store was destroyed by the server

client.state: ConnectionState

Read-only. One of:

"disconnected" → "connecting" → "joining" → "connected"
                                                  ↓
                                           "reconnecting"
                                                  ↓
                                            "destroyed"

TypeScript

All types are included. No @types/ package needed.

import type {
  AqwasClientConfig,
  ClientEvent,
  ConnectionState,
  ReconnectConfig,
} from "@aqwas/core";

License

MIT