@aqwas/core

Vanilla TypeScript client for Aqwas — a distributed, real-time state service. Multiple clients, instant local writes, automatic sync.

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

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: "wss://aqwas-server.fly.dev/ws",
  storeId: "my-app/room-1",
});

await client.connect();

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

// Read
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 to", value);
});

unsub();
client.disconnect();

How it works

Last-write-wins. Each set(key, value) sends a JSON message to the server, which broadcasts it to every other connected client. The most recent write for a key wins. This is the right model for 99% of real-time state: game state, presence, AI agent memory, dashboards.

Optimistic updates. set() applies to the local store immediately — the UI never waits for a server round-trip. Other clients receive the update asynchronously via broadcast.

Offline buffering. Writes made while disconnected are queued as plain messages. On reconnect they are flushed to the server in order — no data is lost.

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

API

new AqwasClient(config)

const client = new AqwasClient({
  url: "wss://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 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 locally immediately; syncs to the server asynchronously. If the client is offline, the write 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));
unsub(); // stop listening

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("sync", (state) => console.log("full state", state));
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