@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/transport/grpc.mjs

@@ -1,6 +1,6 @@
-import { TransportError } from '../chunk-O7SLN3GI.mjs';
-import '../chunk-5NOIGN5Y.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import { TransportError } from '../chunk-BTTFW4Z4.mjs';
+import '../chunk-2QLXDHAP.mjs';
+import '../chunk-PBRXXISQ.mjs';
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { makeGenericClientConstructor, Server, Metadata, status, ServerCredentials, credentials } from '@grpc/grpc-js';
 import { readFileSync } from 'fs';
@@ -2778,6 +2778,18 @@ function buildChannelCreds(options) {
 }
 
 // src/transport/grpc/peer-streams.ts
+function replicateWriteStream(serverPeerStreams, clientPeerStreams, peerId) {
+  return serverPeerStreams.get(peerId)?.replicateStream ?? clientPeerStreams.get(peerId)?.replicateStream ?? null;
+}
+function syncWriteStream(serverPeerStreams, clientPeerStreams, peerId) {
+  return serverPeerStreams.get(peerId)?.syncStream ?? clientPeerStreams.get(peerId)?.syncStream ?? null;
+}
+function peerIdForServerStream(serverPeerStreams, entry) {
+  for (const [peerId, candidate] of serverPeerStreams) {
+    if (candidate === entry) return peerId;
+  }
+  return null;
+}
 function registerPeer(connectedPeers, peerConnectedHandler, nodeId, role, metadata = {}) {
   if (connectedPeers.has(nodeId)) return;
   const peerInfo = {
@@ -3196,34 +3208,58 @@ function writeWithBackpressure(stream, message) {
 
 // src/transport/grpc/transport.ts
 var GrpcReplicationTransport = class {
+  /** @internal */
   options;
+  /** @internal */
   localNodeId = "";
+  /** @internal */
   localRole = "replica";
+  /** @internal */
   localGroupId;
+  /** @internal */
   localPrimaryTerm;
+  /** @internal */
   localProtocolVersion;
+  /** @internal */
   connected = false;
+  /** @internal */
   server = null;
+  /** @internal */
   boundPort = 0;
+  /** @internal */
   healthImpl = null;
+  /** @internal */
   connectedPeers = /* @__PURE__ */ new Map();
+  /** @internal */
   serverPeerStreams = /* @__PURE__ */ new Map();
+  /** @internal */
   clientPeerStreams = /* @__PURE__ */ new Map();
+  /** @internal */
   batchHandler = null;
+  /** @internal */
   ackHandler = null;
+  /** @internal */
   forwardHandler = null;
+  /** @internal */
   peerConnectedHandler = null;
+  /** @internal */
   peerDisconnectedHandler = null;
+  /** @internal */
   syncRequestHandler = null;
+  /** @internal */
   syncBatchHandler = null;
+  /** @internal */
   syncCompleteHandler = null;
+  /** @internal */
   syncAckHandler = null;
   constructor(options = {}) {
     this.options = options;
   }
+  /** Returns the port the gRPC server bound to, which is the resolved port when you asked for 0. */
   getPort() {
     return this.boundPort;
   }
+  /** Connects to the configured peers and announces this node. */
   async connect(localNodeId, config) {
     if (this.connected) {
       throw new TransportError("Transport is already connected");
@@ -3246,6 +3282,7 @@ var GrpcReplicationTransport = class {
       }
     }
   }
+  /** Closes every peer connection. */
   async disconnect() {
     if (!this.connected) return;
     this.connected = false;
@@ -3286,6 +3323,7 @@ var GrpcReplicationTransport = class {
       this.server = null;
     }
   }
+  /** Sends one batch of changes to one peer. */
   async send(peerId, batch) {
     this.ensureConnected();
     const stream = this.getReplicateWriteStream(peerId);
@@ -3295,6 +3333,7 @@ var GrpcReplicationTransport = class {
     const msg = { batch: toBatchPayload(batch) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Sends one batch of changes to every connected peer. */
   async broadcast(batch) {
     this.ensureConnected();
     const msg = { batch: toBatchPayload(batch) };
@@ -3307,6 +3346,7 @@ var GrpcReplicationTransport = class {
     }
     await Promise.all(promises);
   }
+  /** Confirms to a peer that this node applied one of its batches. */
   async sendAck(peerId, ack) {
     this.ensureConnected();
     const stream = this.getReplicateWriteStream(peerId);
@@ -3316,6 +3356,7 @@ var GrpcReplicationTransport = class {
     const msg = { ack: toAckPayload(ack) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Sends a write to the primary and waits for its result. */
   async forward(peerId, request) {
     this.ensureConnected();
     const clientEntry = this.clientPeerStreams.get(peerId);
@@ -3324,6 +3365,7 @@ var GrpcReplicationTransport = class {
     }
     return forwardOverRpc(clientEntry, request, this.options.forwardDeadlineMs ?? DEFAULT_FORWARD_DEADLINE_MS);
   }
+  /** Asks a peer to stream a full copy of the database. */
   async requestSync(peerId, request) {
     this.ensureConnected();
     const stream = this.getSyncWriteStream(peerId);
@@ -3333,6 +3375,7 @@ var GrpcReplicationTransport = class {
     const msg = { syncRequest: toSyncRequestPayload(request) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Sends one page of first-sync table data. */
   async sendSyncBatch(peerId, batch) {
     this.ensureConnected();
     const stream = this.getSyncWriteStream(peerId);
@@ -3342,6 +3385,7 @@ var GrpcReplicationTransport = class {
     const msg = { syncBatch: toSyncBatchPayload(batch) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Tells a joining node that first sync has finished, and sends the manifests to verify it. */
   async sendSyncComplete(peerId, complete) {
     this.ensureConnected();
     const stream = this.getSyncWriteStream(peerId);
@@ -3351,6 +3395,7 @@ var GrpcReplicationTransport = class {
     const msg = { syncComplete: toSyncCompletePayload(complete) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Confirms to the source that a joining node stored one first-sync page. */
   async sendSyncAck(peerId, ack) {
     this.ensureConnected();
     const stream = this.getSyncWriteStream(peerId);
@@ -3360,33 +3405,43 @@ var GrpcReplicationTransport = class {
     const msg = { syncAck: toSyncAckPayload(ack) };
     await writeWithBackpressure(stream, msg);
   }
+  /** Registers the handler that applies incoming change batches. */
   onBatchReceived(handler) {
     this.batchHandler = handler;
   }
+  /** Registers the handler that records incoming acknowledgements. */
   onAckReceived(handler) {
     this.ackHandler = handler;
   }
+  /** Registers the handler that runs a write a replica forwarded. */
   onForwardReceived(handler) {
     this.forwardHandler = handler;
   }
+  /** Registers the handler that serves a first-sync request. */
   onSyncRequested(handler) {
     this.syncRequestHandler = handler;
   }
+  /** Registers the handler that stores an incoming first-sync page. */
   onSyncBatchReceived(handler) {
     this.syncBatchHandler = handler;
   }
+  /** Registers the handler that finishes first sync and verifies the manifests. */
   onSyncCompleteReceived(handler) {
     this.syncCompleteHandler = handler;
   }
+  /** Registers the handler that records first-sync page acknowledgements. */
   onSyncAckReceived(handler) {
     this.syncAckHandler = handler;
   }
+  /** Registers the handler that runs when a peer connects. */
   onPeerConnected(handler) {
     this.peerConnectedHandler = handler;
   }
+  /** Registers the handler that runs when a peer disconnects. */
   onPeerDisconnected(handler) {
     this.peerDisconnectedHandler = handler;
   }
+  /** Returns every connected peer, keyed by identifier. */
   peers() {
     return this.connectedPeers;
   }
@@ -3402,12 +3457,14 @@ var GrpcReplicationTransport = class {
     if (Array.isArray(certCN)) return certCN[0] ?? null;
     return certCN;
   }
+  /** @internal */
   validateTlsIdentity(call, claimedNodeId) {
     if (this.options.insecure) return true;
     if (!this.options.tlsCaCert) return true;
     const cn = this.extractTlsCN(call);
     return cn === claimedNodeId;
   }
+  /** @internal */
   resolveForwardPeerId(call) {
     const cn = this.extractTlsCN(call);
     if (cn) {
@@ -3417,36 +3474,22 @@ var GrpcReplicationTransport = class {
     const peerAddr = call.getPeer();
     for (const [, entry] of this.serverPeerStreams) {
       if (entry.replicateStream?.getPeer() === peerAddr) {
-        const streamPeerId = this.findPeerIdForStream(entry);
+        const streamPeerId = peerIdForServerStream(this.serverPeerStreams, entry);
         if (streamPeerId) return streamPeerId;
       }
     }
     return null;
   }
-  findPeerIdForStream(entry) {
-    for (const [peerId, ps] of this.serverPeerStreams) {
-      if (ps === entry) return peerId;
-    }
-    return null;
-  }
   ensureConnected() {
     if (!this.connected) {
       throw new TransportError("Transport is not connected");
     }
   }
   getReplicateWriteStream(peerId) {
-    const serverStream = this.serverPeerStreams.get(peerId);
-    if (serverStream?.replicateStream) return serverStream.replicateStream;
-    const clientEntry = this.clientPeerStreams.get(peerId);
-    if (clientEntry?.replicateStream) return clientEntry.replicateStream;
-    return null;
+    return replicateWriteStream(this.serverPeerStreams, this.clientPeerStreams, peerId);
   }
   getSyncWriteStream(peerId) {
-    const serverStream = this.serverPeerStreams.get(peerId);
-    if (serverStream?.syncStream) return serverStream.syncStream;
-    const clientEntry = this.clientPeerStreams.get(peerId);
-    if (clientEntry?.syncStream) return clientEntry.syncStream;
-    return null;
+    return syncWriteStream(this.serverPeerStreams, this.clientPeerStreams, peerId);
   }
 };
 

package/dist/transport/memory.d.ts

@@ -1,8 +1,9 @@
-import { N as NodeInfo, R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, T as TransportConfig } from '../types-B7gmEsZW.js';
-import { R as ReplicationBatch } from '../types-C_D8IhpO.js';
-import '../change-tracker-DKRVUC3l.js';
-import '../types-zhnRXrsb.js';
-import '../types-BsVabqSI.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DyrCiWuc.js';
+import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
+import '../change-tracker-DDmXB754.js';
+import '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
+import '../types-CMBcFPhb.js';
 
 type BatchHandler = (batch: ReplicationBatch, fromPeerId: string) => Promise<void>;
 type AckHandler = (ack: ReplicationAck, fromPeerId: string) => void;
@@ -20,10 +21,12 @@ type SyncAckHandler = (ack: SyncAck, fromPeerId: string) => void;
  *
  * Messages between peers are delivered through a shared MemoryBus via
  * microtask scheduling (`queueMicrotask`), preserving the async delivery
- * semantics of a real network transport while avoiding actual I/O. All
+ * semantics of a real network transport with no I/O. All
  * message types (batches, acks, forwards) go through runtime
  * validation before delivery, and malformed payloads are silently dropped
- * to match the behavior of a lossy network.
+ * to match the behaviour of a lossy network.
+ *
+ * @public
  */
 declare class InMemoryTransport implements ReplicationTransport {
     private localNodeId;
@@ -31,47 +34,67 @@ declare class InMemoryTransport implements ReplicationTransport {
     private localGroupId;
     private localPrimaryTerm;
     private localProtocolVersion;
-    connected: boolean;
+    private connected;
     private readonly bus;
-    readonly connectedPeers: Map<string, NodeInfo>;
+    private readonly connectedPeers;
     private batchHandler;
     private ackHandler;
     private forwardHandler;
-    peerConnectedHandler: PeerConnectedHandler | null;
-    peerDisconnectedHandler: PeerDisconnectedHandler | null;
+    private peerConnectedHandler;
+    private peerDisconnectedHandler;
     private syncRequestHandler;
     private syncBatchHandler;
     private syncCompleteHandler;
     private syncAckHandler;
     constructor(bus: MemoryBus);
-    get role(): 'primary' | 'replica';
+    private get role();
+    /** Connects to the configured peers and announces this node. */
     connect(localNodeId: string, config: TransportConfig): Promise<void>;
+    /** Closes every peer connection. */
     disconnect(): Promise<void>;
+    /** Sends one batch of changes to one peer. */
     send(peerId: string, batch: ReplicationBatch): Promise<void>;
+    /** Sends one batch of changes to every connected peer. */
     broadcast(batch: ReplicationBatch): Promise<void>;
+    /** Confirms to a peer that this node applied one of its batches. */
     sendAck(peerId: string, ack: ReplicationAck): Promise<void>;
+    /** Sends a write to the primary and waits for its result. */
     forward(peerId: string, request: ForwardedTransaction): Promise<ForwardedTransactionResult>;
+    /** Asks a peer to stream a full copy of the database. */
     requestSync(peerId: string, request: SyncRequest): Promise<void>;
+    /** Sends one page of first-sync table data. */
     sendSyncBatch(peerId: string, batch: SyncBatch): Promise<void>;
+    /** Tells a joining node that first sync has finished, and sends the manifests to verify it. */
     sendSyncComplete(peerId: string, complete: SyncComplete): Promise<void>;
+    /** Confirms to the source that a joining node stored one first-sync page. */
     sendSyncAck(peerId: string, ack: SyncAck): Promise<void>;
+    /** Registers the handler that applies incoming change batches. */
     onBatchReceived(handler: BatchHandler): void;
+    /** Registers the handler that records incoming acknowledgements. */
     onAckReceived(handler: AckHandler): void;
+    /** Registers the handler that runs a write a replica forwarded. */
     onForwardReceived(handler: ForwardHandler): void;
+    /** Registers the handler that serves a first-sync request. */
     onSyncRequested(handler: SyncRequestHandler): void;
+    /** Registers the handler that stores an incoming first-sync page. */
     onSyncBatchReceived(handler: SyncBatchHandler): void;
+    /** Registers the handler that finishes first sync and verifies the manifests. */
     onSyncCompleteReceived(handler: SyncCompleteHandler): void;
+    /** Registers the handler that records first-sync page acknowledgements. */
     onSyncAckReceived(handler: SyncAckHandler): void;
+    /** Registers the handler that runs when a peer connects. */
     onPeerConnected(handler: PeerConnectedHandler): void;
+    /** Registers the handler that runs when a peer disconnects. */
     onPeerDisconnected(handler: PeerDisconnectedHandler): void;
+    /** Returns every connected peer, keyed by identifier. */
     peers(): ReadonlyMap<string, NodeInfo>;
-    _receiveBatch(batch: ReplicationBatch, fromPeerId: string): Promise<void>;
-    _receiveAck(ack: ReplicationAck, fromPeerId: string): void;
-    _receiveForward(request: ForwardedTransaction, fromPeerId: string): Promise<ForwardedTransactionResult>;
-    _receiveSyncRequest(request: SyncRequest, fromPeerId: string): Promise<void>;
-    _receiveSyncBatch(batch: SyncBatch, fromPeerId: string): Promise<void>;
-    _receiveSyncComplete(complete: SyncComplete, fromPeerId: string): Promise<void>;
-    _receiveSyncAck(ack: SyncAck, fromPeerId: string): void;
+    private _receiveBatch;
+    private _receiveAck;
+    private _receiveForward;
+    private _receiveSyncRequest;
+    private _receiveSyncBatch;
+    private _receiveSyncComplete;
+    private _receiveSyncAck;
     private ensureConnected;
 }
 
@@ -79,14 +102,21 @@ declare class InMemoryTransport implements ReplicationTransport {
  * Shared message bus that connects InMemoryTransport instances within the
  * same process. Each transport registers itself on `connect()` and messages
  * are delivered via direct method calls on the target transport through
- * microtask scheduling, simulating async network delivery without actual I/O.
+ * microtask scheduling, simulating async network delivery with no I/O.
+ *
+ * @public
  */
 declare class MemoryBus {
     private readonly transports;
+    /** @internal */
     join(peerId: string, transport: InMemoryTransport): void;
+    /** @internal */
     leave(peerId: string): void;
+    /** @internal */
     getTransport(peerId: string): InMemoryTransport | undefined;
+    /** @internal */
     peerIds(): IterableIterator<string>;
+    /** @internal */
     get size(): number;
 }
 

package/dist/transport/memory.mjs

@@ -1,18 +1,23 @@
 // src/transport/memory/bus.ts
 var MemoryBus = class {
   transports = /* @__PURE__ */ new Map();
+  /** @internal */
   join(peerId, transport) {
     this.transports.set(peerId, transport);
   }
+  /** @internal */
   leave(peerId) {
     this.transports.delete(peerId);
   }
+  /** @internal */
   getTransport(peerId) {
     return this.transports.get(peerId);
   }
+  /** @internal */
   peerIds() {
     return this.transports.keys();
   }
+  /** @internal */
   get size() {
     return this.transports.size;
   }
@@ -115,6 +120,7 @@ var InMemoryTransport = class {
   get role() {
     return this.localRole;
   }
+  /** Connects to the configured peers and announces this node. */
   async connect(localNodeId, config) {
     if (this.connected) {
       throw new TransportError("Transport is already connected");
@@ -160,6 +166,7 @@ var InMemoryTransport = class {
       }
     }
   }
+  /** Closes every peer connection. */
   async disconnect() {
     if (!this.connected) return;
     this.connected = false;
@@ -175,6 +182,7 @@ var InMemoryTransport = class {
     }
     this.connectedPeers.clear();
   }
+  /** Sends one batch of changes to one peer. */
   async send(peerId, batch) {
     this.ensureConnected();
     if (!isValidBatch(batch)) {
@@ -190,6 +198,7 @@ var InMemoryTransport = class {
       });
     });
   }
+  /** Sends one batch of changes to every connected peer. */
   async broadcast(batch) {
     this.ensureConnected();
     if (!isValidBatch(batch)) {
@@ -206,6 +215,7 @@ var InMemoryTransport = class {
       }
     }
   }
+  /** Confirms to a peer that this node applied one of its batches. */
   async sendAck(peerId, ack) {
     this.ensureConnected();
     if (!isValidAck(ack)) {
@@ -220,6 +230,7 @@ var InMemoryTransport = class {
       peer._receiveAck(ack, fromPeerId);
     });
   }
+  /** Sends a write to the primary and waits for its result. */
   async forward(peerId, request) {
     this.ensureConnected();
     if (!isValidForwardedTransaction(request)) {
@@ -231,6 +242,7 @@ var InMemoryTransport = class {
     }
     return peer._receiveForward(request, this.localNodeId);
   }
+  /** Asks a peer to stream a full copy of the database. */
   async requestSync(peerId, request) {
     this.ensureConnected();
     if (!isValidSyncRequest(request)) throw new TransportError("Invalid sync request structure");
@@ -242,6 +254,7 @@ var InMemoryTransport = class {
       });
     });
   }
+  /** Sends one page of first-sync table data. */
   async sendSyncBatch(peerId, batch) {
     this.ensureConnected();
     if (!isValidSyncBatch(batch)) throw new TransportError("Invalid sync batch structure");
@@ -253,6 +266,7 @@ var InMemoryTransport = class {
       });
     });
   }
+  /** Tells a joining node that first sync has finished, and sends the manifests to verify it. */
   async sendSyncComplete(peerId, complete) {
     this.ensureConnected();
     if (!isValidSyncComplete(complete)) throw new TransportError("Invalid sync complete structure");
@@ -264,6 +278,7 @@ var InMemoryTransport = class {
       });
     });
   }
+  /** Confirms to the source that a joining node stored one first-sync page. */
   async sendSyncAck(peerId, ack) {
     this.ensureConnected();
     if (!isValidSyncAck(ack)) throw new TransportError("Invalid sync ack structure");
@@ -274,33 +289,43 @@ var InMemoryTransport = class {
       peer._receiveSyncAck(ack, fromPeerId);
     });
   }
+  /** Registers the handler that applies incoming change batches. */
   onBatchReceived(handler) {
     this.batchHandler = handler;
   }
+  /** Registers the handler that records incoming acknowledgements. */
   onAckReceived(handler) {
     this.ackHandler = handler;
   }
+  /** Registers the handler that runs a write a replica forwarded. */
   onForwardReceived(handler) {
     this.forwardHandler = handler;
   }
+  /** Registers the handler that serves a first-sync request. */
   onSyncRequested(handler) {
     this.syncRequestHandler = handler;
   }
+  /** Registers the handler that stores an incoming first-sync page. */
   onSyncBatchReceived(handler) {
     this.syncBatchHandler = handler;
   }
+  /** Registers the handler that finishes first sync and verifies the manifests. */
   onSyncCompleteReceived(handler) {
     this.syncCompleteHandler = handler;
   }
+  /** Registers the handler that records first-sync page acknowledgements. */
   onSyncAckReceived(handler) {
     this.syncAckHandler = handler;
   }
+  /** Registers the handler that runs when a peer connects. */
   onPeerConnected(handler) {
     this.peerConnectedHandler = handler;
   }
+  /** Registers the handler that runs when a peer disconnects. */
   onPeerDisconnected(handler) {
     this.peerDisconnectedHandler = handler;
   }
+  /** Returns every connected peer, keyed by identifier. */
   peers() {
     return this.connectedPeers;
   }

package/dist/{types-CL6piSnD.d.ts → types-BCejqzNA.d.ts}

@@ -1,3 +1,6 @@
+/** Where a live query stands: waiting for its first rows, holding rows, or failed.
+ * @public
+ */
 type LiveQueryState<T> = {
     status: 'pending';
 } | {
@@ -8,6 +11,9 @@ type LiveQueryState<T> = {
     status: 'error';
     error: Error;
 };
+/** One change to a live query's result set, as a position and the row at it.
+ * @public
+ */
 type ResultOp<T> = {
     op: 'insert';
     index: number;
@@ -20,6 +26,9 @@ type ResultOp<T> = {
     op: 'delete';
     index: number;
 };
+/** What a live query tells its listeners: the rows replaced, edited in place, being re-read, or failed.
+ * @public
+ */
 type LiveUpdate<T> = {
     kind: 'rows';
 } | {
@@ -30,13 +39,24 @@ type LiveUpdate<T> = {
 } | {
     kind: 'error';
 };
+/** A registered read that keeps its rows current as the underlying tables change.
+ * @public
+ */
 interface LiveQuery<T = Record<string, unknown>> {
+    /** Returns the rows the query holds right now. */
     getState(): LiveQueryState<T>;
+    /** Calls back on each update and returns a function that stops the listener. */
     subscribe(listener: (update: LiveUpdate<T>) => void): () => void;
+    /** Ends the query and releases its subscription. */
     close(): Promise<void>;
 }
+/** Settings for one live query.
+ * @public
+ */
 interface LiveQueryOptions {
+    /** Milliseconds of random delay before a re-read, which spreads the load of many queries reacting at once. */
     rereadJitterMs?: number;
+    /** Changes in one transaction above which the query re-reads instead of applying them one by one. */
     maxTransactionChanges?: number;
 }