@noy-db/by-peer 0.1.0-pre.3

package/dist/index.d.cts

@@ -0,0 +1,236 @@
+import { NoydbStore } from '@noy-db/hub';
+
+/**
+ * `PeerChannel` — the minimal duplex message primitive used by the p2p
+ * NoydbStore wrapper. Any transport that can deliver UTF-8 strings
+ * reliably and in-order qualifies: WebRTC DataChannel, BroadcastChannel,
+ * MessagePort, WebSocket, even postMessage pairs.
+ *
+ * Keeping the transport abstract has three payoffs:
+ *
+ *   1. **Tests run without a WebRTC polyfill.** `pairInMemory()` returns
+ *      two wired channels for conformance tests against `to-memory`.
+ *   2. **Consumers pick their signaling story.** Matrix rooms, QR codes,
+ *      pastebin, Firebase Realtime DB — the handshake is out of scope.
+ *   3. **Future transports slot in cheaply.** WebTransport (HTTP/3),
+ *      libp2p, Iroh, or a plain relay WebSocket become additional
+ *      bindings without touching the RPC layer.
+ *
+ * @module
+ */
+/**
+ * Minimal duplex message primitive.
+ *
+ * Implementations MUST deliver every `send` payload in order exactly
+ * once to every live `on('message')` subscriber. `close()` is best-effort
+ * — once called, further `send()` calls MAY throw and `on('close')` MUST
+ * fire once.
+ */
+interface PeerChannel {
+    /** Enqueue a payload for delivery to the remote end. */
+    send(payload: string): void;
+    /** Subscribe to incoming payloads or lifecycle events. Returns unsubscribe. */
+    on(event: 'message', listener: (payload: string) => void): () => void;
+    on(event: 'close', listener: () => void): () => void;
+    /** Close the channel. Idempotent. */
+    close(): void;
+    /** True once the channel is ready for `send`. */
+    readonly isOpen: boolean;
+}
+/**
+ * Create a pair of in-memory `PeerChannel`s wired to each other.
+ * Intended for tests and multi-tab simulations inside a single process.
+ */
+declare function pairInMemory(): [PeerChannel, PeerChannel];
+/**
+ * Wrap a WebRTC `RTCDataChannel` as a `PeerChannel`.
+ *
+ * Browser-only — the caller is responsible for establishing the
+ * `RTCPeerConnection`, exchanging SDP offers/answers out of band, and
+ * passing the opened DataChannel here. When the remote peer is only
+ * reachable via TURN, the relay sees DTLS-wrapped ciphertext (noy-db
+ * already encrypts at rest, so even a TURN compromise leaks nothing).
+ */
+declare function fromDataChannel(dc: RTCDataChannel): PeerChannel;
+
+/**
+ * JSON-RPC protocol over a `PeerChannel`.
+ *
+ * Request shape:
+ *   `{ t: 'req', id, method, args }`
+ * Response shape (success):
+ *   `{ t: 'res', id, ok: true, result }`
+ * Response shape (error):
+ *   `{ t: 'res', id, ok: false, error: { name, message, version? } }`
+ *
+ * Why not reuse msgpack/protobuf? The payloads are already base64-encoded
+ * ciphertext — further binary packing saves ~8-12% at a large dependency
+ * cost. JSON over UTF-8 is inspectable, fits the zero-dependency ethos,
+ * and WebRTC DataChannel string mode already frames for us.
+ *
+ * @module
+ */
+
+/** Wire format discriminator for RPC messages. */
+type RpcMessage = RpcRequest | RpcResponse;
+interface RpcRequest {
+    readonly t: 'req';
+    readonly id: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+interface RpcResponse {
+    readonly t: 'res';
+    readonly id: string;
+    readonly ok: boolean;
+    readonly result?: unknown;
+    readonly error?: {
+        name: string;
+        message: string;
+        version?: number;
+    };
+}
+/** Handler invoked when an RPC request arrives. Return value is serialized as `result`. */
+type RpcHandler = (method: string, args: readonly unknown[]) => Promise<unknown>;
+/** Options for a client-side RPC caller. */
+interface RpcClientOptions {
+    /** Max milliseconds to wait for a response before rejecting. */
+    timeoutMs?: number;
+}
+/** Client: wrap a `PeerChannel` in a `call(method, args)` helper. */
+declare function createRpcClient(channel: PeerChannel, opts?: RpcClientOptions): {
+    call<T = unknown>(method: string, args: readonly unknown[]): Promise<T>;
+    dispose(): void;
+};
+/** Server: dispatch incoming RPC requests through a handler. Returns a dispose fn. */
+declare function serveRpc(channel: PeerChannel, handler: RpcHandler): () => void;
+
+/**
+ * `peerStore()` — a `NoydbStore` backed by RPC calls over a `PeerChannel`.
+ *
+ * The local peer calls `get`/`put`/`delete`/… against this store as if
+ * it were any other backend; every call is serialized as an RPC request
+ * to the remote peer, which runs `servePeerStore()` to funnel the RPCs
+ * into its own local `NoydbStore`.
+ *
+ * Error re-hydration: the remote handler re-throws `ConflictError` with
+ * a `.version` field when a CAS check fails. The RPC layer carries
+ * `version` in the error envelope so the local caller can catch
+ * `ConflictError` with the same semantics as a direct store call.
+ *
+ * @module
+ */
+
+interface PeerStoreOptions {
+    /** The duplex channel to the remote peer. */
+    readonly channel: PeerChannel;
+    /** Max ms to wait for any single RPC response. Default 30s. */
+    readonly timeoutMs?: number;
+    /** Optional display name used in diagnostics. Default `'by-peer'`. */
+    readonly name?: string;
+}
+/**
+ * Create a `NoydbStore` that forwards every operation to a remote peer
+ * over the supplied `PeerChannel`. The remote peer must be running
+ * `servePeerStore()` against its own local store.
+ */
+declare function peerStore(opts: PeerStoreOptions): NoydbStore & {
+    dispose: () => void;
+};
+
+/**
+ * `servePeerStore()` — runs on the peer that owns the data. Listens on
+ * a `PeerChannel` for RPC requests from a remote `peerStore()` client
+ * and executes each one against the local `NoydbStore`.
+ *
+ * The 6 core methods plus the optional `ping` / `listSince` / `listPage`
+ * extensions are exposed. Unknown methods surface as a remote Error.
+ *
+ * @module
+ */
+
+interface ServePeerStoreOptions {
+    /** The duplex channel from the remote peer. */
+    readonly channel: PeerChannel;
+    /** The local store to serve. */
+    readonly store: NoydbStore;
+    /**
+     * Optional method whitelist. When provided, any method not in the set
+     * is rejected with "method not allowed". Useful for read-only peers.
+     */
+    readonly allow?: ReadonlySet<string>;
+}
+/**
+ * Start serving the local store on the channel. Returns a dispose
+ * function that stops the RPC listener. The underlying channel is NOT
+ * closed by dispose — ownership stays with the caller.
+ */
+declare function servePeerStore(opts: ServePeerStoreOptions): () => void;
+
+/**
+ * WebRTC handshake helper — opinionated wrapper around
+ * `RTCPeerConnection` that produces a ready-to-use `PeerChannel`.
+ *
+ * The handshake is split into two halves so the caller can ferry the
+ * SDP blobs over whatever signaling channel they prefer (QR code,
+ * Matrix room, pastebin, Firebase, signed URL…). Signaling is
+ * intentionally out of scope — noy-db has no opinion on how peers
+ * discover each other, only on what flows once they do.
+ *
+ * ```ts
+ * // Peer A (initiator)
+ * const a = await createOffer({ iceServers })
+ * send(a.offer)                           // → signaling channel
+ * const answer = await receive()          // ← signaling channel
+ * await a.accept(answer)
+ * const channel = await a.channel         // ready PeerChannel
+ *
+ * // Peer B (responder)
+ * const offer = await receive()           // ← signaling channel
+ * const b = await acceptOffer(offer, { iceServers })
+ * send(b.answer)                          // → signaling channel
+ * const channel = await b.channel         // ready PeerChannel
+ * ```
+ *
+ * Browser-only. Node consumers who want to interconnect with browsers
+ * can plug `@roamhq/wrtc` into the global `RTCPeerConnection` slot; this
+ * module does not pull it in so the package has zero runtime deps.
+ *
+ * @module
+ */
+
+type PeerConnection = RTCPeerConnection;
+type SessionDescription = RTCSessionDescriptionInit;
+interface WebRTCOptions {
+    /** Optional ICE servers (STUN / TURN). */
+    readonly iceServers?: RTCIceServer[];
+    /** Label for the `RTCDataChannel`. Default `'noydb'`. */
+    readonly label?: string;
+}
+interface Initiator {
+    readonly offer: SessionDescription;
+    /** Feed in the remote peer's SDP answer to complete the handshake. */
+    accept(answer: SessionDescription): Promise<void>;
+    /** Resolves with the opened `PeerChannel` once the DataChannel is live. */
+    readonly channel: Promise<PeerChannel>;
+    readonly connection: PeerConnection;
+}
+interface Responder {
+    readonly answer: SessionDescription;
+    /** Resolves with the opened `PeerChannel` once the DataChannel is live. */
+    readonly channel: Promise<PeerChannel>;
+    readonly connection: PeerConnection;
+}
+/**
+ * Build an offer as the initiating peer. Returns the SDP offer to send
+ * to the remote peer and a promise for the opened `PeerChannel`.
+ */
+declare function createOffer(opts?: WebRTCOptions): Promise<Initiator>;
+/**
+ * Accept an incoming offer as the responding peer. Returns the SDP
+ * answer to send back to the initiator and a promise for the opened
+ * `PeerChannel`.
+ */
+declare function acceptOffer(offer: SessionDescription, opts?: WebRTCOptions): Promise<Responder>;
+
+export { type Initiator, type PeerChannel, type PeerStoreOptions, type Responder, type RpcClientOptions, type RpcHandler, type RpcMessage, type RpcRequest, type RpcResponse, type ServePeerStoreOptions, type WebRTCOptions, acceptOffer, createOffer, createRpcClient, fromDataChannel, pairInMemory, peerStore, servePeerStore, serveRpc };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import { NoydbStore } from '@noy-db/hub';
+
+/**
+ * `PeerChannel` — the minimal duplex message primitive used by the p2p
+ * NoydbStore wrapper. Any transport that can deliver UTF-8 strings
+ * reliably and in-order qualifies: WebRTC DataChannel, BroadcastChannel,
+ * MessagePort, WebSocket, even postMessage pairs.
+ *
+ * Keeping the transport abstract has three payoffs:
+ *
+ *   1. **Tests run without a WebRTC polyfill.** `pairInMemory()` returns
+ *      two wired channels for conformance tests against `to-memory`.
+ *   2. **Consumers pick their signaling story.** Matrix rooms, QR codes,
+ *      pastebin, Firebase Realtime DB — the handshake is out of scope.
+ *   3. **Future transports slot in cheaply.** WebTransport (HTTP/3),
+ *      libp2p, Iroh, or a plain relay WebSocket become additional
+ *      bindings without touching the RPC layer.
+ *
+ * @module
+ */
+/**
+ * Minimal duplex message primitive.
+ *
+ * Implementations MUST deliver every `send` payload in order exactly
+ * once to every live `on('message')` subscriber. `close()` is best-effort
+ * — once called, further `send()` calls MAY throw and `on('close')` MUST
+ * fire once.
+ */
+interface PeerChannel {
+    /** Enqueue a payload for delivery to the remote end. */
+    send(payload: string): void;
+    /** Subscribe to incoming payloads or lifecycle events. Returns unsubscribe. */
+    on(event: 'message', listener: (payload: string) => void): () => void;
+    on(event: 'close', listener: () => void): () => void;
+    /** Close the channel. Idempotent. */
+    close(): void;
+    /** True once the channel is ready for `send`. */
+    readonly isOpen: boolean;
+}
+/**
+ * Create a pair of in-memory `PeerChannel`s wired to each other.
+ * Intended for tests and multi-tab simulations inside a single process.
+ */
+declare function pairInMemory(): [PeerChannel, PeerChannel];
+/**
+ * Wrap a WebRTC `RTCDataChannel` as a `PeerChannel`.
+ *
+ * Browser-only — the caller is responsible for establishing the
+ * `RTCPeerConnection`, exchanging SDP offers/answers out of band, and
+ * passing the opened DataChannel here. When the remote peer is only
+ * reachable via TURN, the relay sees DTLS-wrapped ciphertext (noy-db
+ * already encrypts at rest, so even a TURN compromise leaks nothing).
+ */
+declare function fromDataChannel(dc: RTCDataChannel): PeerChannel;
+
+/**
+ * JSON-RPC protocol over a `PeerChannel`.
+ *
+ * Request shape:
+ *   `{ t: 'req', id, method, args }`
+ * Response shape (success):
+ *   `{ t: 'res', id, ok: true, result }`
+ * Response shape (error):
+ *   `{ t: 'res', id, ok: false, error: { name, message, version? } }`
+ *
+ * Why not reuse msgpack/protobuf? The payloads are already base64-encoded
+ * ciphertext — further binary packing saves ~8-12% at a large dependency
+ * cost. JSON over UTF-8 is inspectable, fits the zero-dependency ethos,
+ * and WebRTC DataChannel string mode already frames for us.
+ *
+ * @module
+ */
+
+/** Wire format discriminator for RPC messages. */
+type RpcMessage = RpcRequest | RpcResponse;
+interface RpcRequest {
+    readonly t: 'req';
+    readonly id: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+interface RpcResponse {
+    readonly t: 'res';
+    readonly id: string;
+    readonly ok: boolean;
+    readonly result?: unknown;
+    readonly error?: {
+        name: string;
+        message: string;
+        version?: number;
+    };
+}
+/** Handler invoked when an RPC request arrives. Return value is serialized as `result`. */
+type RpcHandler = (method: string, args: readonly unknown[]) => Promise<unknown>;
+/** Options for a client-side RPC caller. */
+interface RpcClientOptions {
+    /** Max milliseconds to wait for a response before rejecting. */
+    timeoutMs?: number;
+}
+/** Client: wrap a `PeerChannel` in a `call(method, args)` helper. */
+declare function createRpcClient(channel: PeerChannel, opts?: RpcClientOptions): {
+    call<T = unknown>(method: string, args: readonly unknown[]): Promise<T>;
+    dispose(): void;
+};
+/** Server: dispatch incoming RPC requests through a handler. Returns a dispose fn. */
+declare function serveRpc(channel: PeerChannel, handler: RpcHandler): () => void;
+
+/**
+ * `peerStore()` — a `NoydbStore` backed by RPC calls over a `PeerChannel`.
+ *
+ * The local peer calls `get`/`put`/`delete`/… against this store as if
+ * it were any other backend; every call is serialized as an RPC request
+ * to the remote peer, which runs `servePeerStore()` to funnel the RPCs
+ * into its own local `NoydbStore`.
+ *
+ * Error re-hydration: the remote handler re-throws `ConflictError` with
+ * a `.version` field when a CAS check fails. The RPC layer carries
+ * `version` in the error envelope so the local caller can catch
+ * `ConflictError` with the same semantics as a direct store call.
+ *
+ * @module
+ */
+
+interface PeerStoreOptions {
+    /** The duplex channel to the remote peer. */
+    readonly channel: PeerChannel;
+    /** Max ms to wait for any single RPC response. Default 30s. */
+    readonly timeoutMs?: number;
+    /** Optional display name used in diagnostics. Default `'by-peer'`. */
+    readonly name?: string;
+}
+/**
+ * Create a `NoydbStore` that forwards every operation to a remote peer
+ * over the supplied `PeerChannel`. The remote peer must be running
+ * `servePeerStore()` against its own local store.
+ */
+declare function peerStore(opts: PeerStoreOptions): NoydbStore & {
+    dispose: () => void;
+};
+
+/**
+ * `servePeerStore()` — runs on the peer that owns the data. Listens on
+ * a `PeerChannel` for RPC requests from a remote `peerStore()` client
+ * and executes each one against the local `NoydbStore`.
+ *
+ * The 6 core methods plus the optional `ping` / `listSince` / `listPage`
+ * extensions are exposed. Unknown methods surface as a remote Error.
+ *
+ * @module
+ */
+
+interface ServePeerStoreOptions {
+    /** The duplex channel from the remote peer. */
+    readonly channel: PeerChannel;
+    /** The local store to serve. */
+    readonly store: NoydbStore;
+    /**
+     * Optional method whitelist. When provided, any method not in the set
+     * is rejected with "method not allowed". Useful for read-only peers.
+     */
+    readonly allow?: ReadonlySet<string>;
+}
+/**
+ * Start serving the local store on the channel. Returns a dispose
+ * function that stops the RPC listener. The underlying channel is NOT
+ * closed by dispose — ownership stays with the caller.
+ */
+declare function servePeerStore(opts: ServePeerStoreOptions): () => void;
+
+/**
+ * WebRTC handshake helper — opinionated wrapper around
+ * `RTCPeerConnection` that produces a ready-to-use `PeerChannel`.
+ *
+ * The handshake is split into two halves so the caller can ferry the
+ * SDP blobs over whatever signaling channel they prefer (QR code,
+ * Matrix room, pastebin, Firebase, signed URL…). Signaling is
+ * intentionally out of scope — noy-db has no opinion on how peers
+ * discover each other, only on what flows once they do.
+ *
+ * ```ts
+ * // Peer A (initiator)
+ * const a = await createOffer({ iceServers })
+ * send(a.offer)                           // → signaling channel
+ * const answer = await receive()          // ← signaling channel
+ * await a.accept(answer)
+ * const channel = await a.channel         // ready PeerChannel
+ *
+ * // Peer B (responder)
+ * const offer = await receive()           // ← signaling channel
+ * const b = await acceptOffer(offer, { iceServers })
+ * send(b.answer)                          // → signaling channel
+ * const channel = await b.channel         // ready PeerChannel
+ * ```
+ *
+ * Browser-only. Node consumers who want to interconnect with browsers
+ * can plug `@roamhq/wrtc` into the global `RTCPeerConnection` slot; this
+ * module does not pull it in so the package has zero runtime deps.
+ *
+ * @module
+ */
+
+type PeerConnection = RTCPeerConnection;
+type SessionDescription = RTCSessionDescriptionInit;
+interface WebRTCOptions {
+    /** Optional ICE servers (STUN / TURN). */
+    readonly iceServers?: RTCIceServer[];
+    /** Label for the `RTCDataChannel`. Default `'noydb'`. */
+    readonly label?: string;
+}
+interface Initiator {
+    readonly offer: SessionDescription;
+    /** Feed in the remote peer's SDP answer to complete the handshake. */
+    accept(answer: SessionDescription): Promise<void>;
+    /** Resolves with the opened `PeerChannel` once the DataChannel is live. */
+    readonly channel: Promise<PeerChannel>;
+    readonly connection: PeerConnection;
+}
+interface Responder {
+    readonly answer: SessionDescription;
+    /** Resolves with the opened `PeerChannel` once the DataChannel is live. */
+    readonly channel: Promise<PeerChannel>;
+    readonly connection: PeerConnection;
+}
+/**
+ * Build an offer as the initiating peer. Returns the SDP offer to send
+ * to the remote peer and a promise for the opened `PeerChannel`.
+ */
+declare function createOffer(opts?: WebRTCOptions): Promise<Initiator>;
+/**
+ * Accept an incoming offer as the responding peer. Returns the SDP
+ * answer to send back to the initiator and a promise for the opened
+ * `PeerChannel`.
+ */
+declare function acceptOffer(offer: SessionDescription, opts?: WebRTCOptions): Promise<Responder>;
+
+export { type Initiator, type PeerChannel, type PeerStoreOptions, type Responder, type RpcClientOptions, type RpcHandler, type RpcMessage, type RpcRequest, type RpcResponse, type ServePeerStoreOptions, type WebRTCOptions, acceptOffer, createOffer, createRpcClient, fromDataChannel, pairInMemory, peerStore, servePeerStore, serveRpc };