@tangentfeed/react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+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,12 @@
+# @tangentfeed/react
+
+React hooks for tangentfeed.
+
+```tsx
+const db = useSpace({ space: "kitchen-42", transports: [broadcast()] });
+const { rows } = useRows(db, "tasks");
+```
+
+Hooks: `useSpace`, `useRows`, `useRow`, `usePeers`, `useTable`.
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { SyncedSpace, OpenSpaceOptions } from 'tangentfeed';
+import { RowData, Json } from '@tangentfeed/core';
+import { SchemaShape, TableName, RowOf, InsertInput, UpdateInput } from '@tangentfeed/schema';
+
+/**
+ * React bindings for tangentfeed.
+ *
+ * The engine is push-based (subscribe fires after every committed batch), so
+ * these hooks are thin: they re-read the affected slice and re-render. Reads
+ * are local and fast, but they are async, so each hook exposes a `loading`
+ * flag for the first paint.
+ *
+ *   const db = useSpace({ space: "kitchen-42", transports: [broadcast()] });
+ *   const { rows } = useRows(db, "tasks");
+ */
+
+/**
+ * Each hook is generic over the schema so a typed space keeps its types
+ * through the binding. With no schema these collapse to the untyped forms the
+ * hooks had before, so existing components are unaffected.
+ */
+type Schema = SchemaShape | undefined;
+/** Table names accepted for a given schema. */
+type TableArg<S extends Schema> = S extends SchemaShape ? TableName<S> : string;
+/** A read row for a given schema and table. */
+type RowType<S extends Schema, T> = S extends SchemaShape ? T extends keyof S ? RowOf<S, T> : never : RowData;
+type InsertArg<S extends Schema, T> = S extends SchemaShape ? T extends keyof S ? InsertInput<S, T> : never : Record<string, Json>;
+type UpdateArg<S extends Schema, T> = S extends SchemaShape ? T extends keyof S ? UpdateInput<S, T> : never : Record<string, Json>;
+/**
+ * Open a space for the lifetime of the component. Returns null until ready.
+ *
+ * The options object is captured on first render; changing `space` opens a new
+ * database and closes the old one, other fields are ignored after mount (they
+ * describe how to connect, not what to display).
+ */
+declare function useSpace<S extends Schema = undefined>(opts: OpenSpaceOptions<S>): SyncedSpace<S> | null;
+/** Live view of every visible row in a table, sorted by rowId. */
+declare function useRows<S extends Schema = undefined, T extends TableArg<S> = TableArg<S>>(db: SyncedSpace<S> | null, table: T): {
+    rows: RowType<S, T>[];
+    loading: boolean;
+};
+/** Live view of one row. `row` is undefined when absent or deleted. */
+declare function useRow<S extends Schema = undefined, T extends TableArg<S> = TableArg<S>>(db: SyncedSpace<S> | null, table: T, rowId: string | null | undefined): {
+    row: RowType<S, T> | undefined;
+    loading: boolean;
+};
+/**
+ * Currently reachable peers. Polled, because transports report connection
+ * state through their own callbacks rather than the engine's change stream.
+ */
+declare function usePeers<S extends Schema = undefined>(db: SyncedSpace<S> | null, intervalMs?: number): string[];
+/** Stable mutation helpers bound to a table. */
+declare function useTable<S extends Schema = undefined, T extends TableArg<S> = TableArg<S>>(db: SyncedSpace<S> | null, table: T): {
+    insert: (values: InsertArg<S, T>) => Promise<string>;
+    update: (row: string, values: UpdateArg<S, T>) => Promise<void>;
+    remove: (row: string) => Promise<void>;
+};
+
+export { usePeers, useRow, useRows, useSpace, useTable };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/index.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  openSpace
+} from "tangentfeed";
+function useSpace(opts) {
+  const [db, setDb] = useState(null);
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+  useEffect(() => {
+    let cancelled = false;
+    let opened = null;
+    const open = openSpace;
+    void open(optsRef.current).then((space) => {
+      if (cancelled) {
+        void space.close();
+        return;
+      }
+      opened = space;
+      setDb(space);
+    });
+    return () => {
+      cancelled = true;
+      setDb(null);
+      void opened?.close();
+    };
+  }, [opts.space]);
+  return db;
+}
+function useRows(db, table) {
+  const [rows, setRows] = useState([]);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    if (!db) {
+      setRows([]);
+      setLoading(true);
+      return;
+    }
+    let live = true;
+    const plain = db;
+    const refresh = async () => {
+      const next = await plain.list(table);
+      if (live) {
+        setRows(next);
+        setLoading(false);
+      }
+    };
+    void refresh();
+    const unsub = plain.subscribe((ev) => {
+      if (ev.changes.some((c) => c.table === table)) void refresh();
+    });
+    return () => {
+      live = false;
+      unsub();
+    };
+  }, [db, table]);
+  return { rows, loading };
+}
+function useRow(db, table, rowId) {
+  const [row, setRow] = useState(void 0);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    if (!db || !rowId) {
+      setRow(void 0);
+      setLoading(!!rowId);
+      return;
+    }
+    let live = true;
+    const plain = db;
+    const refresh = async () => {
+      const next = await plain.get(table, rowId);
+      if (live) {
+        setRow(next);
+        setLoading(false);
+      }
+    };
+    void refresh();
+    const unsub = plain.subscribe((ev) => {
+      if (ev.changes.some((c) => c.table === table && c.row === rowId)) void refresh();
+    });
+    return () => {
+      live = false;
+      unsub();
+    };
+  }, [db, table, rowId]);
+  return { row, loading };
+}
+function usePeers(db, intervalMs = 1e3) {
+  const [peers, setPeers] = useState([]);
+  useEffect(() => {
+    if (!db) {
+      setPeers([]);
+      return;
+    }
+    const tick = () => setPeers(db.peers());
+    tick();
+    const timer = setInterval(tick, intervalMs);
+    return () => clearInterval(timer);
+  }, [db, intervalMs]);
+  return peers;
+}
+function useTable(db, table) {
+  const insert = useCallback(
+    (values) => {
+      if (!db) throw new Error("space not ready");
+      return db.insert(table, values);
+    },
+    [db, table]
+  );
+  const update = useCallback(
+    (row, values) => {
+      if (!db) throw new Error("space not ready");
+      return db.update(table, row, values);
+    },
+    [db, table]
+  );
+  const remove = useCallback(
+    (row) => {
+      if (!db) throw new Error("space not ready");
+      return db.delete(table, row);
+    },
+    [db, table]
+  );
+  return useMemo(() => ({ insert, update, remove }), [insert, update, remove]);
+}
+export {
+  usePeers,
+  useRow,
+  useRows,
+  useSpace,
+  useTable
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tangentfeed/react",
+  "version": "0.2.0",
+  "description": "React hooks for tangentfeed",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "build": "tsup src/index.ts --format esm --dts --clean --external react",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@tangentfeed/core": "0.2.0",
+    "@tangentfeed/schema": "0.2.0",
+    "tangentfeed": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/react"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}