@super-line/tanstack-db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,79 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  superLineCollectionOptions: () => superLineCollectionOptions
+});
+module.exports = __toCommonJS(index_exports);
+function superLineCollectionOptions(client, contract, name, opts = {}) {
+  const key = contract.collections?.[name]?.key;
+  if (!key) throw new Error(`superLineCollectionOptions: collection '${String(name)}' is not declared on the contract`);
+  const handle = client.collection(name);
+  return {
+    id: `superline:${String(name)}`,
+    getKey: (row) => row[key],
+    sync: {
+      rowUpdateMode: "full",
+      // super-line updates carry the whole row
+      sync: ({ begin, write, commit, markReady }) => {
+        const rowSet = handle.subscribe(opts.query ?? {});
+        let ready = false;
+        let cancelled = false;
+        const off = rowSet.subscribe((ev) => {
+          if (!ready || cancelled) return;
+          begin();
+          if (ev.type === "delete") write({ type: "delete", key: ev.id });
+          else write({ type: ev.type, value: ev.row });
+          commit();
+        });
+        void rowSet.ready.then(() => {
+          if (cancelled) return;
+          begin();
+          for (const row of rowSet.rows()) write({ type: "insert", value: row });
+          commit();
+          ready = true;
+          markReady();
+        }).catch(() => {
+          if (!cancelled) markReady();
+        });
+        return () => {
+          cancelled = true;
+          off();
+          rowSet.close();
+        };
+      }
+    },
+    // Each optimistic transaction → ONE atomic super-line batch. Ack resolves the optimism; error rolls it back.
+    onInsert: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "insert", row: m.modified })));
+    },
+    onUpdate: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "update", row: m.modified })));
+    },
+    onDelete: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "delete", id: String(m.key) })));
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  superLineCollectionOptions
+});

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+import { CollectionQuery, Contract, RoleOf, CollectionName, RowOf } from '@super-line/core';
+import { SuperLineClient } from '@super-line/client';
+import { CollectionConfig } from '@tanstack/db';
+
+/** Options for {@link superLineCollectionOptions}. */
+interface SuperLineCollectionOptions {
+    /** The subset to sync (filter / orderBy / limit). Omit for the whole collection, subject to the server's row policy. */
+    query?: CollectionQuery;
+}
+/**
+ * Build TanStack DB collection options backed by a super-line collection. Feed the result to
+ * `createCollection(...)`; TanStack then owns client-side live queries, joins, and optimistic mutations while
+ * super-line is the server-authoritative sync source.
+ *
+ * - The initial snapshot + live changes flow from `client.collection(name).subscribe(query)`.
+ * - Optimistic mutations map to atomic super-line batches (`onInsert`/`onUpdate`/`onDelete`); the ack resolves
+ *   the optimistic transaction, an error rolls it back.
+ * - `getKey` comes from the contract. No client-side schema validation is wired: super-line validates every
+ *   write on the server (ADR-0006). // ponytail: pass the contract schema through here for optimistic pre-validation if wanted.
+ *
+ * @example
+ * ```ts
+ * const messages = createCollection(superLineCollectionOptions(client, contract, 'messages', { query: { filter: eq('channelId', id) } }))
+ * const users = createCollection(superLineCollectionOptions(client, contract, 'users'))
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ m: messages }).join({ u: users }, ({ m, u }) => eq(u.id, m.authorId), 'inner'),
+ * )
+ * ```
+ */
+declare function superLineCollectionOptions<C extends Contract, R extends RoleOf<C>, N extends CollectionName<C>>(client: SuperLineClient<C, R>, contract: C, name: N, opts?: SuperLineCollectionOptions): CollectionConfig<RowOf<C, N> & object, string>;
+
+export { type SuperLineCollectionOptions, superLineCollectionOptions };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { CollectionQuery, Contract, RoleOf, CollectionName, RowOf } from '@super-line/core';
+import { SuperLineClient } from '@super-line/client';
+import { CollectionConfig } from '@tanstack/db';
+
+/** Options for {@link superLineCollectionOptions}. */
+interface SuperLineCollectionOptions {
+    /** The subset to sync (filter / orderBy / limit). Omit for the whole collection, subject to the server's row policy. */
+    query?: CollectionQuery;
+}
+/**
+ * Build TanStack DB collection options backed by a super-line collection. Feed the result to
+ * `createCollection(...)`; TanStack then owns client-side live queries, joins, and optimistic mutations while
+ * super-line is the server-authoritative sync source.
+ *
+ * - The initial snapshot + live changes flow from `client.collection(name).subscribe(query)`.
+ * - Optimistic mutations map to atomic super-line batches (`onInsert`/`onUpdate`/`onDelete`); the ack resolves
+ *   the optimistic transaction, an error rolls it back.
+ * - `getKey` comes from the contract. No client-side schema validation is wired: super-line validates every
+ *   write on the server (ADR-0006). // ponytail: pass the contract schema through here for optimistic pre-validation if wanted.
+ *
+ * @example
+ * ```ts
+ * const messages = createCollection(superLineCollectionOptions(client, contract, 'messages', { query: { filter: eq('channelId', id) } }))
+ * const users = createCollection(superLineCollectionOptions(client, contract, 'users'))
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ m: messages }).join({ u: users }, ({ m, u }) => eq(u.id, m.authorId), 'inner'),
+ * )
+ * ```
+ */
+declare function superLineCollectionOptions<C extends Contract, R extends RoleOf<C>, N extends CollectionName<C>>(client: SuperLineClient<C, R>, contract: C, name: N, opts?: SuperLineCollectionOptions): CollectionConfig<RowOf<C, N> & object, string>;
+
+export { type SuperLineCollectionOptions, superLineCollectionOptions };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/index.ts
+function superLineCollectionOptions(client, contract, name, opts = {}) {
+  const key = contract.collections?.[name]?.key;
+  if (!key) throw new Error(`superLineCollectionOptions: collection '${String(name)}' is not declared on the contract`);
+  const handle = client.collection(name);
+  return {
+    id: `superline:${String(name)}`,
+    getKey: (row) => row[key],
+    sync: {
+      rowUpdateMode: "full",
+      // super-line updates carry the whole row
+      sync: ({ begin, write, commit, markReady }) => {
+        const rowSet = handle.subscribe(opts.query ?? {});
+        let ready = false;
+        let cancelled = false;
+        const off = rowSet.subscribe((ev) => {
+          if (!ready || cancelled) return;
+          begin();
+          if (ev.type === "delete") write({ type: "delete", key: ev.id });
+          else write({ type: ev.type, value: ev.row });
+          commit();
+        });
+        void rowSet.ready.then(() => {
+          if (cancelled) return;
+          begin();
+          for (const row of rowSet.rows()) write({ type: "insert", value: row });
+          commit();
+          ready = true;
+          markReady();
+        }).catch(() => {
+          if (!cancelled) markReady();
+        });
+        return () => {
+          cancelled = true;
+          off();
+          rowSet.close();
+        };
+      }
+    },
+    // Each optimistic transaction → ONE atomic super-line batch. Ack resolves the optimism; error rolls it back.
+    onInsert: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "insert", row: m.modified })));
+    },
+    onUpdate: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "update", row: m.modified })));
+    },
+    onDelete: async ({ transaction }) => {
+      await handle.batch(transaction.mutations.map((m) => ({ type: "delete", id: String(m.key) })));
+    }
+  };
+}
+export {
+  superLineCollectionOptions
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@super-line/tanstack-db",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TanStack DB collection adapter for super-line — use super-line collections as a TanStack DB sync source with client-side live queries and joins.",
+  "license": "MIT",
+  "author": "Mert",
+  "keywords": [
+    "super-line",
+    "tanstack",
+    "tanstack-db",
+    "collections",
+    "sync",
+    "live-query"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertdogar/super-line.git",
+    "directory": "packages/tanstack-db"
+  },
+  "homepage": "https://mertdogar.github.io/super-line/",
+  "bugs": "https://github.com/mertdogar/super-line/issues",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@super-line/core": "^0.10.1",
+    "@super-line/client": "^0.8.0"
+  },
+  "peerDependencies": {
+    "@tanstack/db": ">=0.1"
+  },
+  "devDependencies": {
+    "@tanstack/db": "^0.5.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.1",
+    "@super-line/server": "0.10.2",
+    "@super-line/collections-memory": "0.1.0",
+    "@super-line/transport-websocket": "0.6.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}