@nativewindow/tsdb 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Saverio Cannizzaro
+
+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/README.md

@@ -0,0 +1,111 @@
+# @nativewindow/tsdb
+
+[![npm](https://img.shields.io/npm/v/@nativewindow/tsdb)](https://www.npmjs.com/package/@nativewindow/tsdb)
+
+> [!WARNING]
+> This project is in **alpha**. APIs may change without notice.
+
+[TanStack DB](https://tanstack.com/db) collection adapter for [native-window](https://github.com/nativewindow/webview) IPC. Sync data between the host process and webview collections over the native IPC bridge.
+
+## Install
+
+```bash
+bun add @nativewindow/tsdb
+# or
+deno add npm:@nativewindow/tsdb
+```
+
+## Overview
+
+Two entry points for the two sides of the bridge:
+
+| Entry                       | Side                 | Export                          |
+| --------------------------- | -------------------- | ------------------------------- |
+| `@nativewindow/tsdb`        | Host (Bun/Deno/Node) | `createDataSource`              |
+| `@nativewindow/tsdb/client` | Webview              | `nativeWindowCollectionOptions` |
+
+## Host side (Bun/Deno/Node)
+
+Create a data source and sync data to the webview:
+
+```ts
+import { createDataSource } from "@nativewindow/tsdb";
+
+const ds = createDataSource(win, {
+  channel: "todos",
+  getKey: (item) => item.id,
+});
+
+// Single operations
+ds.insert({ id: 1, text: "Buy milk", done: false });
+ds.update({ id: 1, text: "Buy milk", done: true });
+ds.delete({ id: 1 });
+
+// Batch multiple operations in a single message
+ds.batch((b) => {
+  b.insert({ id: 1, text: "Buy milk", done: false });
+  b.insert({ id: 2, text: "Walk dog", done: false });
+  b.update({ id: 1, text: "Buy milk", done: true });
+});
+
+// Send a full snapshot (replaces all data)
+ds.sync([
+  { id: 1, text: "Buy milk", done: true },
+  { id: 2, text: "Walk dog", done: false },
+]);
+```
+
+## Webview side (TanStack DB collection)
+
+Use `nativeWindowCollectionOptions` with TanStack DB's `createCollection`:
+
+```ts
+import { createCollection } from "@tanstack/db";
+import { nativeWindowCollectionOptions } from "@nativewindow/tsdb/client";
+
+const todos = createCollection(
+  nativeWindowCollectionOptions({
+    id: "todos",
+    channel: "todos",
+    getKey: (item) => item.id,
+  }),
+);
+```
+
+Works with `useLiveQuery` from `@tanstack/react-db`:
+
+```tsx
+import { useLiveQuery } from "@tanstack/react-db";
+
+function TodoList() {
+  const todos = useLiveQuery((q) => q.from({ todos }).many());
+
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Wire Protocol
+
+Operations use a single-letter discriminated union over the `{ $ch, p }` IPC envelope:
+
+| Type     | `t`   | Payload                     |
+| -------- | ----- | --------------------------- |
+| Insert   | `"i"` | `{ t: "i", k: TKey, d: T }` |
+| Update   | `"u"` | `{ t: "u", k: TKey, d: T }` |
+| Delete   | `"d"` | `{ t: "d", k: TKey }`       |
+| Snapshot | `"s"` | `{ t: "s", d: T[] }`        |
+| Batch    | `"b"` | `{ t: "b", o: SyncOp[] }`   |
+
+## Documentation
+
+Full documentation at [nativewindow.fcannizzaro.com](https://nativewindow.fcannizzaro.com)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Options for {@link nativeWindowCollectionOptions}.
+ *
+ * @example
+ * ```ts
+ * import { createCollection } from "@tanstack/db";
+ * import { nativeWindowCollectionOptions } from "@nativewindow/tsdb/client";
+ *
+ * const todos = createCollection(
+ *   nativeWindowCollectionOptions<Todo, string>({
+ *     id: "todos",
+ *     channel: "tsdb:todos",
+ *     getKey: (todo) => todo.id,
+ *   }),
+ * );
+ * ```
+ */
+export interface NativeWindowCollectionConfig<T extends object, TKey extends string | number> {
+    /** Collection ID for TanStack DB. */
+    id: string;
+    /**
+     * IPC channel name. Must match the `channel` passed to
+     * `createDataSource` on the host side.
+     */
+    channel: string;
+    /** Extract the primary key from an item. */
+    getKey: (item: T) => TKey;
+}
+/**
+ * Sync parameters provided by TanStack DB's `createCollection`.
+ * Declared locally to avoid a runtime dependency on `@tanstack/db`.
+ * @internal
+ */
+interface SyncParams<T extends object, TKey extends string | number> {
+    collection: unknown;
+    begin: (options?: {
+        immediate?: boolean;
+    }) => void;
+    write: (message: {
+        value: T;
+        type: "insert" | "update" | "delete";
+        previousValue?: T;
+        metadata?: Record<string, unknown>;
+    } | {
+        key: TKey;
+        type: "delete";
+    }) => void;
+    commit: () => void;
+    markReady: () => void;
+    truncate: () => void;
+}
+/**
+ * Return type of {@link nativeWindowCollectionOptions}.
+ * Structurally compatible with `CollectionConfig` from `@tanstack/db`.
+ */
+export interface NativeWindowCollectionResult<T extends object, TKey extends string | number> {
+    id: string;
+    getKey: (item: T) => TKey;
+    sync: {
+        sync: (params: SyncParams<T, TKey>) => () => void;
+    };
+}
+/**
+ * Create TanStack DB collection options that sync data from a
+ * native-window host process via IPC.
+ *
+ * The returned config is **read-only** — no `onInsert`/`onUpdate`/
+ * `onDelete` handlers. Data flows host to webview only.
+ *
+ * The sync function prefers `window.__native_message_listeners__`
+ * (the external listener registry exposed by `createChannelClient`)
+ * when available. This avoids the frozen-property crash caused by
+ * assigning to the read-only `window.__native_message__`. When the
+ * IPC client is not present, it falls back to direct interposition
+ * of `window.__native_message__` with a try/catch guard.
+ *
+ * @param config - Collection and channel configuration.
+ * @returns An object compatible with `createCollection()` from `@tanstack/db`.
+ *
+ * @example
+ * ```ts
+ * import { createCollection } from "@tanstack/db";
+ * import { useLiveQuery } from "@tanstack/react-db";
+ * import { nativeWindowCollectionOptions } from "@nativewindow/tsdb/client";
+ *
+ * type Todo = { id: string; text: string; done: boolean };
+ *
+ * const todoCollection = createCollection(
+ *   nativeWindowCollectionOptions<Todo, string>({
+ *     id: "todos",
+ *     channel: "tsdb:todos",
+ *     getKey: (todo) => todo.id,
+ *   }),
+ * );
+ *
+ * function TodoList() {
+ *   const { data: todos } = useLiveQuery((q) =>
+ *     q.from({ todos: todoCollection }),
+ *   );
+ *   return (
+ *     <ul>
+ *       {todos.map((todo) => (
+ *         <li key={todo.id}>{todo.text}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function nativeWindowCollectionOptions<T extends object, TKey extends string | number = string>(config: NativeWindowCollectionConfig<T, TKey>): NativeWindowCollectionResult<T, TKey>;
+export {};

package/dist/client.js

@@ -0,0 +1,113 @@
+function isEnvelope(data) {
+  return typeof data === "object" && data !== null && "$ch" in data && typeof data.$ch === "string";
+}
+function nativeWindowCollectionOptions(config) {
+  const { id, channel, getKey } = config;
+  return {
+    id,
+    getKey,
+    sync: {
+      sync: (params) => {
+        const { begin, write, commit, markReady } = params;
+        function processPayload(payload) {
+          switch (payload.t) {
+            case "i":
+              begin();
+              write({ type: "insert", value: payload.v });
+              commit();
+              break;
+            case "u":
+              begin();
+              write({ type: "update", value: payload.v });
+              commit();
+              break;
+            case "d":
+              begin();
+              write({ key: payload.k, type: "delete" });
+              commit();
+              break;
+            case "s":
+              begin();
+              for (const item of payload.items) {
+                write({ type: "insert", value: item.v });
+              }
+              commit();
+              markReady();
+              break;
+            case "b":
+              begin();
+              for (const op of payload.ops) {
+                switch (op.t) {
+                  case "i":
+                    write({ type: "insert", value: op.v });
+                    break;
+                  case "u":
+                    write({ type: "update", value: op.v });
+                    break;
+                  case "d":
+                    write({ key: op.k, type: "delete" });
+                    break;
+                }
+              }
+              commit();
+              break;
+          }
+        }
+        function handler(msg) {
+          let parsed;
+          try {
+            parsed = JSON.parse(msg);
+          } catch {
+            return;
+          }
+          if (!isEnvelope(parsed) || parsed.$ch !== channel) return;
+          const payload = parsed.p;
+          if (!payload || typeof payload.t !== "string") return;
+          processPayload(payload);
+        }
+        const registry = window.__native_message_listeners__;
+        if (registry && typeof registry.add === "function") {
+          registry.add(handler);
+          return () => {
+            registry.remove(handler);
+          };
+        }
+        const prev = window.__native_message__;
+        function fallbackHandler(msg) {
+          let parsed;
+          try {
+            parsed = JSON.parse(msg);
+          } catch {
+            prev?.(msg);
+            return;
+          }
+          if (!isEnvelope(parsed) || parsed.$ch !== channel) {
+            prev?.(msg);
+            return;
+          }
+          const payload = parsed.p;
+          if (!payload || typeof payload.t !== "string") {
+            prev?.(msg);
+            return;
+          }
+          processPayload(payload);
+        }
+        try {
+          window.__native_message__ = fallbackHandler;
+        } catch {
+        }
+        return () => {
+          try {
+            if (window.__native_message__ === fallbackHandler) {
+              window.__native_message__ = prev;
+            }
+          } catch {
+          }
+        };
+      }
+    }
+  };
+}
+export {
+  nativeWindowCollectionOptions
+};

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Minimal interface for sending messages to the webview.
+ * Satisfied by {@link NativeWindow} without importing it directly.
+ *
+ * @example
+ * ```ts
+ * const win = new NativeWindow();
+ * // win satisfies MessageSender
+ * ```
+ */
+export interface MessageSender {
+    postMessage(message: string): void;
+}
+/**
+ * Options for {@link createDataSource}.
+ *
+ * @example
+ * ```ts
+ * const ds = createDataSource<Todo, string>(win, {
+ *   channel: "tsdb:todos",
+ *   getKey: (todo) => todo.id,
+ * });
+ * ```
+ */
+export interface DataSourceOptions<T extends object, TKey extends string | number> {
+    /**
+     * IPC channel name for this data source.
+     * Must match the `channel` passed to `nativeWindowCollectionOptions`
+     * on the webview side.
+     */
+    channel: string;
+    /** Extract the primary key from an item. */
+    getKey: (item: T) => TKey;
+}
+/**
+ * Builder for batched operations passed to {@link DataSource.batch}.
+ *
+ * @example
+ * ```ts
+ * ds.batch((b) => {
+ *   b.insert({ id: "1", text: "A", done: false });
+ *   b.insert({ id: "2", text: "B", done: false });
+ *   b.delete("3");
+ * });
+ * ```
+ */
+export interface BatchBuilder<T extends object, TKey extends string | number> {
+    /** Queue an insert operation. */
+    insert(item: T): void;
+    /** Queue a full-item update operation. */
+    update(key: TKey, item: T): void;
+    /** Queue a delete operation. */
+    delete(key: TKey): void;
+}
+/**
+ * A host-side data source that pushes mutations to the webview
+ * via native-window IPC. Data flows host to webview only.
+ *
+ * Each mutation updates an internal item map *and* sends an IPC
+ * message so the webview collection stays in sync.
+ *
+ * @example
+ * ```ts
+ * const ds = createDataSource<Todo, string>(win, {
+ *   channel: "tsdb:todos",
+ *   getKey: (todo) => todo.id,
+ * });
+ *
+ * ds.insert({ id: "1", text: "Buy milk", done: false });
+ * ds.update("1", { id: "1", text: "Buy oat milk", done: false });
+ * ds.delete("1");
+ * ```
+ */
+export interface DataSource<T extends object, TKey extends string | number> {
+    /** Send an insert to the webview and track the item internally. */
+    insert(item: T): void;
+    /** Send a full-item update to the webview and update internal state. */
+    update(key: TKey, item: T): void;
+    /** Send a delete to the webview and remove the item internally. */
+    delete(key: TKey): void;
+    /**
+     * Execute multiple operations as a single IPC message.
+     * The webview applies them atomically within one begin/commit cycle.
+     *
+     * @example
+     * ```ts
+     * ds.batch((b) => {
+     *   b.insert({ id: "1", text: "A", done: false });
+     *   b.insert({ id: "2", text: "B", done: false });
+     *   b.delete("3");
+     * });
+     * ```
+     */
+    batch(fn: (builder: BatchBuilder<T, TKey>) => void): void;
+    /**
+     * Send the current internal state as a full snapshot to the webview.
+     * If `items` is provided, replaces the internal state first.
+     *
+     * Call this after page load to initialize or re-initialize the
+     * webview collection (e.g. from an `onPageLoad` handler).
+     *
+     * @example
+     * ```ts
+     * // Send current state
+     * ds.sync();
+     *
+     * // Replace internal state and send
+     * ds.sync([
+     *   { id: "1", text: "A", done: false },
+     *   { id: "2", text: "B", done: true },
+     * ]);
+     * ```
+     */
+    sync(items?: T[]): void;
+}
+/**
+ * Create a host-side data source that pushes mutations to the
+ * webview via native-window IPC.
+ *
+ * The data source maintains an internal `Map` of all items so it
+ * can send full snapshots on demand (e.g. after a page reload).
+ * Individual mutations (`insert`, `update`, `delete`) update the
+ * map *and* send an incremental IPC message.
+ *
+ * @param sender - Any object with a `postMessage` method (e.g. a `NativeWindow`).
+ * @param options - Data source configuration.
+ * @returns A {@link DataSource} with imperative push methods.
+ *
+ * @example
+ * ```ts
+ * import { NativeWindow } from "@nativewindow/webview";
+ * import { createDataSource } from "@nativewindow/tsdb";
+ *
+ * const win = new NativeWindow({ title: "My App" });
+ * win.loadUrl("http://localhost:5173");
+ *
+ * const todos = createDataSource<Todo, string>(win, {
+ *   channel: "tsdb:todos",
+ *   getKey: (todo) => todo.id,
+ * });
+ *
+ * todos.insert({ id: "1", text: "Hello", done: false });
+ *
+ * // Re-send full state after page load
+ * win.onPageLoad((event) => {
+ *   if (event === "finished") todos.sync();
+ * });
+ * ```
+ */
+export declare function createDataSource<T extends object, TKey extends string | number = string>(sender: MessageSender, options: DataSourceOptions<T, TKey>): DataSource<T, TKey>;

package/dist/index.js

@@ -0,0 +1,59 @@
+function createDataSource(sender, options) {
+  const { channel, getKey } = options;
+  const items = /* @__PURE__ */ new Map();
+  function send(payload) {
+    sender.postMessage(JSON.stringify({ $ch: channel, p: payload }));
+  }
+  function sendSnapshot() {
+    const entries = [];
+    items.forEach((v, k) => entries.push({ k, v }));
+    send({ t: "s", items: entries });
+  }
+  return {
+    insert(item) {
+      const key = getKey(item);
+      items.set(key, item);
+      send({ t: "i", k: key, v: item });
+    },
+    update(key, item) {
+      items.set(key, item);
+      send({ t: "u", k: key, v: item });
+    },
+    delete(key) {
+      items.delete(key);
+      send({ t: "d", k: key });
+    },
+    batch(fn) {
+      const ops = [];
+      const builder = {
+        insert(item) {
+          const key = getKey(item);
+          items.set(key, item);
+          ops.push({ t: "i", k: key, v: item });
+        },
+        update(key, item) {
+          items.set(key, item);
+          ops.push({ t: "u", k: key, v: item });
+        },
+        delete(key) {
+          items.delete(key);
+          ops.push({ t: "d", k: key });
+        }
+      };
+      fn(builder);
+      if (ops.length > 0) send({ t: "b", ops });
+    },
+    sync(newItems) {
+      if (newItems !== void 0) {
+        items.clear();
+        for (const item of newItems) {
+          items.set(getKey(item), item);
+        }
+      }
+      sendSnapshot();
+    }
+  };
+}
+export {
+  createDataSource
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nativewindow/tsdb",
+  "version": "0.1.1",
+  "description": "TanStack DB collection adapter for native-window IPC (alpha)",
+  "homepage": "https://nativewindow.fcannizzaro.com",
+  "bugs": {
+    "url": "https://github.com/nativewindow/webview/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Francesco Saverio Cannizzaro (fcannizzaro)",
+    "url": "https://fcannizzaro.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nativewindow/webview/tree/main/packages/tsdb"
+  },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/fcannizzaro"
+    }
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@nativewindow/webview": "workspace:*",
+    "typescript": "^5"
+  }
+}