tangentfeed 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,14 @@
+# tangentfeed
+
+Batteries-included entry point.
+
+```ts
+import { openSpace, broadcast } from "tangentfeed";
+
+const db = await openSpace({ space: "kitchen-42", transports: [broadcast()] });
+await db.insert("tasks", { title: "Buy oat milk", done: false });
+```
+
+See the [project README](https://github.com/sreerajta/tangentfeed) for the full guide.
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { StorageAdapter, Transport, SyncEngine, Json, RowData, ChangeEvent, Frontier } from '@tangentfeed/core';
+export { ChangeEvent, Frontier, Json, MemoryAdapter, Op, Replicator, RowData, StorageAdapter, SyncEngine, Transport } from '@tangentfeed/core';
+import { ManualPairState, ManualPairTransport, SignalingState } from '@tangentfeed/transport-webrtc';
+export { ManualPairState, ManualPairTransport, SignalingState, WebRTCTransport } from '@tangentfeed/transport-webrtc';
+import { SchemaShape, TableName, InsertInput, UpdateInput, RowOf } from '@tangentfeed/schema';
+export { IdbAdapter } from '@tangentfeed/adapter-idb';
+export { SpaceCipher } from '@tangentfeed/crypto';
+export { BroadcastTransport } from '@tangentfeed/transport-broadcast';
+
+/**
+ * tangentfeed — offline-first, peer-to-peer data sync.
+ *
+ * This package is the batteries-included entry point. It assembles the pieces
+ * (engine, storage adapter, transports, optional encryption) that the
+ * @tangentfeed/* packages provide individually, so the common case is one call:
+ *
+ *   const db = await openSpace({
+ *     space: "kitchen-42",
+ *     transports: [broadcast(), webrtc({ signaling: "wss://…" })],
+ *     encryption: { passphrase: "correct horse battery staple" },
+ *   });
+ *
+ *   await db.insert("tasks", { title: "Buy oat milk", done: false });
+ *   db.subscribe(() => render(db.list("tasks")));
+ *
+ * Everything remains available à la carte: import from @tangentfeed/core to build
+ * against the protocol directly with your own storage or transport.
+ */
+
+type TransportFactory = (ctx: {
+    space: string;
+    deviceId: string;
+}) => Transport | Promise<Transport>;
+interface OpenSpaceOptions<S extends SchemaShape | undefined = undefined> {
+    /** Logical database name; peers only sync within the same space. */
+    space: string;
+    /**
+     * "indexeddb" (default in browsers), "memory", or any StorageAdapter.
+     *
+     * For SQLite, construct the adapter yourself and pass it here — the driver
+     * (better-sqlite3, node:sqlite, bun:sqlite) is your choice, and keeping it
+     * out of this package means browsers never bundle a native dependency:
+     *
+     *   import { SqliteAdapter, betterSqliteDriver } from "@tangentfeed/adapter-sqlite";
+     *   import Database from "better-sqlite3";
+     *
+     *   const db = await openSpace({
+     *     space: "kitchen-42",
+     *     storage: SqliteAdapter.open(betterSqliteDriver(new Database("data.db"))),
+     *   });
+     */
+    storage?: "indexeddb" | "memory" | StorageAdapter;
+    /**
+     * Names the local database when several replicas share one origin — two
+     * browser tabs syncing with each other, for instance.
+     *
+     * This is not an identity. Identity is a keypair held inside the database
+     * (§4.3); this only decides which database to open. Callers that supply
+     * their own storage adapter never need it.
+     */
+    replica?: string;
+    /** Zero or more transports. Omit for a purely local database. */
+    transports?: TransportFactory[];
+    /** End-to-end encryption. Every peer in the space needs the same secret. */
+    encryption?: {
+        passphrase: string;
+    } | {
+        secret: Uint8Array;
+    };
+    /** Surface protocol-level problems (clock drift, bad ops, transport errors). */
+    onError?: (err: unknown, ctx: {
+        peer?: string;
+    }) => void;
+    /**
+     * Optional typed schema. Supplying one types the data methods and validates
+     * local writes; it never inspects data arriving from peers, so a peer on a
+     * different schema still syncs completely.
+     */
+    schema?: S;
+}
+interface SyncedSpace<S extends SchemaShape | undefined = undefined> {
+    readonly space: string;
+    readonly deviceId: string;
+    /** Underlying engine, for protocol-level work. */
+    readonly engine: SyncEngine;
+    insert: S extends SchemaShape ? <T extends TableName<S>>(table: T, values: InsertInput<S, T>) => Promise<string> : (table: string, values: Record<string, Json>) => Promise<string>;
+    update: S extends SchemaShape ? <T extends TableName<S>>(table: T, row: string, values: UpdateInput<S, T>) => Promise<void> : (table: string, row: string, values: Record<string, Json>) => Promise<void>;
+    delete: S extends SchemaShape ? (table: TableName<S>, row: string) => Promise<void> : (table: string, row: string) => Promise<void>;
+    get: S extends SchemaShape ? <T extends TableName<S>>(table: T, row: string) => Promise<RowOf<S, T> | undefined> : (table: string, row: string) => Promise<RowData | undefined>;
+    list: S extends SchemaShape ? <T extends TableName<S>>(table: T) => Promise<RowOf<S, T>[]> : (table: string) => Promise<RowData[]>;
+    /** Called after every committed change, local or remote. */
+    subscribe(cb: (event: ChangeEvent) => void): () => void;
+    /** deviceIds currently reachable across all transports. */
+    peers(): string[];
+    frontier(): Promise<Frontier>;
+    /** Reclaim superseded ops. See PROTOCOL.md §9. */
+    compact(opts?: {
+        includeTombstones?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        removed: number;
+        rowsReclaimed: number;
+        blockedBy: string[];
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * Overloads, not one generic signature, so the no-schema call keeps exactly
+ * the types it had before this layer existed.
+ *
+ * Order is load-bearing: `Parameters<typeof openSpace>` resolves against the
+ * LAST overload, and existing code uses that utility type to describe options.
+ * A single generic signature resolves S to its constraint there, which widens
+ * the return to SyncedSpace<SchemaShape | undefined> and breaks assignment to
+ * SyncedSpace.
+ */
+declare function openSpace<S extends SchemaShape>(opts: OpenSpaceOptions<S> & {
+    schema: S;
+}): Promise<SyncedSpace<S>>;
+declare function openSpace(opts: OpenSpaceOptions<undefined>): Promise<SyncedSpace<undefined>>;
+/** Same-device sync between tabs and workers. No infrastructure. */
+declare function broadcast(): TransportFactory;
+/** Cross-device sync over WebRTC, brokered by a signaling server. */
+declare function webrtc(opts: {
+    signaling: string;
+    iceServers?: RTCIceServer[];
+    onSignalingState?: (state: SignalingState) => void;
+    onError?: (err: unknown, ctx: {
+        peer?: string;
+    }) => void;
+}): TransportFactory;
+/**
+ * Serverless pairing: the two devices exchange offer/answer blobs by QR code
+ * or copy-paste. Create the transport yourself so you can drive the handshake,
+ * then hand it to openSpace via `existing()`.
+ */
+declare function manualPair(opts: {
+    deviceId: string;
+    iceServers?: RTCIceServer[];
+    onState?: (state: ManualPairState) => void;
+}): ManualPairTransport;
+/** Wrap an already-constructed transport (e.g. a paired ManualPairTransport). */
+declare function existing(transport: Transport): TransportFactory;
+
+export { type OpenSpaceOptions, type SyncedSpace, type TransportFactory, broadcast, existing, manualPair, openSpace, webrtc };

package/dist/index.js

@@ -0,0 +1,156 @@
+// src/index.ts
+import {
+  Replicator,
+  SyncEngine
+} from "@tangentfeed/core";
+import { IdbAdapter } from "@tangentfeed/adapter-idb";
+import { MemoryAdapter } from "@tangentfeed/core";
+import { SpaceCipher } from "@tangentfeed/crypto";
+import { BroadcastTransport } from "@tangentfeed/transport-broadcast";
+import {
+  ManualPairTransport,
+  WebRTCTransport
+} from "@tangentfeed/transport-webrtc";
+import {
+  validateInsert,
+  validateUpdate
+} from "@tangentfeed/schema";
+import {
+  SyncEngine as SyncEngine2,
+  Replicator as Replicator2,
+  MemoryAdapter as MemoryAdapter2
+} from "@tangentfeed/core";
+import { IdbAdapter as IdbAdapter2 } from "@tangentfeed/adapter-idb";
+import { SpaceCipher as SpaceCipher2 } from "@tangentfeed/crypto";
+import { BroadcastTransport as BroadcastTransport2 } from "@tangentfeed/transport-broadcast";
+import {
+  WebRTCTransport as WebRTCTransport2,
+  ManualPairTransport as ManualPairTransport2
+} from "@tangentfeed/transport-webrtc";
+async function openSpace(opts) {
+  const space = opts.space;
+  const storage = await resolveStorage(opts.storage, space, opts.replica ?? "default");
+  const cipher = await resolveCipher(opts.encryption, space);
+  const engine = await SyncEngine.open({
+    storage,
+    ...cipher ? { cipher } : {}
+  });
+  const transports = [];
+  const replicators = [];
+  for (const make of opts.transports ?? []) {
+    const transport = await make({ space, deviceId: engine.deviceId });
+    transports.push(transport);
+    const replicator = new Replicator({
+      engine,
+      transport,
+      space,
+      events: {
+        onError: (err, ctx) => opts.onError?.(err, ctx.from ? { peer: ctx.from } : {})
+      }
+    });
+    replicators.push(replicator);
+    await replicator.start();
+  }
+  return {
+    space,
+    deviceId: engine.deviceId,
+    engine,
+    // `async` is load-bearing: validation throws synchronously, and these
+    // methods are declared to return a Promise. Without it a SchemaError would
+    // escape past `.catch()` and reject-style handling.
+    insert: (async (table, values) => engine.insert(
+      table,
+      opts.schema ? validateInsert(opts.schema, table, values) : values
+    )),
+    update: (async (table, row, values) => engine.update(
+      table,
+      row,
+      opts.schema ? validateUpdate(opts.schema, table, values) : values
+    )),
+    // The read casts are where "asserted, not proven" lives: the engine still
+    // returns RowData and the schema layer relabels it without checking. That
+    // is deliberate — see parseRow for the opt-in check.
+    delete: ((t, r) => engine.delete(t, r)),
+    get: ((t, r) => engine.get(t, r)),
+    list: ((t) => engine.list(t)),
+    subscribe: (cb) => engine.subscribe(cb),
+    peers: () => {
+      const ids = /* @__PURE__ */ new Set();
+      for (const r of replicators) for (const id of r.peerIds) ids.add(id);
+      for (const t of transports) {
+        const connected = t.connectedPeers;
+        for (const id of connected ?? []) ids.add(id);
+      }
+      return [...ids];
+    },
+    frontier: () => engine.frontier(),
+    compact: async (o = {}) => {
+      const stats = await engine.compact(o);
+      return {
+        removed: stats.removed,
+        rowsReclaimed: stats.rowsReclaimed,
+        blockedBy: stats.blockedBy
+      };
+    },
+    close: async () => {
+      for (const r of replicators) r.stop();
+      for (const t of transports) t.close();
+      storage.close?.();
+    }
+  };
+}
+function broadcast() {
+  return ({ space }) => new BroadcastTransport(space);
+}
+function webrtc(opts) {
+  return ({ space, deviceId }) => new WebRTCTransport({
+    space,
+    deviceId,
+    signalingUrl: opts.signaling,
+    ...opts.iceServers ? { rtcConfig: { iceServers: opts.iceServers } } : {},
+    ...opts.onSignalingState ? { onSignalingState: opts.onSignalingState } : {},
+    ...opts.onError ? { onError: opts.onError } : {}
+  });
+}
+function manualPair(opts) {
+  return new ManualPairTransport({
+    deviceId: opts.deviceId,
+    ...opts.iceServers ? { rtcConfig: { iceServers: opts.iceServers } } : {},
+    ...opts.onState ? { onState: opts.onState } : {}
+  });
+}
+function existing(transport) {
+  return () => transport;
+}
+async function resolveStorage(storage, space, replica) {
+  if (storage && typeof storage !== "string") return storage;
+  if (storage === "memory") return new MemoryAdapter();
+  if (storage === "indexeddb" || storage === void 0) {
+    if (globalThis.indexedDB) return IdbAdapter.open(`${space}:${replica}`);
+    if (storage === "indexeddb") {
+      throw new Error("IndexedDB is not available in this environment");
+    }
+    return new MemoryAdapter();
+  }
+  throw new Error(`unknown storage option: ${String(storage)}`);
+}
+async function resolveCipher(enc, space) {
+  if (!enc) return void 0;
+  if ("passphrase" in enc) return SpaceCipher.fromPassphrase(enc.passphrase, space);
+  return new SpaceCipher(enc.secret);
+}
+export {
+  BroadcastTransport2 as BroadcastTransport,
+  IdbAdapter2 as IdbAdapter,
+  ManualPairTransport2 as ManualPairTransport,
+  MemoryAdapter2 as MemoryAdapter,
+  Replicator2 as Replicator,
+  SpaceCipher2 as SpaceCipher,
+  SyncEngine2 as SyncEngine,
+  WebRTCTransport2 as WebRTCTransport,
+  broadcast,
+  existing,
+  manualPair,
+  openSpace,
+  webrtc
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tangentfeed",
+  "version": "0.2.0",
+  "description": "Offline-first, peer-to-peer data sync. Any storage, any transport, any language.",
+  "license": "MIT",
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "offline-first",
+    "sync",
+    "crdt",
+    "p2p",
+    "webrtc",
+    "local-first",
+    "indexeddb"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tangentfeed/core": "0.2.0",
+    "@tangentfeed/adapter-idb": "0.2.0",
+    "@tangentfeed/crypto": "0.2.0",
+    "@tangentfeed/schema": "0.2.0",
+    "@tangentfeed/transport-broadcast": "0.2.0",
+    "@tangentfeed/transport-webrtc": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/tangentfeed"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}