@absolutejs/sync 0.0.1

package/README.md

@@ -0,0 +1,102 @@
+# @absolutejs/sync
+
+Two small, composable primitives for live data in [Elysia](https://elysiajs.com)
+and the AbsoluteJS ecosystem:
+
+- **`createReactiveHub` + `sync` plugin** — push-on-change over SSE so clients stop
+  polling. A widget subscribes to the topics its data depends on; a mutation
+  publishes those topics; subscribers refetch (or read the pushed payload) the
+  instant data changes.
+- **`createWriteBehindCache`** — an in-memory hot cache with write-behind
+  persistence, so a latency-sensitive hot path doesn't pay a round-trip to a remote
+  store on every read/write.
+
+It is **not a sync engine.** Convex, ElectricSQL, and Zero are whole backends —
+read-set tracking, OCC/MVCC, a transaction log, client SQLite replicas. This package
+does **not** rebuild any of that. It's a thin reactive layer over the store and
+transport you already have: pair it with **Drizzle _or_ Prisma** (or any store) and
+your existing SSE/WebSocket. Dependencies are explicit (you name topics), not
+auto-tracked from query read sets. If you want a full local-first sync engine, reach
+for one of the above; if you just want to delete your polling loop and keep a remote
+DB off your hot path, reach for this.
+
+> Status: early (`0.0.1`). In-memory hub, write-behind cache, Elysia SSE plugin, and
+> a browser subscriber. Durable/transport adapters land in a companion
+> `-adapters` package as the API settles.
+
+## Install
+
+```bash
+bun add @absolutejs/sync
+```
+
+`elysia` is an optional peer (only needed for the `sync` plugin).
+
+## Reactive push — kill the polling loop
+
+```ts
+// server
+import { Elysia } from 'elysia';
+import { createReactiveHub, sync } from '@absolutejs/sync';
+
+const hub = createReactiveHub();
+
+new Elysia()
+	.use(sync({ hub })) // serves SSE at GET /sync?topics=a,b,c
+	.post('/orders', async ({ body }) => {
+		const order = await db.orders.insert(body); // your Drizzle/Prisma write
+		hub.publish('orders'); // notify everyone watching "orders"
+		hub.publish(`orders:${order.id}`); // …and this one specifically
+		return order;
+	})
+	.listen(3000);
+```
+
+```ts
+// browser
+import { createSyncSubscriber } from '@absolutejs/sync/client';
+
+const sub = createSyncSubscriber({
+	topics: ['orders', 'orders:*'], // trailing * matches by prefix
+	onEvent: (event) => {
+		// data changed — refetch instead of polling on a timer
+		if (event.topic.startsWith('orders')) refetchOrders();
+	}
+});
+// sub.close() when the view unmounts
+```
+
+## Write-behind cache — keep a remote store off your hot path
+
+```ts
+import { createWriteBehindCache } from '@absolutejs/sync';
+
+const sessions = createWriteBehindCache({
+	load: (id) => db.sessions.get(id), // read-through on a miss
+	persist: (id, value) => db.sessions.set(id, value), // coalesced background write
+	remove: (id) => db.sessions.delete(id),
+	debounceMs: 250,
+	evict: (value) => value.status === 'closed' // drop terminal entries
+});
+
+sessions.set('s1', next); // synchronous; persists ~250ms later
+const current = await sessions.get('s1'); // from memory
+await sessions.flush(); // on shutdown
+```
+
+This is what `@absolutejs/voice` uses to keep its per-audio-frame session state in
+memory while the Drizzle/Postgres store stays the durable source of truth — without
+it, ~3 store round-trips every 20ms ran the voice pipeline far slower than real time.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `createReactiveHub()` | In-memory topic pub/sub (`publish`, `subscribe`, `subscriberCount`). |
+| `sync({ hub, path?, resolveTopics?, heartbeatMs? })` | Elysia plugin: SSE stream of hub events. |
+| `createSyncSubscriber({ topics, onEvent, url? })` | Browser SSE client (from `@absolutejs/sync/client`). |
+| `createWriteBehindCache({ load, persist, remove?, debounceMs?, evict?, onPersistError? })` | In-memory cache + write-behind persistence. |
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,31 @@
+import type { ReactiveEvent } from '../reactiveHub';
+export type { ReactiveEvent } from '../reactiveHub';
+export type SyncSubscriberOptions = {
+    /** Topics to subscribe to. A trailing `*` matches by prefix server-side. */
+    topics: string[];
+    /** Called for every reactive event pushed from the server. */
+    onEvent: (event: ReactiveEvent) => void;
+    /** SSE endpoint mounted by the {@link sync} plugin. Defaults to `/sync`. */
+    url?: string;
+    onOpen?: () => void;
+    onError?: (event: Event) => void;
+    /** Send cookies with the SSE request (cross-origin auth). */
+    withCredentials?: boolean;
+    /**
+     * EventSource implementation to use. Defaults to the global one; pass a polyfill
+     * for non-browser runtimes.
+     */
+    eventSourceImpl?: typeof EventSource;
+};
+export type SyncSubscriber = {
+    close: () => void;
+    /** The underlying EventSource, for advanced listeners. */
+    source: EventSource;
+};
+/**
+ * Subscribe a browser to the server's {@link ReactiveHub} over SSE. `onEvent` fires
+ * whenever a subscribed topic is published — the cue to refetch (or read the pushed
+ * payload) instead of polling. EventSource reconnects automatically on transient
+ * network drops.
+ */
+export declare const createSyncSubscriber: ({ topics, onEvent, url, onOpen, onError, withCredentials, eventSourceImpl }: SyncSubscriberOptions) => SyncSubscriber;

package/dist/client/index.js

@@ -0,0 +1,41 @@
+// src/client/index.ts
+var createSyncSubscriber = ({
+  topics,
+  onEvent,
+  url = "/sync",
+  onOpen,
+  onError,
+  withCredentials,
+  eventSourceImpl
+}) => {
+  const Impl = eventSourceImpl ?? globalThis.EventSource;
+  if (!Impl) {
+    throw new Error("createSyncSubscriber requires EventSource. Run in a browser or pass eventSourceImpl.");
+  }
+  const params = new URLSearchParams({ topics: topics.join(",") });
+  const separator = url.includes("?") ? "&" : "?";
+  const source = new Impl(`${url}${separator}${params.toString()}`, {
+    withCredentials: withCredentials ?? false
+  });
+  source.onmessage = (event) => {
+    try {
+      onEvent(JSON.parse(event.data));
+    } catch {}
+  };
+  if (onOpen) {
+    source.onopen = () => onOpen();
+  }
+  if (onError) {
+    source.onerror = (event) => onError(event);
+  }
+  return {
+    close: () => source.close(),
+    source
+  };
+};
+export {
+  createSyncSubscriber
+};
+
+//# debugId=10D2496AED02ED9364756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/client/index.ts"],
+  "sourcesContent": [
+    "import type { ReactiveEvent } from '../reactiveHub';\n\nexport type { ReactiveEvent } from '../reactiveHub';\n\nexport type SyncSubscriberOptions = {\n\t/** Topics to subscribe to. A trailing `*` matches by prefix server-side. */\n\ttopics: string[];\n\t/** Called for every reactive event pushed from the server. */\n\tonEvent: (event: ReactiveEvent) => void;\n\t/** SSE endpoint mounted by the {@link sync} plugin. Defaults to `/sync`. */\n\turl?: string;\n\tonOpen?: () => void;\n\tonError?: (event: Event) => void;\n\t/** Send cookies with the SSE request (cross-origin auth). */\n\twithCredentials?: boolean;\n\t/**\n\t * EventSource implementation to use. Defaults to the global one; pass a polyfill\n\t * for non-browser runtimes.\n\t */\n\teventSourceImpl?: typeof EventSource;\n};\n\nexport type SyncSubscriber = {\n\tclose: () => void;\n\t/** The underlying EventSource, for advanced listeners. */\n\tsource: EventSource;\n};\n\n/**\n * Subscribe a browser to the server's {@link ReactiveHub} over SSE. `onEvent` fires\n * whenever a subscribed topic is published — the cue to refetch (or read the pushed\n * payload) instead of polling. EventSource reconnects automatically on transient\n * network drops.\n */\nexport const createSyncSubscriber = ({\n\ttopics,\n\tonEvent,\n\turl = '/sync',\n\tonOpen,\n\tonError,\n\twithCredentials,\n\teventSourceImpl\n}: SyncSubscriberOptions): SyncSubscriber => {\n\tconst Impl = eventSourceImpl ?? globalThis.EventSource;\n\tif (!Impl) {\n\t\tthrow new Error(\n\t\t\t'createSyncSubscriber requires EventSource. Run in a browser or pass eventSourceImpl.'\n\t\t);\n\t}\n\n\tconst params = new URLSearchParams({ topics: topics.join(',') });\n\tconst separator = url.includes('?') ? '&' : '?';\n\tconst source = new Impl(`${url}${separator}${params.toString()}`, {\n\t\twithCredentials: withCredentials ?? false\n\t});\n\n\tsource.onmessage = (event) => {\n\t\ttry {\n\t\t\tonEvent(JSON.parse(event.data) as ReactiveEvent);\n\t\t} catch {\n\t\t\t// ignore heartbeats / non-JSON frames\n\t\t}\n\t};\n\tif (onOpen) {\n\t\tsource.onopen = () => onOpen();\n\t}\n\tif (onError) {\n\t\tsource.onerror = (event) => onError(event);\n\t}\n\n\treturn {\n\t\tclose: () => source.close(),\n\t\tsource\n\t};\n};\n"
+  ],
+  "mappings": ";AAkCO,IAAM,uBAAuB;AAAA,EACnC;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,MAC4C;AAAA,EAC5C,MAAM,OAAO,mBAAmB,WAAW;AAAA,EAC3C,IAAI,CAAC,MAAM;AAAA,IACV,MAAM,IAAI,MACT,sFACD;AAAA,EACD;AAAA,EAEA,MAAM,SAAS,IAAI,gBAAgB,EAAE,QAAQ,OAAO,KAAK,GAAG,EAAE,CAAC;AAAA,EAC/D,MAAM,YAAY,IAAI,SAAS,GAAG,IAAI,MAAM;AAAA,EAC5C,MAAM,SAAS,IAAI,KAAK,GAAG,MAAM,YAAY,OAAO,SAAS,KAAK;AAAA,IACjE,iBAAiB,mBAAmB;AAAA,EACrC,CAAC;AAAA,EAED,OAAO,YAAY,CAAC,UAAU;AAAA,IAC7B,IAAI;AAAA,MACH,QAAQ,KAAK,MAAM,MAAM,IAAI,CAAkB;AAAA,MAC9C,MAAM;AAAA;AAAA,EAIT,IAAI,QAAQ;AAAA,IACX,OAAO,SAAS,MAAM,OAAO;AAAA,EAC9B;AAAA,EACA,IAAI,SAAS;AAAA,IACZ,OAAO,UAAU,CAAC,UAAU,QAAQ,KAAK;AAAA,EAC1C;AAAA,EAEA,OAAO;AAAA,IACN,OAAO,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACD;AAAA;",
+  "debugId": "10D2496AED02ED9364756E2164756E21",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createWriteBehindCache } from './writeBehindCache';
+export type { WriteBehindCache, WriteBehindCacheOptions } from './writeBehindCache';
+export { createReactiveHub } from './reactiveHub';
+export type { ReactiveEvent, ReactiveHub, ReactiveListener } from './reactiveHub';
+export { sync } from './plugin';
+export type { SyncPluginOptions, SyncRequestContext } from './plugin';

