@absolutejs/sync 0.0.1 → 0.1.0

package/README.md

@@ -1,28 +1,40 @@
 # @absolutejs/sync
 
-Two small, composable primitives for live data in [Elysia](https://elysiajs.com)
-and the AbsoluteJS ecosystem:
+Reactive data primitives for [Elysia](https://elysiajs.com) and the AbsoluteJS
+ecosystem — kill polling and keep a remote store off your hot path, **on your own
+database and ORM** (Drizzle _or_ Prisma, any DB they support).
 
-- **`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.
+- **`createReactiveHub` + `sync` plugin** — push-on-change over SSE. A view
+  subscribes to the topics its data depends on; a mutation publishes those topics;
+  subscribers refetch (or read the pushed payload) the instant data changes.
+- **ORM adapters (`/drizzle`, `/prisma`)** — _derive_ those topics automatically
+  from a query, so you stop hand-naming them. A read maps to a `table` topic (or a
+  `table:key` row topic for a primary-key lookup); a mutation publishes the matching
+  topics.
+- **`createLiveQuery`** — a client query that hydrates once, then refetches whenever
+  one of its topics fires. Framework-agnostic (`get` + `subscribe`).
+- **Sync engine (`/engine`, `/postgres`)** — row-level reactive query results:
+  hydrate a collection once, then maintain it from `{ added, removed, changed }`
+  diffs over a WebSocket, with optimistic mutations, an offline queue, and access
+  control. CDC catches out-of-band writes; aggregations are incremental.
 - **`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.
+Unlike Convex, ElectricSQL, or Zero, it does **not** own or replicate your database
+— it stays a _library_ over the store, ORM, and transport you already have. Tier 1/2
+keep granularity deliberately coarse (table/row topics, refetch on change); the Tier
+3 engine adds true row-level diffs and optimistic writes. Single-table filtered
+queries are matched incrementally; joins (inner and left), aggregations, and
+top-N ordering are maintained incrementally through a composable operator graph
+(`query(...).filter().join().leftJoin().groupBy().orderBy()`).
 
-> 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.
+> Status: early (`0.0.1`). Tier 1 (hub, SSE plugin, browser subscriber,
+> write-behind cache), Tier 2 (Drizzle + Prisma topic adapters, `createLiveQuery`),
+> and Tier 3 (sync engine: collections, WebSocket diff transport, optimistic
+> mutations + offline queue, CDC for Postgres/MySQL/SQLite, incremental
+> aggregations + joins, and a declarative operator graph) are in place.
+> Everything ships as subpaths of this one package.
 
 ## Install
 
@@ -30,7 +42,8 @@ DB off your hot path, reach for this.
 bun add @absolutejs/sync
 ```
 
-`elysia` is an optional peer (only needed for the `sync` plugin).
+`elysia` is an optional peer (only needed for the `sync` plugin). The Drizzle adapter
+expects `drizzle-orm` if you use it; the Prisma adapter needs no Prisma import at all.
 
 ## Reactive push — kill the polling loop
 
@@ -66,6 +79,143 @@ const sub = createSyncSubscriber({
 // sub.close() when the view unmounts
 ```
 
+`resolveTopics` on the plugin lets you derive a connection's topics from the session
+or auth instead of trusting the client's `?topics=`.
+
+## ORM auto-reactivity — stop hand-naming topics
+
+The adapters turn a query into the topics it touches, so reads and writes line up
+automatically. Same function names for both ORMs; pick the matching subpath.
+
+```ts
+// server — Drizzle
+import { eq } from 'drizzle-orm';
+import { deriveReadTopics, publishWhere } from '@absolutejs/sync/drizzle';
+
+new Elysia()
+	.use(sync({ hub }))
+	.get('/api/orders', () => db.select().from(orders)) // list -> topic "orders"
+	.patch('/api/orders/:id', async ({ params, body }) => {
+		const id = Number(params.id);
+		await db.update(orders).set(body).where(eq(orders.id, id));
+		publishWhere(hub, orders, eq(orders.id, id), { op: 'update' });
+		// publishes "orders" and "orders:<id>"
+	});
+```
+
+```ts
+// browser — createLiveQuery + Prisma topic derivation (just a model name, no deps)
+import { createLiveQuery, jsonFetcher } from '@absolutejs/sync/client';
+import { deriveReadTopics } from '@absolutejs/sync/prisma';
+
+const orders = createLiveQuery({
+	topics: deriveReadTopics('order').topics, // ['order']
+	fetcher: jsonFetcher('/api/orders')
+});
+
+orders.subscribe((state) => render(state.data)); // refetches on every order change
+// orders.close() when the view unmounts
+```
+
+`createLiveQuery` is a small observable store: `get()` for the current
+`{ data, error, loading, fetching }`, `subscribe(listener)` for changes (plugs
+straight into React's `useSyncExternalStore`), plus `refetch()` and `close()`. It
+supersedes overlapping fetches (last write wins), re-hydrates on reconnect, and takes
+`initialData` (SSR seed), `manual`, and `debounceMs`.
+
+What the adapters derive:
+
+- `deriveReadTopics(orders)` → `{ topics: ['orders'], rowLevel: false }`
+- `deriveReadTopics(orders, eq(orders.id, 5))` → `{ topics: ['orders:5'], rowLevel: true }`
+- anything more complex (joins, `and`/`or`, ranges, `in`, non-key columns) falls back
+  to the table topic — over-invalidating rather than missing an update.
+- Write side: `publishChange` (explicit keys), `publishRows` (keys from a mutation's
+  returned/created records), `publishWhere` (keys from an update/delete filter).
+
+The Prisma adapter parses Prisma's plain `where`/result objects, so it needs no
+`@prisma/client` import; the Drizzle adapter reads the schema's table objects.
+
+## Live collections — the sync engine (Tier 3)
+
+Row-level reactive results: the client holds a collection and the server pushes
+`{ added, removed, changed }` diffs over a WebSocket, instead of refetching. Define
+a collection once (the filter powers both the DB hydrate and the incremental
+matcher), expose it over `syncSocket`, and drive changes from mutations.
+
+```ts
+// server
+import { Elysia } from 'elysia';
+import { syncSocket } from '@absolutejs/sync';
+import { createSyncEngine, defineMutation } from '@absolutejs/sync/engine';
+import { prismaCollection } from '@absolutejs/sync/prisma';
+
+const engine = createSyncEngine();
+
+engine.register(
+	prismaCollection({
+		name: 'orders',
+		where: (params) => ({ userId: params.userId, status: 'open' }), // written once
+		find: (where) => prisma.order.findMany({ where }),
+		authorize: (params, ctx) => params.userId === ctx.userId // never leak rows
+	})
+);
+
+engine.registerMutation(
+	defineMutation({
+		name: 'createOrder',
+		handler: async (args, ctx, actions) => {
+			const order = await prisma.order.create({
+				data: { ...args, userId: ctx.userId }
+			});
+			await actions.change('orders', { op: 'insert', row: order });
+			return order;
+		}
+	})
+);
+
+new Elysia()
+	.use(
+		syncSocket({
+			engine,
+			resolveContext: (data) => ({ userId: data.userId })
+		})
+	)
+	.listen(3000);
+```
+
+```ts
+// browser
+import { createSyncCollection } from '@absolutejs/sync/client';
+
+const orders = createSyncCollection({
+	url: 'ws://localhost:3000/sync/ws',
+	collection: 'orders',
+	params: { userId }
+});
+
+orders.subscribe((state) => render(state.data)); // live: diff-driven, auto-reconnect
+
+// optimistic write — instant UI, reconciled (or rolled back) by the server
+await orders.mutate({
+	name: 'createOrder',
+	args: { total: 42 },
+	optimistic: (draft) => draft.set({ id: tempId, total: 42, status: 'open' })
+});
+```
+
+- **Incremental vs refetch.** A single-table filtered collection is matched
+  incrementally (only the changed rows move). Joins/aggregations and filters the
+  matcher can't evaluate fall back to a correct re-hydrate. `createAggregate`
+  (`/engine`) maintains `count`/`sum`/`avg`/`min`/`max` + `groupBy` incrementally.
+- **Out-of-band writes.** Writes that bypass mutations are caught by a
+  `ChangeSource` — e.g. `postgresChangeSource` (`/postgres`) over `LISTEN/NOTIFY`,
+  wired with `engine.connectSource(...)` and the trigger SQL from
+  `postgresNotifyTrigger`.
+- **Offline.** Pending mutations replay on reconnect; pass `storage`
+  (e.g. `localStorageMutationStorage`) to also survive a reload.
+- **Access control is mandatory.** Each collection's `authorize` gates subscribe and
+  its filter scopes rows, so a change to a row a caller can't see never reaches them.
+
 ## Write-behind cache — keep a remote store off your hot path
 
 ```ts
@@ -90,12 +240,102 @@ it, ~3 store round-trips every 20ms ran the voice pipeline far slower than real
 
 ## 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. |
+### `@absolutejs/sync`
+
+| 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.                             |
+| `syncSocket({ engine, path?, resolveContext? })`                                           | Elysia WebSocket plugin for the sync engine.                         |
+| `createWriteBehindCache({ load, persist, remove?, debounceMs?, evict?, onPersistError? })` | In-memory cache + write-behind persistence.                          |
+
+### `@absolutejs/sync/client`
+
+| Export                                            | What it is                                                      |
+| ------------------------------------------------- | --------------------------------------------------------------- |
+| `createSyncSubscriber({ topics, onEvent, url? })` | Browser SSE client.                                             |
+| `createLiveQuery({ topics, fetcher, ... })`       | Hydrate-once, refetch-on-event observable query store.          |
+| `jsonFetcher(url, init?)`                         | Default `fetcher`: GET + JSON parse, forwards the abort signal. |
+| `createSyncCollection({ url, collection, ... })`  | Live diff-driven collection store with optimistic `mutate`.     |
+| `localStorageMutationStorage(key)`                | `localStorage`-backed offline queue for `createSyncCollection`. |
+
+### Framework bindings — `@absolutejs/sync/{react,vue,svelte,angular}`
+
+Idiomatic wrappers over `createSyncCollection`, one per framework, so a live
+collection is one call. Each returns the same `{ data, status, error, mutate }`
+and is SSR-safe (the socket opens on the client only).
+
+| Subpath    | Export                                   | What it is                                           |
+| ---------- | ---------------------------------------- | ---------------------------------------------------- |
+| `/react`   | `useSyncCollection(options)`             | React hook (re-renders on diffs).                    |
+| `/vue`     | `useSyncCollection(options)`             | Vue composable (reactive refs).                      |
+| `/svelte`  | `createSyncCollectionStore(options)`     | Svelte readable store (`$store` → state) + `mutate`. |
+| `/angular` | `SyncCollectionService.connect(options)` | Angular service returning signals.                   |
+
+```tsx
+// React
+import { useSyncCollection } from '@absolutejs/sync/react';
+
+const { data, status, mutate } = useSyncCollection<Order>({
+	url: 'ws://localhost:3000/sync/ws',
+	collection: 'orders',
+	params: { userId }
+});
+
+mutate({
+	name: 'createOrder',
+	args: { total: 42 },
+	optimistic: (draft) => draft.set({ id: tempId, total: 42 } as Order)
+});
+```
+
+### `@absolutejs/sync/engine`
+
+| Export                                                                      | What it is                                                                                                          |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `createSyncEngine()`                                                        | Registry + view syncer: `register`, `subscribe`, `applyChange`, `connectSource`, `registerMutation`, `runMutation`. |
+| `defineCollection({ name, hydrate, key?, match?, authorize?, tables? })`    | Define a syncable collection.                                                                                       |
+| `defineMutation({ name, handler, authorize? })`                             | Define a server mutation that emits changes.                                                                        |
+| `createAggregate({ key, groupBy?, value? })`                                | Incremental count/sum/avg/min/max by group.                                                                         |
+| `createMaterializedView({ key, match, equals? })`                           | The predicate-matching IVM primitive (`apply`/`reset` → diffs).                                                     |
+| `createPollingChangeSource({ poll, intervalMs?, startSeq?, onProcessed? })` | DB-agnostic CDC `ChangeSource` that tails a changelog (outbox) table.                                               |
+| `query(source).filter().map().join().leftJoin().groupBy().orderBy()`        | Declarative incremental query builder (the operator graph).                                                         |
+| `defineGraphCollection({ name, query, key, authorize? })`                   | Run a `query` as a live collection.                                                                                 |
+
+### `@absolutejs/sync/postgres`
+
+| Export                                                       | What it is                                                       |
+| ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `postgresChangeSource({ listen, channel?, parse? })`         | CDC `ChangeSource` over `LISTEN/NOTIFY` (bring your own client). |
+| `postgresNotifyTrigger({ tables, channel?, functionName? })` | SQL to install the notify triggers (run once).                   |
+
+### `@absolutejs/sync/mysql`
+
+| Export                                                       | What it is                                                                  |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `mysqlChangelogSchema({ tables, changelogTable?, prefix? })` | SQL to install the changelog table + triggers (run once).                   |
+| `createPollingChangeSource({ poll, ... })`                   | Tail the changelog (re-exported from the engine).                           |
+| `mysqlBinlogChangeSource({ subscribe, normalize? })`         | Higher-throughput CDC over the binlog (bring your own reader, e.g. zongji). |
+| `normalizeBinlogEvent(event)`                                | Pure: a binlog row event → engine changes.                                  |
+
+### `@absolutejs/sync/sqlite`
+
+| Export                                                        | What it is                                                |
+| ------------------------------------------------------------- | --------------------------------------------------------- |
+| `sqliteChangelogSchema({ tables, changelogTable?, prefix? })` | SQL to install the changelog table + triggers (run once). |
+| `createPollingChangeSource({ poll, ... })`                    | Tail the changelog (re-exported from the engine).         |
+
+### `@absolutejs/sync/drizzle` and `@absolutejs/sync/prisma`
+
+| Export                                                                | What it is                                                 |
+| --------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `deriveReadTopics(table\|model, where?, options?)`                    | Topics a read depends on (`{ topics, rowLevel }`).         |
+| `publishChange(hub, table\|model, { keys?, op? })`                    | Publish the table topic + a row topic per key.             |
+| `publishRows(hub, table\|model, rows, { keyField?/keyColumn?, op? })` | Publish topics for returned/created records.               |
+| `publishWhere(hub, table\|model, where, { ..., op? })`                | Publish topics for an update/delete filter.                |
+| `tableTopic` / `keyTopic`                                             | The shared topic vocabulary both sides speak.              |
+| `prismaCollection({ name, where, find, ... })` (prisma)               | A sync-engine collection; one `where` → hydrate + matcher. |
+| `matchesWhere(where, row)` (prisma)                                   | Evaluate a Prisma `where` against a row (the matcher).     |
 
 ## License
 

package/dist/adapters/drizzle/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Drizzle adapter for @absolutejs/sync (Tier 2 — ORM auto-reactivity).
+ *
+ * Derives reactive-hub topics from a Drizzle schema so you stop hand-naming
+ * them: a read subscribes to the topics it depends on ({@link deriveReadTopics})
+ * and a mutation publishes the topics it invalidates ({@link publishChange} and
+ * friends). Both speak the same {@link tableTopic}/{@link keyTopic} vocabulary,
+ * so reads and writes always line up.
+ *
+ * Granularity is deliberately coarse and DB-agnostic: table-level by default,
+ * narrowing to a single row when a filter is a simple primary-key equality.
+ */
+export { keyTopic, tableTopic } from './topics';
+export { deriveReadTopics } from './read';
+export type { DeriveReadTopicsOptions, DerivedReadTopics } from './read';
+export { publishChange, publishRows, publishWhere } from './write';
+export type { ChangeOp, ChangePayload, PublishChangeOptions, PublishRowsOptions, PublishWhereOptions } from './write';

package/dist/adapters/drizzle/index.js

@@ -0,0 +1,128 @@
+// @bun
+// src/adapters/drizzle/topics.ts
+import {
+  Column,
+  getTableColumns,
+  getTableName,
+  is,
+  Param,
+  SQL
+} from "drizzle-orm";
+var tableTopic = (table) => getTableName(table);
+var keyTopic = (table, key) => `${getTableName(table)}:${key}`;
+var resolveKeyColumn = (table, keyColumn) => {
+  const columns = getTableColumns(table);
+  if (keyColumn !== undefined) {
+    const column = columns[keyColumn];
+    return column === undefined ? undefined : { property: keyColumn, column: column.name };
+  }
+  const primaries = Object.entries(columns).filter(([, column]) => column.primary);
+  const primary = primaries.length === 1 ? primaries[0] : undefined;
+  return primary === undefined ? undefined : { property: primary[0], column: primary[1].name };
+};
+var extractKeyFromWhere = (table, where, keyColumn) => {
+  const resolved = resolveKeyColumn(table, keyColumn);
+  if (resolved === undefined) {
+    return;
+  }
+  const chunks = where.queryChunks;
+  if (!Array.isArray(chunks)) {
+    return;
+  }
+  let column;
+  let param;
+  let tooComplex = false;
+  let operator = "";
+  for (const chunk of chunks) {
+    if (is(chunk, SQL)) {
+      return;
+    }
+    if (is(chunk, Column)) {
+      if (column !== undefined) {
+        tooComplex = true;
+      }
+      column = chunk;
+    } else if (is(chunk, Param)) {
+      if (param !== undefined) {
+        tooComplex = true;
+      }
+      param = chunk;
+    } else {
+      const value2 = chunk.value;
+      if (Array.isArray(value2)) {
+        operator += value2.join("");
+      }
+    }
+  }
+  if (tooComplex || column === undefined || param === undefined) {
+    return;
+  }
+  if (operator.trim() !== "=") {
+    return;
+  }
+  if (column.name !== resolved.column) {
+    return;
+  }
+  if (getTableName(column.table) !== getTableName(table)) {
+    return;
+  }
+  const value = param.value;
+  return typeof value === "string" || typeof value === "number" ? value : undefined;
+};
+var extractRowKeys = (table, rows, keyColumn) => {
+  const resolved = resolveKeyColumn(table, keyColumn);
+  if (resolved === undefined) {
+    return [];
+  }
+  const keys = [];
+  for (const row of rows) {
+    const value = row[resolved.property];
+    if (typeof value === "string" || typeof value === "number") {
+      keys.push(value);
+    }
+  }
+  return keys;
+};
+// src/adapters/drizzle/read.ts
+var deriveReadTopics = (table, where, options = {}) => {
+  const key = where === undefined ? undefined : extractKeyFromWhere(table, where, options.keyColumn);
+  if (key === undefined) {
+    return { topics: [tableTopic(table)], rowLevel: false };
+  }
+  return { topics: [keyTopic(table, key)], rowLevel: true };
+};
+// src/adapters/drizzle/write.ts
+var publishChange = (hub, table, options = {}) => {
+  const name = tableTopic(table);
+  const keys = options.keys === undefined ? [] : [...new Set(options.keys)];
+  const payload = { table: name, op: options.op, keys };
+  const topics = [
+    ...new Set([name, ...keys.map((key) => keyTopic(table, key))])
+  ];
+  for (const topic of topics) {
+    hub.publish(topic, payload);
+  }
+  return topics;
+};
+var publishRows = (hub, table, rows, options = {}) => publishChange(hub, table, {
+  keys: extractRowKeys(table, rows, options.keyColumn),
+  op: options.op
+});
+var publishWhere = (hub, table, where, options = {}) => {
+  const key = extractKeyFromWhere(table, where, options.keyColumn);
+  return publishChange(hub, table, {
+    keys: key === undefined ? [] : [key],
+    op: options.op
+  });
+};
+export {
+  tableTopic,
+  publishWhere,
+  publishRows,
+  publishChange,
+  keyTopic,
+  deriveReadTopics
+};
+
+//# debugId=ADD7C375EE239C1664756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/adapters/drizzle/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/adapters/drizzle/topics.ts", "../src/adapters/drizzle/read.ts", "../src/adapters/drizzle/write.ts"],
+  "sourcesContent": [
+    "import {\n\tColumn,\n\tgetTableColumns,\n\tgetTableName,\n\tis,\n\tParam,\n\tSQL\n} from 'drizzle-orm';\nimport type { Table } from 'drizzle-orm';\n\n/**\n * Shared topic vocabulary + key resolution for the Drizzle adapter. Both the\n * read side (derive the topics a query depends on) and the write side (publish\n * the topics a mutation invalidates) build on these so the two always agree.\n */\n\n/** The coarse topic every read/write of `table` touches, e.g. `users`. */\nexport const tableTopic = (table: Table): string => getTableName(table);\n\n/** The row-level topic for one key of `table`, e.g. `users:5`. */\nexport const keyTopic = (table: Table, key: string | number): string =>\n\t`${getTableName(table)}:${key}`;\n\ntype ResolvedKey = {\n\t/** JS property name of the key column on the table / result rows. */\n\tproperty: string;\n\t/** Underlying DB column name, as it appears in a SQL expression. */\n\tcolumn: string;\n};\n\n/**\n * Resolve the column to use as the row key: an explicitly requested column (by\n * JS property name), otherwise the table's sole primary key. Returns `undefined`\n * when no single key column applies (composite or missing primary key).\n */\nexport const resolveKeyColumn = (\n\ttable: Table,\n\tkeyColumn?: string\n): ResolvedKey | undefined => {\n\tconst columns = getTableColumns(table);\n\tif (keyColumn !== undefined) {\n\t\tconst column = columns[keyColumn];\n\t\treturn column === undefined\n\t\t\t? undefined\n\t\t\t: { property: keyColumn, column: column.name };\n\t}\n\tconst primaries = Object.entries(columns).filter(\n\t\t([, column]) => column.primary\n\t);\n\tconst primary = primaries.length === 1 ? primaries[0] : undefined;\n\treturn primary === undefined\n\t\t? undefined\n\t\t: { property: primary[0], column: primary[1].name };\n};\n\n/**\n * Best-effort: pull a single key-column equality value out of a Drizzle `where`\n * expression. Recognises only the simple `eq(keyColumn, scalar)` shape — any\n * nesting (`and`/`or`), extra columns/params, a non-`=` operator, or a\n * non-key/cross-table column yields `undefined`.\n *\n * Reads Drizzle's internal `queryChunks`, which is not a stable public API;\n * every branch degrades to `undefined` (coarser topic) rather than throwing, so\n * a Drizzle version bump can only cost precision, never correctness.\n */\nexport const extractKeyFromWhere = (\n\ttable: Table,\n\twhere: SQL,\n\tkeyColumn?: string\n): string | number | undefined => {\n\tconst resolved = resolveKeyColumn(table, keyColumn);\n\tif (resolved === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst chunks: unknown = (where as { queryChunks?: unknown }).queryChunks;\n\tif (!Array.isArray(chunks)) {\n\t\treturn undefined;\n\t}\n\n\tlet column: Column | undefined;\n\tlet param: Param | undefined;\n\tlet tooComplex = false;\n\tlet operator = '';\n\n\tfor (const chunk of chunks) {\n\t\tif (is(chunk, SQL)) {\n\t\t\t// Nested expression (e.g. and/or) — not a simple equality.\n\t\t\treturn undefined;\n\t\t}\n\t\tif (is(chunk, Column)) {\n\t\t\tif (column !== undefined) {\n\t\t\t\ttooComplex = true;\n\t\t\t}\n\t\t\tcolumn = chunk;\n\t\t} else if (is(chunk, Param)) {\n\t\t\tif (param !== undefined) {\n\t\t\t\ttooComplex = true;\n\t\t\t}\n\t\t\tparam = chunk;\n\t\t} else {\n\t\t\tconst value: unknown = (chunk as { value?: unknown }).value;\n\t\t\tif (Array.isArray(value)) {\n\t\t\t\toperator += value.join('');\n\t\t\t}\n\t\t}\n\t}\n\n\tif (tooComplex || column === undefined || param === undefined) {\n\t\treturn undefined;\n\t}\n\tif (operator.trim() !== '=') {\n\t\treturn undefined;\n\t}\n\tif (column.name !== resolved.column) {\n\t\treturn undefined;\n\t}\n\tif (getTableName(column.table) !== getTableName(table)) {\n\t\treturn undefined;\n\t}\n\n\tconst value: unknown = param.value;\n\treturn typeof value === 'string' || typeof value === 'number'\n\t\t? value\n\t\t: undefined;\n};\n\n/**\n * Read the key value from each row (e.g. the output of a mutation's\n * `.returning()`), using the table's primary-key column or an explicit\n * `keyColumn`. Rows without a string/number key are skipped.\n */\nexport const extractRowKeys = (\n\ttable: Table,\n\trows: ReadonlyArray<Record<string, unknown>>,\n\tkeyColumn?: string\n): (string | number)[] => {\n\tconst resolved = resolveKeyColumn(table, keyColumn);\n\tif (resolved === undefined) {\n\t\treturn [];\n\t}\n\tconst keys: (string | number)[] = [];\n\tfor (const row of rows) {\n\t\tconst value = row[resolved.property];\n\t\tif (typeof value === 'string' || typeof value === 'number') {\n\t\t\tkeys.push(value);\n\t\t}\n\t}\n\treturn keys;\n};\n",
+    "import type { SQL, Table } from 'drizzle-orm';\nimport { extractKeyFromWhere, keyTopic, tableTopic } from './topics';\n\nexport type DeriveReadTopicsOptions = {\n\t/**\n\t * Column (its JS property name on the table) to treat as the row key when\n\t * narrowing to a `table:key` topic. Defaults to the table's single\n\t * primary-key column; composite or absent primary keys disable row-level\n\t * narrowing.\n\t */\n\tkeyColumn?: string;\n};\n\nexport type DerivedReadTopics = {\n\t/** Topics this read depends on — subscribe to all of them. */\n\ttopics: string[];\n\t/**\n\t * `true` when derivation narrowed to a specific row (`table:key`); `false`\n\t * when it fell back to the whole-table topic.\n\t */\n\trowLevel: boolean;\n};\n\n/**\n * Derive the reactive topics a read of `table` (optionally filtered by `where`)\n * depends on. A recognised primary-key equality narrows to a single `table:key`\n * topic; everything else subscribes to the whole-table topic, over-invalidating\n * a little rather than missing an update.\n *\n * @example\n * deriveReadTopics(users);                  // { topics: ['users'], rowLevel: false }\n * deriveReadTopics(users, eq(users.id, 5)); // { topics: ['users:5'], rowLevel: true }\n * deriveReadTopics(users, gt(users.id, 5)); // { topics: ['users'], rowLevel: false }\n */\nexport const deriveReadTopics = (\n\ttable: Table,\n\twhere?: SQL,\n\toptions: DeriveReadTopicsOptions = {}\n): DerivedReadTopics => {\n\tconst key =\n\t\twhere === undefined\n\t\t\t? undefined\n\t\t\t: extractKeyFromWhere(table, where, options.keyColumn);\n\n\tif (key === undefined) {\n\t\treturn { topics: [tableTopic(table)], rowLevel: false };\n\t}\n\treturn { topics: [keyTopic(table, key)], rowLevel: true };\n};\n",
+    "import type { SQL, Table } from 'drizzle-orm';\nimport type { ReactiveHub } from '../../reactiveHub';\nimport {\n\textractKeyFromWhere,\n\textractRowKeys,\n\tkeyTopic,\n\ttableTopic\n} from './topics';\n\n/**\n * Drizzle write-side topic publishing (Tier 2).\n *\n * The mirror of {@link deriveReadTopics}: after a mutation commits, publish the\n * topics it invalidates so subscribed reads refetch. Every change publishes the\n * **table** topic (so list/table queries refresh) plus a **row** topic per\n * affected key (so row-level queries refresh) — the exact topics the read side\n * subscribes to.\n *\n * These are the \"route mutations through us\" change source from the roadmap:\n * call them right after your durable write. They work on any DB Drizzle supports\n * and never touch DB-specific machinery; out-of-band writes (caught later by CDC\n * adapters) are the only thing they miss.\n */\n\n/** The kind of mutation, forwarded in the change-event payload. */\nexport type ChangeOp = 'insert' | 'update' | 'delete';\n\n/** Payload carried by every change event the write side publishes. */\nexport type ChangePayload = {\n\t/** Name of the table that changed. */\n\ttable: string;\n\t/** Mutation kind, when the caller provided it. */\n\top?: ChangeOp;\n\t/** Affected row keys (empty for a table-wide change). */\n\tkeys: (string | number)[];\n};\n\nexport type PublishChangeOptions = {\n\t/** Row keys that changed; each emits a `table:key` topic. */\n\tkeys?: ReadonlyArray<string | number>;\n\top?: ChangeOp;\n};\n\n/**\n * Publish the reactive topics a change to `table` invalidates: the whole-table\n * topic (always) plus a `table:key` topic per affected row. Call after the\n * durable write commits. Returns the (de-duplicated) topics published.\n */\nexport const publishChange = (\n\thub: Pick<ReactiveHub, 'publish'>,\n\ttable: Table,\n\toptions: PublishChangeOptions = {}\n): string[] => {\n\tconst name = tableTopic(table);\n\tconst keys = options.keys === undefined ? [] : [...new Set(options.keys)];\n\tconst payload: ChangePayload = { table: name, op: options.op, keys };\n\tconst topics = [\n\t\t...new Set([name, ...keys.map((key) => keyTopic(table, key))])\n\t];\n\tfor (const topic of topics) {\n\t\thub.publish(topic, payload);\n\t}\n\treturn topics;\n};\n\nexport type PublishRowsOptions = {\n\t/** Key column (JS property name); defaults to the table's primary key. */\n\tkeyColumn?: string;\n\top?: ChangeOp;\n};\n\n/**\n * Publish change topics for a set of rows — typically the output of a mutation's\n * `.returning()`, which yields real keys including auto-generated ones. Reads\n * each row's primary-key column (or `keyColumn`) to emit `table:key` topics.\n *\n * @example\n * const rows = await db.insert(users).values(input).returning();\n * publishRows(hub, users, rows, { op: 'insert' });\n */\nexport const publishRows = (\n\thub: Pick<ReactiveHub, 'publish'>,\n\ttable: Table,\n\trows: ReadonlyArray<Record<string, unknown>>,\n\toptions: PublishRowsOptions = {}\n): string[] =>\n\tpublishChange(hub, table, {\n\t\tkeys: extractRowKeys(table, rows, options.keyColumn),\n\t\top: options.op\n\t});\n\nexport type PublishWhereOptions = {\n\t/** Key column (JS property name); defaults to the table's primary key. */\n\tkeyColumn?: string;\n\top?: ChangeOp;\n};\n\n/**\n * Publish change topics for an `update`/`delete` identified by a `where` filter.\n * A simple primary-key equality narrows to that row's topic; any other filter\n * publishes just the table topic, so every affected subscriber refetches and\n * re-evaluates.\n *\n * @example\n * await db.update(users).set(patch).where(eq(users.id, id));\n * publishWhere(hub, users, eq(users.id, id), { op: 'update' });\n */\nexport const publishWhere = (\n\thub: Pick<ReactiveHub, 'publish'>,\n\ttable: Table,\n\twhere: SQL,\n\toptions: PublishWhereOptions = {}\n): string[] => {\n\tconst key = extractKeyFromWhere(table, where, options.keyColumn);\n\treturn publishChange(hub, table, {\n\t\tkeys: key === undefined ? [] : [key],\n\t\top: options.op\n\t});\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "ADD7C375EE239C1664756E2164756E21",
+  "names": []
+}

package/dist/adapters/drizzle/read.d.ts

@@ -0,0 +1,31 @@
+import type { SQL, Table } from 'drizzle-orm';
+export type DeriveReadTopicsOptions = {
+    /**
+     * Column (its JS property name on the table) to treat as the row key when
+     * narrowing to a `table:key` topic. Defaults to the table's single
+     * primary-key column; composite or absent primary keys disable row-level
+     * narrowing.
+     */
+    keyColumn?: string;
+};
+export type DerivedReadTopics = {
+    /** Topics this read depends on — subscribe to all of them. */
+    topics: string[];
+    /**
+     * `true` when derivation narrowed to a specific row (`table:key`); `false`
+     * when it fell back to the whole-table topic.
+     */
+    rowLevel: boolean;
+};
+/**
+ * Derive the reactive topics a read of `table` (optionally filtered by `where`)
+ * depends on. A recognised primary-key equality narrows to a single `table:key`
+ * topic; everything else subscribes to the whole-table topic, over-invalidating
+ * a little rather than missing an update.
+ *
+ * @example
+ * deriveReadTopics(users);                  // { topics: ['users'], rowLevel: false }
+ * deriveReadTopics(users, eq(users.id, 5)); // { topics: ['users:5'], rowLevel: true }
+ * deriveReadTopics(users, gt(users.id, 5)); // { topics: ['users'], rowLevel: false }
+ */
+export declare const deriveReadTopics: (table: Table, where?: SQL, options?: DeriveReadTopicsOptions) => DerivedReadTopics;

package/dist/adapters/drizzle/topics.d.ts

@@ -0,0 +1,41 @@
+import { SQL } from 'drizzle-orm';
+import type { Table } from 'drizzle-orm';
+/**
+ * Shared topic vocabulary + key resolution for the Drizzle adapter. Both the
+ * read side (derive the topics a query depends on) and the write side (publish
+ * the topics a mutation invalidates) build on these so the two always agree.
+ */
+/** The coarse topic every read/write of `table` touches, e.g. `users`. */
+export declare const tableTopic: (table: Table) => string;
+/** The row-level topic for one key of `table`, e.g. `users:5`. */
+export declare const keyTopic: (table: Table, key: string | number) => string;
+type ResolvedKey = {
+    /** JS property name of the key column on the table / result rows. */
+    property: string;
+    /** Underlying DB column name, as it appears in a SQL expression. */
+    column: string;
+};
+/**
+ * Resolve the column to use as the row key: an explicitly requested column (by
+ * JS property name), otherwise the table's sole primary key. Returns `undefined`
+ * when no single key column applies (composite or missing primary key).
+ */
+export declare const resolveKeyColumn: (table: Table, keyColumn?: string) => ResolvedKey | undefined;
+/**
+ * Best-effort: pull a single key-column equality value out of a Drizzle `where`
+ * expression. Recognises only the simple `eq(keyColumn, scalar)` shape — any
+ * nesting (`and`/`or`), extra columns/params, a non-`=` operator, or a
+ * non-key/cross-table column yields `undefined`.
+ *
+ * Reads Drizzle's internal `queryChunks`, which is not a stable public API;
+ * every branch degrades to `undefined` (coarser topic) rather than throwing, so
+ * a Drizzle version bump can only cost precision, never correctness.
+ */
+export declare const extractKeyFromWhere: (table: Table, where: SQL, keyColumn?: string) => string | number | undefined;
+/**
+ * Read the key value from each row (e.g. the output of a mutation's
+ * `.returning()`), using the table's primary-key column or an explicit
+ * `keyColumn`. Rows without a string/number key are skipped.
+ */
+export declare const extractRowKeys: (table: Table, rows: ReadonlyArray<Record<string, unknown>>, keyColumn?: string) => (string | number)[];
+export {};

package/dist/adapters/drizzle/write.d.ts

@@ -0,0 +1,69 @@
+import type { SQL, Table } from 'drizzle-orm';
+import type { ReactiveHub } from '../../reactiveHub';
+/**
+ * Drizzle write-side topic publishing (Tier 2).
+ *
+ * The mirror of {@link deriveReadTopics}: after a mutation commits, publish the
+ * topics it invalidates so subscribed reads refetch. Every change publishes the
+ * **table** topic (so list/table queries refresh) plus a **row** topic per
+ * affected key (so row-level queries refresh) — the exact topics the read side
+ * subscribes to.
+ *
+ * These are the "route mutations through us" change source from the roadmap:
+ * call them right after your durable write. They work on any DB Drizzle supports
+ * and never touch DB-specific machinery; out-of-band writes (caught later by CDC
+ * adapters) are the only thing they miss.
+ */
+/** The kind of mutation, forwarded in the change-event payload. */
+export type ChangeOp = 'insert' | 'update' | 'delete';
+/** Payload carried by every change event the write side publishes. */
+export type ChangePayload = {
+    /** Name of the table that changed. */
+    table: string;
+    /** Mutation kind, when the caller provided it. */
+    op?: ChangeOp;
+    /** Affected row keys (empty for a table-wide change). */
+    keys: (string | number)[];
+};
+export type PublishChangeOptions = {
+    /** Row keys that changed; each emits a `table:key` topic. */
+    keys?: ReadonlyArray<string | number>;
+    op?: ChangeOp;
+};
+/**
+ * Publish the reactive topics a change to `table` invalidates: the whole-table
+ * topic (always) plus a `table:key` topic per affected row. Call after the
+ * durable write commits. Returns the (de-duplicated) topics published.
+ */
+export declare const publishChange: (hub: Pick<ReactiveHub, "publish">, table: Table, options?: PublishChangeOptions) => string[];
+export type PublishRowsOptions = {
+    /** Key column (JS property name); defaults to the table's primary key. */
+    keyColumn?: string;
+    op?: ChangeOp;
+};
+/**
+ * Publish change topics for a set of rows — typically the output of a mutation's
+ * `.returning()`, which yields real keys including auto-generated ones. Reads
+ * each row's primary-key column (or `keyColumn`) to emit `table:key` topics.
+ *
+ * @example
+ * const rows = await db.insert(users).values(input).returning();
+ * publishRows(hub, users, rows, { op: 'insert' });
+ */
+export declare const publishRows: (hub: Pick<ReactiveHub, "publish">, table: Table, rows: ReadonlyArray<Record<string, unknown>>, options?: PublishRowsOptions) => string[];
+export type PublishWhereOptions = {
+    /** Key column (JS property name); defaults to the table's primary key. */
+    keyColumn?: string;
+    op?: ChangeOp;
+};
+/**
+ * Publish change topics for an `update`/`delete` identified by a `where` filter.
+ * A simple primary-key equality narrows to that row's topic; any other filter
+ * publishes just the table topic, so every affected subscriber refetches and
+ * re-evaluates.
+ *
+ * @example
+ * await db.update(users).set(patch).where(eq(users.id, id));
+ * publishWhere(hub, users, eq(users.id, id), { op: 'update' });
+ */
+export declare const publishWhere: (hub: Pick<ReactiveHub, "publish">, table: Table, where: SQL, options?: PublishWhereOptions) => string[];