@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/{server-options-1JHu8pid.d.ts → server-options-Dab_Jvd_.d.ts}

@@ -1,6 +1,7 @@
-import { a as OperationRegistry } from './operation-registry-9DcvxcE5.js';
-import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult } from './types-C_D8IhpO.js';
-import { N as NodeHealth, P as Params, Q as QueryOptions, E as ExecuteResult, T as Transaction, C as ClusterStatusInfo } from './types-zhnRXrsb.js';
+import { a as OperationRegistry } from './operation-registry-hlbhqu7q.js';
+import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult } from './types-CjhxcjhA.js';
+import { N as NodeHealth, T as Transaction, C as ClusterStatusInfo } from './types-rVZKnKN-.js';
+import { P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-DL3LtPvY.js';
 
 interface AppliedMigrationRow {
     version: number;
@@ -8,15 +9,32 @@ interface AppliedMigrationRow {
     checksum: string | null;
 }
 
-/** Context passed to the authenticate hook. */
+/** Context passed to the authenticate hook.
+ * @public
+ */
 interface RequestContext {
+    /** Request headers, with every name lower-cased. */
     headers: Record<string, string>;
+    /** HTTP method of the request, or the method of a WebSocket upgrade. */
     method: string;
+    /** Path the request arrived on. */
     path: string;
+    /** Identifier of the database the route addresses. */
     databaseId?: string;
+    /** Address the request came from. */
     remoteAddress: string;
 }
+/**
+ * Identifies the caller behind a request. Return the identity registered
+ * operations then read, and throw a {@link RequestDeniedError} to refuse the
+ * request with a status of your own.
+ *
+ * @public
+ */
 type AuthenticateHook<Identity = unknown> = (ctx: RequestContext) => Identity | undefined | Promise<Identity | undefined>;
+/** Reports whether a caller may read the addresses of every node in the group.
+ * @public
+ */
 type ClusterStatusAuthorizer = (ctx: RequestContext) => boolean | Promise<boolean>;
 /**
  * Durability level in force while a bulk load runs. SQLite sanctions 'off' for
@@ -24,8 +42,13 @@ type ClusterStatusAuthorizer = (ctx: RequestContext) => boolean | Promise<boolea
  * gives up corruption safety, so it fits only a load that starts from nothing.
  * 'normal' keeps WAL-mode corruption safety and suits loads into a database
  * that already holds data the operator cannot afford to lose.
+ *
+ * @public
  */
 type BulkLoadDurability = 'off' | 'normal';
+/** Settings for one bulk load.
+ * @public
+ */
 interface BulkLoadOptions {
     /** Durability during the load. Default: 'off'. */
     durability?: BulkLoadDurability;
@@ -39,28 +62,41 @@ interface BulkLoadOptions {
     checkpoint?: boolean;
 }
 /** Aggregate outcome of a bulk load. Summed rather than per-row so a
- * million-row load never holds a million result objects in memory. */
+ * million-row load never holds a million result objects in memory.
+ * @public
+ */
 interface BulkLoadResult {
+    /** Number of parameter sets the load applied. */
     rowsLoaded: number;
+    /** Number of rows the load inserted, updated, or deleted. */
     changes: number;
 }
+/**
+ * What the server runs statements against for one database. A local
+ * `Database` satisfies it, and so does a proxy that forwards to another node.
+ *
+ * @public
+ */
 interface ServerExecutionTarget {
+    /** Runs a read and returns the rows. */
     query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
     /**
      * Optional single-pass read that returns rows already encoded for the wire
      * (safe-range integers as plain numbers, larger integers and BLOBs as tagged
-     * envelopes). When present the server uses it instead of {@link query}
+     * envelopes). When present the server uses it instead of {@link ServerExecutionTarget.query}
      * followed by a separate tag-encoding walk. A target that omits it stays
-     * correct: the server falls back to encoding {@link query} rows itself.
+     * correct: the server falls back to encoding {@link ServerExecutionTarget.query} rows itself.
      */
     queryForWire?(sql: string, params?: Params, options?: QueryOptions): Promise<unknown[]>;
+    /** Runs one write and returns the change count and last inserted row id. */
     execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    /** Runs a function inside one transaction. */
     transaction<T>(fn: (tx: Transaction) => Promise<T>, options?: QueryOptions): Promise<T>;
     /**
      * Optional entry point for a transaction whose statements are all known
      * before it starts, which lets concurrent transactions share one commit. A
      * target that omits it stays correct: the server falls back to
-     * {@link transaction} and runs the statements one at a time.
+     * {@link ServerExecutionTarget.transaction} and runs the statements one at a time.
      */
     executeTransaction?(statements: readonly {
         sql: string;
@@ -72,14 +108,26 @@ interface ServerExecutionTarget {
      * of silently degrading to per-statement writes.
      */
     bulkLoad?(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+    /** Optional device-sync entry point that applies a batch of changes a device pushed. */
     applyChanges?(batch: ReplicationBatch, resolver?: ConflictResolver | ((table: string) => ConflictResolver)): Promise<ApplyResult>;
+    /** Optional listing of the migrations this database has applied. */
     appliedMigrations?(): Promise<AppliedMigrationRow[]>;
 }
+/**
+ * Finds what the server should run a database's statements against.
+ *
+ * @public
+ */
 type ServerExecutionTargetResolver = (databaseId: string) => ServerExecutionTarget | null | undefined | Promise<ServerExecutionTarget | null | undefined>;
-/** Options for the standalone HTTP + WS server. */
+/** Options for the standalone HTTP + WS server.
+ * @public
+ */
 interface ServerOptions<Identity = unknown> {
+    /** Address the server binds to. Default: '0.0.0.0'. */
     host?: string;
+    /** Port the server binds to. Default: 3000. */
     port?: number;
+    /** Cross-origin rules the server answers browser requests with. */
     cors?: boolean | CorsOptions;
     /**
      * Maximum HTTP request body and WebSocket message size in bytes. Applied
@@ -107,43 +155,77 @@ interface ServerOptions<Identity = unknown> {
      * (one hour).
      */
     cdcRetentionMs?: number;
+    /** How long, in milliseconds, a device's sync cursor is kept after its last contact. */
     deviceCursorRetentionMs?: number;
+    /** Changes a device may leave unacknowledged before the server stops sending more. */
     maxUnacknowledgedChanges?: number;
+    /** Runs before every database route and every WebSocket upgrade, and names the caller. */
     authenticate?: AuthenticateHook<Identity>;
+    /** Statements callers may invoke by name. Without these, only SQL routes serve reads and writes. */
     operations?: OperationRegistry<Identity>;
+    /** Opens the five statement routes and their WebSocket messages. Default: false. */
     acceptSql?: boolean;
+    /** Finds what the server runs a database's statements against. */
     resolveExecutionTarget?: ServerExecutionTargetResolver;
+    /** Supplies the replication figures the readiness endpoint reports. */
     getReplicationStatus?: () => ReplicationStatusInfo | null;
+    /** Supplies what `GET /db/{id}/cluster` reports for one database. */
     getClusterStatus?: (databaseId: string) => ClusterStatusInfo | null;
+    /** Reports whether a caller may read the addresses of every node in the group. */
     authorizeClusterStatus?: ClusterStatusAuthorizer;
 }
+/** Replication figures one node reports through its readiness endpoint.
+ * @public
+ */
 interface ReplicationStatusInfo {
+    /** Whether this node accepts writes or serves reads. */
     role: string;
+    /** Whether this node forwards writes to the primary. */
     writeForwarding: boolean;
+    /** Number of peers the node is connected to. */
     peers: number;
+    /** Highest change-log position this node has recorded locally. */
     localSeq: bigint;
+    /** What the node can do right now, and the condition behind it. */
     health: NodeHealth;
+    /** Identifier of the replication group the node belongs to. */
     replicationGroupId?: string;
+    /** The primary term this node reports as current. */
     primaryTerm?: bigint;
+    /** Identifier of the primary this node reports as current. */
     currentPrimary?: string;
+    /** Whether the node reaches its cluster coordinator, and whether it holds write authority. */
     coordinator?: {
         connected: boolean;
         authority: boolean;
     };
+    /** Whether this node runs the group's controller loop. */
     controller?: {
         state: 'disabled' | 'standby' | 'active' | 'lost';
     };
+    /** Identifiers of the replicas the group counts as in sync. */
     inSyncReplicas?: string[];
+    /** Identifiers of the replicas that have fallen behind. */
     laggingReplicas?: string[];
+    /** Where this node stands in first sync. */
     syncState?: string;
 }
-/** CORS configuration. */
+/** CORS configuration.
+ * @public
+ */
 interface CorsOptions {
+    /** Origins the server allows. */
     origin?: string | string[];
+    /** Methods the server allows. */
     methods?: string[];
+    /** Request headers the server allows. */
     headers?: string[];
 }
-/** Options for the mountable WebSocket handler. */
+/**
+ * Options for the mountable WebSocket handler.
+ *
+ * @internal
+ */
 interface WSHandlerOptions<Identity = unknown> {
     /** Maximum message size in bytes. Default: 1_048_576 (1 MB). */
     maxPayloadLength?: number;
@@ -155,7 +237,9 @@ interface WSHandlerOptions<Identity = unknown> {
     operations?: OperationRegistry<Identity>;
     resolveExecutionTarget?: ServerExecutionTargetResolver;
 }
-/** Options for the client SDK. */
+/** Options for the client SDK.
+ * @public
+ */
 interface ClientOptions {
     /** Transport to use. Default: 'websocket'. */
     transport?: 'websocket' | 'http';

package/dist/sirannon-CMhiJa5Y.d.ts

@@ -0,0 +1,111 @@
+import { D as Database } from './database-B5Qv1-cU.js';
+import { S as SirannonOptions, a as SQLiteDriver, D as DatabaseOptions, M as Migration, B as BeforeQueryHook, A as AfterQueryHook, b as BeforeConnectHook, c as DatabaseOpenHook, d as DatabaseCloseHook } from './types-rVZKnKN-.js';
+
+/**
+ * A registry of open SQLite databases, keyed by identifier.
+ *
+ * It opens each database through one driver, applies shared hooks, metrics, and migrations, and closes idle databases when you configure a lifecycle.
+ *
+ * @public
+ */
+declare class Sirannon {
+    private readonly dbs;
+    private readonly opening;
+    private readonly resolving;
+    private migrationSet;
+    private _shutdown;
+    private readonly _driver;
+    private readonly hookRegistry;
+    private readonly metricsCollector;
+    private readonly lifecycleManager;
+    /** The driver, hooks, metrics, lifecycle, migrations, and writer-worker default this registry was built with. */
+    readonly options: SirannonOptions;
+    /**
+     * Builds a registry.
+     *
+     * @param options - Driver, hooks, metrics, lifecycle, migrations, and the writer-worker default.
+     */
+    constructor(options: SirannonOptions);
+    /** @internal */
+    get driver(): SQLiteDriver;
+    /**
+     * Opens a database and registers it under an identifier.
+     *
+     * @param id - Identifier callers reach this database by.
+     * @param path - File path of the SQLite database.
+     * @param options - Pool size, journal mode, durability, and change-capture settings.
+     * @returns The open database.
+     * @throws When the identifier is already registered.
+     */
+    open(id: string, path: string, options?: DatabaseOptions): Promise<Database>;
+    private withRegistryDefaults;
+    /**
+     * Closes one database and removes it from the registry.
+     *
+     * @param id - Identifier of the database to close.
+     */
+    close(id: string): Promise<void>;
+    /**
+     * Returns an already-open database.
+     *
+     * @param id - Identifier of the database.
+     * @returns The database, or undefined when none is open under that identifier.
+     */
+    get(id: string): Database | undefined;
+    /** @internal */
+    resolve(id: string): Promise<Database | undefined>;
+    /** @internal */
+    registryMigrations(): Promise<Migration[]>;
+    private applyRegistryMigrations;
+    private loadMigrationSet;
+    /**
+     * Reports whether a database is open under an identifier.
+     *
+     * @param id - Identifier to check.
+     * @returns True when the registry holds an open database under it.
+     */
+    has(id: string): boolean;
+    /**
+     * Returns every database this registry currently holds open.
+     *
+     * @returns The open databases, keyed by identifier.
+     */
+    databases(): Map<string, Database>;
+    /**
+     * Closes every open database and stops the lifecycle timers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Registers a hook that runs before each statement on every database in this registry. Throw from it to refuse the statement.
+     *
+     * @param hook - Receives the statement, its parameters, and the concerns it carries.
+     */
+    onBeforeQuery(hook: BeforeQueryHook): void;
+    /**
+     * Registers a hook that runs after each statement on every database in this registry.
+     *
+     * @param hook - Receives the statement and how long it took.
+     */
+    onAfterQuery(hook: AfterQueryHook): void;
+    /**
+     * Registers a hook that runs before a database connection opens.
+     *
+     * @param hook - Receives the database identifier and its file path.
+     */
+    onBeforeConnect(hook: BeforeConnectHook): void;
+    /**
+     * Registers a hook that runs once a database is open.
+     *
+     * @param hook - Receives the database identifier and its file path.
+     */
+    onDatabaseOpen(hook: DatabaseOpenHook): void;
+    /**
+     * Registers a hook that runs once a database is closed.
+     *
+     * @param hook - Receives the database identifier and its file path.
+     */
+    onDatabaseClose(hook: DatabaseCloseHook): void;
+    private ensureRunning;
+}
+
+export { Sirannon as S };

package/dist/transport/grpc.d.ts

@@ -1,11 +1,12 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Client, ClientDuplexStream, CallOptions, Metadata, ServiceError, ClientUnaryCall, ChannelCredentials, ClientOptions, ServerDuplexStream, Server } from '@grpc/grpc-js';
 import { HealthImplementation } from 'grpc-health-check';
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, 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, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, 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';
 
 interface ColumnValue {
     nullValue?: boolean | undefined;
@@ -223,16 +224,52 @@ interface MessageFns<T> {
     fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
 }
 
+/**
+ * Encodes one SQLite value into the gRPC column representation.
+ *
+ * @internal
+ */
 declare function toColumnValue(value: unknown): ColumnValue;
+/**
+ * Decodes one gRPC column value back into a SQLite value.
+ *
+ * @internal
+ */
 declare function fromColumnValue(cv: ColumnValue): unknown;
 
+/**
+ * @public
+ *
+ * Where the gRPC transport listens, and the certificates it presents and trusts.
+ */
 interface GrpcReplicationOptions {
+    /**
+     * Address the gRPC server binds to. Default: '0.0.0.0'.
+     */
     host?: string;
+    /**
+     * Port the gRPC server binds to. Pass 0 to take any free port.
+     */
     port?: number;
+    /**
+     * Path to this node's certificate.
+     */
     tlsCert?: string;
+    /**
+     * Path to this node's private key.
+     */
     tlsKey?: string;
+    /**
+     * Path to the authority certificate this node verifies its peers against.
+     */
     tlsCaCert?: string;
+    /**
+     * Runs without TLS, which suits tests only.
+     */
     insecure?: boolean;
+    /**
+     * Milliseconds a forwarded write may take before the replica gives up. Default: 30000.
+     */
     forwardDeadlineMs?: number;
 }
 
@@ -255,62 +292,109 @@ type SyncBatchHandler = (batch: SyncBatch, fromPeerId: string) => Promise<void>;
 type SyncCompleteHandler = (complete: SyncComplete, fromPeerId: string) => Promise<void>;
 type SyncAckHandler = (ack: SyncAck, fromPeerId: string) => void;
 
+/**
+ * @public
+ *
+ * Replicates between nodes over gRPC with mutual TLS, which is the transport production clusters use.
+ */
 declare class GrpcReplicationTransport implements ReplicationTransport {
+    /** @internal */
     readonly options: GrpcReplicationOptions;
+    /** @internal */
     localNodeId: string;
+    /** @internal */
     localRole: TopologyRole;
+    /** @internal */
     localGroupId: string | undefined;
+    /** @internal */
     localPrimaryTerm: bigint | undefined;
+    /** @internal */
     localProtocolVersion: string | undefined;
+    /** @internal */
     connected: boolean;
+    /** @internal */
     server: Server | null;
+    /** @internal */
     boundPort: number;
+    /** @internal */
     healthImpl: HealthImplementation | null;
+    /** @internal */
     readonly connectedPeers: Map<string, NodeInfo>;
+    /** @internal */
     readonly serverPeerStreams: Map<string, PeerStreamEntry>;
+    /** @internal */
     readonly clientPeerStreams: Map<string, ClientPeerEntry>;
+    /** @internal */
     batchHandler: BatchHandler | null;
+    /** @internal */
     ackHandler: AckHandler | null;
+    /** @internal */
     forwardHandler: ForwardHandler | null;
+    /** @internal */
     peerConnectedHandler: PeerConnectedHandler | null;
+    /** @internal */
     peerDisconnectedHandler: PeerDisconnectedHandler | null;
+    /** @internal */
     syncRequestHandler: SyncRequestHandler | null;
+    /** @internal */
     syncBatchHandler: SyncBatchHandler | null;
+    /** @internal */
     syncCompleteHandler: SyncCompleteHandler | null;
+    /** @internal */
     syncAckHandler: SyncAckHandler | null;
     constructor(options?: GrpcReplicationOptions);
+    /** Returns the port the gRPC server bound to, which is the resolved port when you asked for 0. */
     getPort(): number;
+    /** 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>;
-    extractTlsCN(call: {
-        getAuthContext(): unknown;
-    }): string | null;
+    private extractTlsCN;
+    /** @internal */
     validateTlsIdentity(call: {
         getAuthContext(): unknown;
     }, claimedNodeId: string): boolean;
+    /** @internal */
     resolveForwardPeerId(call: {
         getPeer(): string;
         getAuthContext(): unknown;
     }): string | null;
-    private findPeerIdForStream;
     private ensureConnected;
     private getReplicateWriteStream;
     private getSyncWriteStream;