package/dist/index.js

@@ -0,0 +1,176 @@
+// @bun
+// src/writeBehindCache.ts
+var createWriteBehindCache = (options) => {
+  const debounceMs = options.debounceMs ?? 250;
+  const cache = new Map;
+  const timers = new Map;
+  const persist = async (key) => {
+    timers.delete(key);
+    const value = cache.get(key);
+    if (value === undefined) {
+      return;
+    }
+    try {
+      await options.persist(key, value);
+      if (options.evict?.(value, key)) {
+        cache.delete(key);
+      }
+    } catch (error) {
+      options.onPersistError?.(error, key);
+    }
+  };
+  const schedulePersist = (key) => {
+    if (timers.has(key)) {
+      return;
+    }
+    timers.set(key, setTimeout(() => {
+      persist(key);
+    }, debounceMs));
+  };
+  return {
+    get: async (key) => {
+      const cached = cache.get(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const loaded = await options.load(key);
+      if (loaded !== undefined) {
+        cache.set(key, loaded);
+      }
+      return loaded;
+    },
+    peek: (key) => cache.get(key),
+    has: (key) => cache.has(key),
+    set: (key, value) => {
+      cache.set(key, value);
+      schedulePersist(key);
+    },
+    delete: async (key) => {
+      const timer = timers.get(key);
+      if (timer) {
+        clearTimeout(timer);
+        timers.delete(key);
+      }
+      cache.delete(key);
+      await options.remove?.(key);
+    },
+    keys: () => cache.keys(),
+    values: () => cache.values(),
+    size: () => cache.size,
+    flush: async () => {
+      for (const timer of timers.values()) {
+        clearTimeout(timer);
+      }
+      timers.clear();
+      await Promise.all([...cache.keys()].map((key) => persist(key)));
+    }
+  };
+};
+// src/reactiveHub.ts
+var createReactiveHub = () => {
+  const subscriptions = new Set;
+  const matches = (subscription, topic) => {
+    if (subscription.exact.has(topic)) {
+      return true;
+    }
+    return subscription.prefixes.some((prefix) => topic.startsWith(prefix));
+  };
+  return {
+    publish: (topic, payload) => {
+      const event = { topic, at: Date.now(), payload };
+      for (const subscription of subscriptions) {
+        if (matches(subscription, topic)) {
+          subscription.listener(event);
+        }
+      }
+    },
+    subscribe: (topics, listener) => {
+      const exact = new Set;
+      const prefixes = [];
+      for (const topic of topics) {
+        if (topic.endsWith("*")) {
+          prefixes.push(topic.slice(0, -1));
+        } else {
+          exact.add(topic);
+        }
+      }
+      const subscription = { exact, prefixes, listener };
+      subscriptions.add(subscription);
+      return () => {
+        subscriptions.delete(subscription);
+      };
+    },
+    subscriberCount: (topic) => {
+      if (topic === undefined) {
+        return subscriptions.size;
+      }
+      let count = 0;
+      for (const subscription of subscriptions) {
+        if (matches(subscription, topic)) {
+          count += 1;
+        }
+      }
+      return count;
+    }
+  };
+};
+// src/plugin.ts
+import { Elysia } from "elysia";
+var defaultResolveTopics = (context) => (context.query.topics ?? "").split(",").map((topic) => topic.trim()).filter(Boolean);
+var sync = ({
+  hub,
+  path = "/sync",
+  resolveTopics = defaultResolveTopics,
+  heartbeatMs = 25000
+}) => new Elysia({ name: "@absolutejs/sync" }).get(path, (context) => {
+  const topics = resolveTopics({
+    query: context.query,
+    request: context.request
+  });
+  const encoder = new TextEncoder;
+  const stream = new ReadableStream({
+    start(controller) {
+      const write = (chunk) => {
+        try {
+          controller.enqueue(encoder.encode(chunk));
+        } catch {}
+      };
+      const send = (event) => {
+        write(`data: ${JSON.stringify(event)}
+
+`);
+      };
+      send({
+        topic: "@absolutejs/sync:open",
+        at: Date.now(),
+        payload: { topics }
+      });
+      const unsubscribe = topics.length > 0 ? hub.subscribe(topics, send) : () => {};
+      const heartbeat = setInterval(() => write(`: ping
+
+`), heartbeatMs);
+      context.request.signal.addEventListener("abort", () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+        try {
+          controller.close();
+        } catch {}
+      }, { once: true });
+    }
+  });
+  return new Response(stream, {
+    headers: {
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "content-type": "text/event-stream"
+    }
+  });
+});
+export {
+  sync,
+  createWriteBehindCache,
+  createReactiveHub
+};
+
+//# debugId=2C5B85D345323A2D64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/writeBehindCache.ts", "../src/reactiveHub.ts", "../src/plugin.ts"],
+  "sourcesContent": [
+    "export type WriteBehindCacheOptions<K, V> = {\n\t/**\n\t * Read a value from the durable store on a cache miss. Called at most once per\n\t * key until the entry is evicted.\n\t */\n\tload: (key: K) => Promise<V | undefined> | V | undefined;\n\t/** Persist a value to the durable store. Runs in the background (write-behind). */\n\tpersist: (key: K, value: V) => Promise<void> | void;\n\t/** Remove a value from the durable store. */\n\tremove?: (key: K) => Promise<void> | void;\n\t/**\n\t * Coalesce writes: each key persists at most once per window. A burst of\n\t * `set`s collapses into a single durable write. Defaults to 250ms.\n\t */\n\tdebounceMs?: number;\n\t/**\n\t * After a key persists, return true to drop it from the in-memory cache so the\n\t * cache stays bounded to \"hot\" entries (e.g. evict terminal sessions). The next\n\t * `get` reloads it via `load`. Defaults to never evicting.\n\t */\n\tevict?: (value: V, key: K) => boolean;\n\t/**\n\t * Called when a background persist throws. The cache stays authoritative and the\n\t * key re-persists on its next `set`, so a transient durable-store blip does not\n\t * drop live state. Defaults to a no-op.\n\t */\n\tonPersistError?: (error: unknown, key: K) => void;\n};\n\nexport type WriteBehindCache<K, V> = {\n\t/** Cached value, or load-through from the durable store on a miss. */\n\tget: (key: K) => Promise<V | undefined>;\n\t/** Cached value only — synchronous, never touches the durable store. */\n\tpeek: (key: K) => V | undefined;\n\thas: (key: K) => boolean;\n\t/** Write to memory immediately and schedule a coalesced durable persist. */\n\tset: (key: K, value: V) => void;\n\t/** Drop from cache and the durable store. */\n\tdelete: (key: K) => Promise<void>;\n\tkeys: () => IterableIterator<K>;\n\tvalues: () => IterableIterator<V>;\n\tsize: () => number;\n\t/** Persist every pending key to the durable store now. Call on shutdown. */\n\tflush: () => Promise<void>;\n};\n\n/**\n * Wrap a durable store (Postgres, SQLite, Drizzle, Prisma, file, S3, an HTTP API …)\n * with an in-memory hot cache and write-behind persistence.\n *\n * Reads are served from memory; writes hit memory synchronously and are flushed to\n * the durable store in coalesced background batches. The durable store stays the\n * source of truth for history and cross-instance reads, while a latency-sensitive\n * hot path (a per-frame voice session, presence, cursors, game state) stays fast.\n *\n * This is the \"fast authoritative local state, durable persistence synced behind it\"\n * split a sync engine like Convex makes — without adopting a whole sync-engine\n * backend. Bring your own store via `load`/`persist`/`remove`.\n */\nexport const createWriteBehindCache = <K, V>(\n\toptions: WriteBehindCacheOptions<K, V>\n): WriteBehindCache<K, V> => {\n\tconst debounceMs = options.debounceMs ?? 250;\n\tconst cache = new Map<K, V>();\n\tconst timers = new Map<K, ReturnType<typeof setTimeout>>();\n\n\tconst persist = async (key: K) => {\n\t\ttimers.delete(key);\n\t\tconst value = cache.get(key);\n\t\tif (value === undefined) {\n\t\t\treturn;\n\t\t}\n\t\ttry {\n\t\t\tawait options.persist(key, value);\n\t\t\tif (options.evict?.(value, key)) {\n\t\t\t\tcache.delete(key);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\toptions.onPersistError?.(error, key);\n\t\t}\n\t};\n\n\tconst schedulePersist = (key: K) => {\n\t\tif (timers.has(key)) {\n\t\t\treturn;\n\t\t}\n\t\ttimers.set(\n\t\t\tkey,\n\t\t\tsetTimeout(() => {\n\t\t\t\tvoid persist(key);\n\t\t\t}, debounceMs)\n\t\t);\n\t};\n\n\treturn {\n\t\tget: async (key) => {\n\t\t\tconst cached = cache.get(key);\n\t\t\tif (cached !== undefined) {\n\t\t\t\treturn cached;\n\t\t\t}\n\t\t\tconst loaded = await options.load(key);\n\t\t\tif (loaded !== undefined) {\n\t\t\t\tcache.set(key, loaded);\n\t\t\t}\n\t\t\treturn loaded;\n\t\t},\n\t\tpeek: (key) => cache.get(key),\n\t\thas: (key) => cache.has(key),\n\t\tset: (key, value) => {\n\t\t\tcache.set(key, value);\n\t\t\tschedulePersist(key);\n\t\t},\n\t\tdelete: async (key) => {\n\t\t\tconst timer = timers.get(key);\n\t\t\tif (timer) {\n\t\t\t\tclearTimeout(timer);\n\t\t\t\ttimers.delete(key);\n\t\t\t}\n\t\t\tcache.delete(key);\n\t\t\tawait options.remove?.(key);\n\t\t},\n\t\tkeys: () => cache.keys(),\n\t\tvalues: () => cache.values(),\n\t\tsize: () => cache.size,\n\t\tflush: async () => {\n\t\t\tfor (const timer of timers.values()) {\n\t\t\t\tclearTimeout(timer);\n\t\t\t}\n\t\t\ttimers.clear();\n\t\t\tawait Promise.all([...cache.keys()].map((key) => persist(key)));\n\t\t}\n\t};\n};\n",
+    "export type ReactiveEvent<TPayload = unknown> = {\n\ttopic: string;\n\tat: number;\n\tpayload?: TPayload;\n};\n\nexport type ReactiveListener<TPayload = unknown> = (\n\tevent: ReactiveEvent<TPayload>\n) => void;\n\nexport type ReactiveHub = {\n\t/**\n\t * Notify every subscriber of `topic` (and any prefix-wildcard subscriber that\n\t * matches it). Call this from a mutation after the durable write commits.\n\t */\n\tpublish: (topic: string, payload?: unknown) => void;\n\t/**\n\t * Listen on one or more topics. A topic ending in `*` matches every topic that\n\t * starts with the prefix before it (e.g. `voice:session:*`). Returns an\n\t * unsubscribe function.\n\t */\n\tsubscribe: (topics: string[], listener: ReactiveListener) => () => void;\n\t/** Number of active subscribers, optionally for a single exact topic. */\n\tsubscriberCount: (topic?: string) => number;\n};\n\ntype Subscription = {\n\texact: Set<string>;\n\tprefixes: string[];\n\tlistener: ReactiveListener;\n};\n\n/**\n * An in-memory topic pub/sub for reactive, push-on-change updates.\n *\n * The pattern that replaces polling: a query/widget subscribes to the topics its\n * data depends on; a mutation `publish`es those topics after it writes; subscribers\n * are notified immediately and refetch (or receive the pushed payload) — instead of\n * every client hammering the server on a timer.\n *\n * Dependencies are explicit (you name the topics) rather than auto-tracked from a\n * query's read set — deliberately small, with no sandbox or query interception.\n * Pair it with the {@link sync} Elysia plugin to stream events to browsers over SSE.\n */\nexport const createReactiveHub = (): ReactiveHub => {\n\tconst subscriptions = new Set<Subscription>();\n\n\tconst matches = (subscription: Subscription, topic: string) => {\n\t\tif (subscription.exact.has(topic)) {\n\t\t\treturn true;\n\t\t}\n\t\treturn subscription.prefixes.some((prefix) => topic.startsWith(prefix));\n\t};\n\n\treturn {\n\t\tpublish: (topic, payload) => {\n\t\t\tconst event: ReactiveEvent = { topic, at: Date.now(), payload };\n\t\t\tfor (const subscription of subscriptions) {\n\t\t\t\tif (matches(subscription, topic)) {\n\t\t\t\t\tsubscription.listener(event);\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\tsubscribe: (topics, listener) => {\n\t\t\tconst exact = new Set<string>();\n\t\t\tconst prefixes: string[] = [];\n\t\t\tfor (const topic of topics) {\n\t\t\t\tif (topic.endsWith('*')) {\n\t\t\t\t\tprefixes.push(topic.slice(0, -1));\n\t\t\t\t} else {\n\t\t\t\t\texact.add(topic);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst subscription: Subscription = { exact, prefixes, listener };\n\t\t\tsubscriptions.add(subscription);\n\t\t\treturn () => {\n\t\t\t\tsubscriptions.delete(subscription);\n\t\t\t};\n\t\t},\n\t\tsubscriberCount: (topic) => {\n\t\t\tif (topic === undefined) {\n\t\t\t\treturn subscriptions.size;\n\t\t\t}\n\t\t\tlet count = 0;\n\t\t\tfor (const subscription of subscriptions) {\n\t\t\t\tif (matches(subscription, topic)) {\n\t\t\t\t\tcount += 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn count;\n\t\t}\n\t};\n};\n",
+    "import { Elysia } from 'elysia';\nimport type { ReactiveEvent, ReactiveHub } from './reactiveHub';\n\nexport type SyncRequestContext = {\n\tquery: Record<string, string | undefined>;\n\trequest: Request;\n};\n\nexport type SyncPluginOptions = {\n\thub: ReactiveHub;\n\t/** Route the SSE stream is served from. Defaults to `/sync`. */\n\tpath?: string;\n\t/**\n\t * Which topics a connection subscribes to. Defaults to a comma-separated\n\t * `?topics=a,b,c` query param. Override to derive topics from the session,\n\t * params, or auth instead of trusting the client.\n\t */\n\tresolveTopics?: (context: SyncRequestContext) => string[];\n\t/**\n\t * Server→client heartbeat comment, so idle proxies don't drop the SSE stream.\n\t * Defaults to 25000ms.\n\t */\n\theartbeatMs?: number;\n};\n\nconst defaultResolveTopics = (context: SyncRequestContext) =>\n\t(context.query.topics ?? '')\n\t\t.split(',')\n\t\t.map((topic) => topic.trim())\n\t\t.filter(Boolean);\n\n/**\n * Elysia plugin that streams {@link ReactiveHub} events to browsers over Server-Sent\n * Events. Mount it once, point {@link createSyncSubscriber} at the same path, and\n * `hub.publish(topic)` from your mutations — subscribed clients are notified the\n * moment data changes, so they can refetch (or read the pushed payload) instead of\n * polling on a timer.\n */\nexport const sync = ({\n\thub,\n\tpath = '/sync',\n\tresolveTopics = defaultResolveTopics,\n\theartbeatMs = 25_000\n}: SyncPluginOptions) =>\n\tnew Elysia({ name: '@absolutejs/sync' }).get(path, (context) => {\n\t\tconst topics = resolveTopics({\n\t\t\tquery: context.query as Record<string, string | undefined>,\n\t\t\trequest: context.request\n\t\t});\n\t\tconst encoder = new TextEncoder();\n\n\t\tconst stream = new ReadableStream<Uint8Array>({\n\t\t\tstart(controller) {\n\t\t\t\tconst write = (chunk: string) => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tcontroller.enqueue(encoder.encode(chunk));\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// controller already closed by an abort race\n\t\t\t\t\t}\n\t\t\t\t};\n\t\t\t\tconst send = (event: ReactiveEvent) => {\n\t\t\t\t\twrite(`data: ${JSON.stringify(event)}\\n\\n`);\n\t\t\t\t};\n\n\t\t\t\tsend({\n\t\t\t\t\ttopic: '@absolutejs/sync:open',\n\t\t\t\t\tat: Date.now(),\n\t\t\t\t\tpayload: { topics }\n\t\t\t\t});\n\n\t\t\t\tconst unsubscribe =\n\t\t\t\t\ttopics.length > 0 ? hub.subscribe(topics, send) : () => {};\n\t\t\t\tconst heartbeat = setInterval(\n\t\t\t\t\t() => write(': ping\\n\\n'),\n\t\t\t\t\theartbeatMs\n\t\t\t\t);\n\n\t\t\t\tcontext.request.signal.addEventListener(\n\t\t\t\t\t'abort',\n\t\t\t\t\t() => {\n\t\t\t\t\t\tclearInterval(heartbeat);\n\t\t\t\t\t\tunsubscribe();\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tcontroller.close();\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// already closed\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\t{ once: true }\n\t\t\t\t);\n\t\t\t}\n\t\t});\n\n\t\treturn new Response(stream, {\n\t\t\theaders: {\n\t\t\t\t'cache-control': 'no-cache, no-transform',\n\t\t\t\tconnection: 'keep-alive',\n\t\t\t\t'content-type': 'text/event-stream'\n\t\t\t}\n\t\t});\n\t});\n"
+  ],
+  "mappings": "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",
+  "debugId": "2C5B85D345323A2D64756E2164756E21",
+  "names": []
+}

package/dist/plugin.d.ts

@@ -0,0 +1,69 @@
+import { Elysia } from 'elysia';
+import type { ReactiveHub } from './reactiveHub';
+export type SyncRequestContext = {
+    query: Record<string, string | undefined>;
+    request: Request;
+};
+export type SyncPluginOptions = {
+    hub: ReactiveHub;
+    /** Route the SSE stream is served from. Defaults to `/sync`. */
+    path?: string;
+    /**
+     * Which topics a connection subscribes to. Defaults to a comma-separated
+     * `?topics=a,b,c` query param. Override to derive topics from the session,
+     * params, or auth instead of trusting the client.
+     */
+    resolveTopics?: (context: SyncRequestContext) => string[];
+    /**
+     * Server→client heartbeat comment, so idle proxies don't drop the SSE stream.
+     * Defaults to 25000ms.
+     */
+    heartbeatMs?: number;
+};
+/**
+ * Elysia plugin that streams {@link ReactiveHub} events to browsers over Server-Sent
+ * Events. Mount it once, point {@link createSyncSubscriber} at the same path, and
+ * `hub.publish(topic)` from your mutations — subscribed clients are notified the
+ * moment data changes, so they can refetch (or read the pushed payload) instead of
+ * polling on a timer.
+ */
+export declare const sync: ({ hub, path, resolveTopics, heartbeatMs }: SyncPluginOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/reactiveHub.d.ts

@@ -0,0 +1,34 @@
+export type ReactiveEvent<TPayload = unknown> = {
+    topic: string;
+    at: number;
+    payload?: TPayload;
+};
+export type ReactiveListener<TPayload = unknown> = (event: ReactiveEvent<TPayload>) => void;
+export type ReactiveHub = {
+    /**
+     * Notify every subscriber of `topic` (and any prefix-wildcard subscriber that
+     * matches it). Call this from a mutation after the durable write commits.
+     */
+    publish: (topic: string, payload?: unknown) => void;
+    /**
+     * Listen on one or more topics. A topic ending in `*` matches every topic that
+     * starts with the prefix before it (e.g. `voice:session:*`). Returns an
+     * unsubscribe function.
+     */
+    subscribe: (topics: string[], listener: ReactiveListener) => () => void;
+    /** Number of active subscribers, optionally for a single exact topic. */
+    subscriberCount: (topic?: string) => number;
+};
+/**
+ * An in-memory topic pub/sub for reactive, push-on-change updates.
+ *
+ * The pattern that replaces polling: a query/widget subscribes to the topics its
+ * data depends on; a mutation `publish`es those topics after it writes; subscribers
+ * are notified immediately and refetch (or receive the pushed payload) — instead of
+ * every client hammering the server on a timer.
+ *
+ * Dependencies are explicit (you name the topics) rather than auto-tracked from a
+ * query's read set — deliberately small, with no sandbox or query interception.
+ * Pair it with the {@link sync} Elysia plugin to stream events to browsers over SSE.
+ */
+export declare const createReactiveHub: () => ReactiveHub;

package/dist/writeBehindCache.d.ts

@@ -0,0 +1,58 @@
+export type WriteBehindCacheOptions<K, V> = {
+    /**
+     * Read a value from the durable store on a cache miss. Called at most once per
+     * key until the entry is evicted.
+     */
+    load: (key: K) => Promise<V | undefined> | V | undefined;
+    /** Persist a value to the durable store. Runs in the background (write-behind). */
+    persist: (key: K, value: V) => Promise<void> | void;
+    /** Remove a value from the durable store. */
+    remove?: (key: K) => Promise<void> | void;
+    /**
+     * Coalesce writes: each key persists at most once per window. A burst of
+     * `set`s collapses into a single durable write. Defaults to 250ms.
+     */
+    debounceMs?: number;
+    /**
+     * After a key persists, return true to drop it from the in-memory cache so the
+     * cache stays bounded to "hot" entries (e.g. evict terminal sessions). The next
+     * `get` reloads it via `load`. Defaults to never evicting.
+     */
+    evict?: (value: V, key: K) => boolean;
+    /**
+     * Called when a background persist throws. The cache stays authoritative and the
+     * key re-persists on its next `set`, so a transient durable-store blip does not
+     * drop live state. Defaults to a no-op.
+     */
+    onPersistError?: (error: unknown, key: K) => void;
+};
+export type WriteBehindCache<K, V> = {
+    /** Cached value, or load-through from the durable store on a miss. */
+    get: (key: K) => Promise<V | undefined>;
+    /** Cached value only — synchronous, never touches the durable store. */
+    peek: (key: K) => V | undefined;
+    has: (key: K) => boolean;
+    /** Write to memory immediately and schedule a coalesced durable persist. */
+    set: (key: K, value: V) => void;
+    /** Drop from cache and the durable store. */
+    delete: (key: K) => Promise<void>;
+    keys: () => IterableIterator<K>;
+    values: () => IterableIterator<V>;
+    size: () => number;
+    /** Persist every pending key to the durable store now. Call on shutdown. */
+    flush: () => Promise<void>;
+};
+/**
+ * Wrap a durable store (Postgres, SQLite, Drizzle, Prisma, file, S3, an HTTP API …)
+ * with an in-memory hot cache and write-behind persistence.
+ *
+ * Reads are served from memory; writes hit memory synchronously and are flushed to
+ * the durable store in coalesced background batches. The durable store stays the
+ * source of truth for history and cross-instance reads, while a latency-sensitive
+ * hot path (a per-frame voice session, presence, cursors, game state) stays fast.
+ *
+ * This is the "fast authoritative local state, durable persistence synced behind it"
+ * split a sync engine like Convex makes — without adopting a whole sync-engine
+ * backend. Bring your own store via `load`/`persist`/`remove`.
+ */
+export declare const createWriteBehindCache: <K, V>(options: WriteBehindCacheOptions<K, V>) => WriteBehindCache<K, V>;

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@absolutejs/sync",
+	"version": "0.0.1",
+	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./client": {
+			"types": "./dist/client/index.d.ts",
+			"import": "./dist/client/index.js",
+			"default": "./dist/client/index.js"
+		}
+	},
+	"files": ["dist", "README.md"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun --external elysia && bun build src/client/index.ts --outdir dist/client --sourcemap --target=browser --format=esm && tsc --project tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish"
+	},
+	"keywords": [
+		"absolutejs",
+		"elysia",
+		"reactive",
+		"sse",
+		"realtime",
+		"write-behind",
+		"cache",
+		"sync"
+	],
+	"peerDependencies": {
+		"elysia": ">= 1.4.26"
+	},
+	"peerDependenciesMeta": {
+		"elysia": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"elysia": "latest",
+		"prettier": "latest",
+		"typescript": "latest"
+	}
+}