@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/sirannon-J3EgPVD7.d.ts

@@ -0,0 +1,179 @@
+import { H as HookRegistry, M as MetricsCollector, D as Database, a as HookDispose } from './database-CGDsXW1K.js';
+import { a as SirannonOptions, S as SQLiteDriver, D as DatabaseOptions, M as Migration, b as BeforeQueryHook, A as AfterQueryHook, c as BeforeConnectHook, d as DatabaseOpenHook, e as DatabaseCloseHook } from './types-Dc8oWlxj.js';
+
+/** The outcome of taking one database offline.
+ * @internal
+ */
+type OfflineOutcome<T> = {
+    /** True when the action returned. */
+    ok: true;
+    /** The value that the action returned. */
+    value: T;
+    /** The error that the reopen threw, when it threw; the action's result is still valid. */
+    reopenFailure?: unknown;
+} | {
+    /** False when the action threw. */
+    ok: false;
+    /** The error that the action threw. */
+    failure: unknown;
+    /** The error that the reopen threw, when it threw. */
+    reopenFailure?: unknown;
+};
+
+/**
+ * A registry of open SQLite databases, keyed by identifier.
+ *
+ * The registry opens every database through one driver and applies its hooks, metrics, and migrations to each one; when you configure a lifecycle, it also closes idle databases.
+ *
+ * @public
+ */
+declare class Sirannon {
+    private readonly dbs;
+    private readonly openedWith;
+    private readonly offline;
+    private readonly offlineWork;
+    private readonly opening;
+    private readonly resolving;
+    private _shutdown;
+    private readonly _driver;
+    private readonly _hookRegistry;
+    private readonly metricsCollector;
+    private readonly lifecycleManager;
+    private readonly migrations;
+    /** The driver, hooks, metrics, lifecycle, migrations, and writer-worker and retention defaults that this registry was constructed with. */
+    readonly options: SirannonOptions;
+    /**
+     * Creates a registry.
+     *
+     * @param options - The driver, hooks, metrics, lifecycle, migrations, and the defaults for every database that the registry opens.
+     */
+    constructor(options: SirannonOptions);
+    /** @internal */
+    get driver(): SQLiteDriver;
+    /** @internal */
+    get hookRegistry(): HookRegistry;
+    /** @internal */
+    get metrics(): MetricsCollector | null;
+    /**
+     * Opens a database and registers it under an identifier.
+     *
+     * @param id - The identifier that callers use to reach this database.
+     * @param path - The file path of the SQLite database.
+     * @param options - The pool size, journal mode, synchronous level, and change-capture settings.
+     * @returns The open database.
+     * @throws A `DatabaseAlreadyExistsError` when the identifier is already in use, or `DATABASE_OPEN_FAILED` when the open or a registry migration fails.
+     */
+    open(id: string, path: string, options?: DatabaseOptions): Promise<Database>;
+    /**
+     * Closes one database and removes it from the registry.
+     *
+     * @param id - The identifier of the database to close.
+     */
+    close(id: string): Promise<void>;
+    /**
+     * Closes one database, calls an action on its file, and then opens that
+     * database again under the same identifier with its earlier settings.
+     *
+     * A restore rebuilds a database at its current path, so no connection may be
+     * open on that file while Sirannon replaces its bytes. {@link Sirannon.get}
+     * returns undefined for the identifier until the database is open again, and
+     * Sirannon reopens the database even after a failed action.
+     *
+     * @param id - The identifier of the database to take offline.
+     * @param action - The function that Sirannon calls with the database file path once the database is closed.
+     * @returns Whether the action returned, the value that it returned or the error that it threw, and any error that the reopen threw.
+     * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, or the close error when the close fails.
+     *
+     * @internal
+     */
+    withDatabaseOffline<T>(id: string, action: (path: string) => Promise<T>): Promise<OfflineOutcome<T>>;
+    /**
+     * Returns an already-open database.
+     *
+     * @param id - The identifier of the database.
+     * @returns The database, or undefined when none is open under that identifier.
+     */
+    get(id: string): Database | undefined;
+    /**
+     * Returns an open database, and opens it through the lifecycle resolver when it is not open yet.
+     *
+     * An in-process application calls this for a database that the registry opens on first use
+     * through the `lifecycle.autoOpen` resolver, such as one file per tenant. Concurrent calls for
+     * the same unopened identifier share one open, so each call receives the same database or the
+     * same error.
+     *
+     * @param id - The identifier of the database.
+     * @returns The database, or undefined when none is open and the resolver returns no path for it.
+     */
+    resolve(id: string): Promise<Database | undefined>;
+    /**
+     * Returns the registry's migration set, which Sirannon applies to each writable database as it opens.
+     *
+     * When the set comes from a function, the registry calls that function once and caches the
+     * result, so this returns the same list on every call; after a failed load, the next call
+     * tries again.
+     *
+     * @returns The migrations declared in `SirannonOptions.migrations`, or an empty list when there are none.
+     */
+    registryMigrations(): Promise<Migration[]>;
+    /**
+     * Returns whether a database is open under an identifier.
+     *
+     * @param id - The identifier to check.
+     * @returns True when the registry has an open database under that identifier.
+     */
+    has(id: string): boolean;
+    /**
+     * Returns every database that this registry has open.
+     *
+     * @returns A copy of the open databases, keyed by identifier.
+     */
+    databases(): Map<string, Database>;
+    /**
+     * Closes every open database and stops the lifecycle timers.
+     *
+     * When Sirannon is replacing a database's file, the shutdown waits for that
+     * work to finish, because a process that exits part-way through the
+     * replacement can leave no database at the path.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Registers a hook that Sirannon calls before each statement on every database in this registry; throw from the hook to reject the statement.
+     *
+     * @param hook - The hook, which Sirannon calls with the statement, its parameters, and its read or write concern.
+     * @returns A function that removes the hook.
+     */
+    onBeforeQuery(hook: BeforeQueryHook): HookDispose;
+    /**
+     * Registers a hook that Sirannon calls after each statement on every database in this registry.
+     *
+     * @param hook - The hook, which Sirannon calls with the statement and its duration.
+     * @returns A function that removes the hook.
+     */
+    onAfterQuery(hook: AfterQueryHook): HookDispose;
+    /**
+     * Registers a hook that Sirannon calls before it opens a database.
+     *
+     * @param hook - The hook, which Sirannon calls with the database identifier and file path.
+     * @returns A function that removes the hook.
+     */
+    onBeforeConnect(hook: BeforeConnectHook): HookDispose;
+    /**
+     * Registers a hook that Sirannon calls once a database is open.
+     *
+     * @param hook - The hook, which Sirannon calls with the database identifier and file path.
+     * @returns A function that removes the hook.
+     */
+    onDatabaseOpen(hook: DatabaseOpenHook): HookDispose;
+    /**
+     * Registers a hook that Sirannon calls once a database is closed.
+     *
+     * @param hook - The hook, which Sirannon calls with the database identifier and file path.
+     * @returns A function that removes the hook.
+     */
+    onDatabaseClose(hook: DatabaseCloseHook): HookDispose;
+    private ensureRunning;
+    private ensureOpenAllowed;
+}
+
+export { Sirannon as S };

package/dist/transport/grpc.d.ts

@@ -1,12 +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-CbjfRwrK.js';
-import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
-import '../change-tracker-CjRFuZdB.js';
-import '../types-DPSmjU54.js';
-import '../query-types-p1liOP-b.js';
-import '../types-B0EhgDbr.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-BrAiDGOb.js';
+import { R as ReplicationBatch } from '../types-DqODKeOq.js';
+import '../change-tracker-DqCdeEyx.js';
+import '../types-Dc8oWlxj.js';
+import '../query-types-5B02ixH0.js';
+import '../types-guEKSzMr.js';
 
 interface ColumnValue {
     nullValue?: boolean | undefined;
@@ -144,6 +144,8 @@ interface ForwardRequest {
     statements: Statement[];
     groupId: string;
     primaryTerm: bigint;
+    writeConcernLevel: string;
+    writeConcernTimeoutMs: number;
 }
 declare const ForwardRequest: MessageFns<ForwardRequest>;
 interface StatementResult {
@@ -157,6 +159,7 @@ interface ForwardResponse {
     error: string;
     groupId: string;
     primaryTerm: bigint;
+    errorCode: string;
 }
 declare const ForwardResponse: MessageFns<ForwardResponse>;
 type ReplicationService = typeof ReplicationService;
@@ -238,37 +241,37 @@ declare function toColumnValue(value: unknown): ColumnValue;
 declare function fromColumnValue(cv: ColumnValue): unknown;
 
 /**
- * Where the gRPC transport listens, and the certificates it presents and trusts.
+ * Sets the address that the gRPC transport listens on and the certificates that it presents and trusts.
  *
  * @public
  */
 interface GrpcReplicationOptions {
     /**
-     * Address the gRPC server binds to. Default: '0.0.0.0'.
+     * Sets the address that the gRPC server binds to. Defaults to '0.0.0.0'.
      */
     host?: string;
     /**
-     * Port the gRPC server binds to. Pass 0 to take any free port.
+     * Sets the port that the gRPC server binds to. The default, 0, lets the operating system pick a free port.
      */
     port?: number;
     /**
-     * Path to this node's certificate.
+     * Sets the path to this node's TLS certificate.
      */
     tlsCert?: string;
     /**
-     * Path to this node's private key.
+     * Sets the path to this node's private key.
      */
     tlsKey?: string;
     /**
-     * Path to the authority certificate this node verifies its peers against.
+     * Sets the path to the certificate authority certificate that this node verifies its peers against.
      */
     tlsCaCert?: string;
     /**
-     * Runs without TLS, which suits tests only.
+     * Turns off TLS. Use it only in tests.
      */
     insecure?: boolean;
     /**
-     * Milliseconds a forwarded write may take before the replica gives up. Default: 30000.
+     * Sets how many milliseconds a replica waits for a forwarded write before it fails the write. Defaults to 30000.
      */
     forwardDeadlineMs?: number;
 }
@@ -293,7 +296,8 @@ type SyncCompleteHandler = (complete: SyncComplete, fromPeerId: string) => Promi
 type SyncAckHandler = (ack: SyncAck, fromPeerId: string) => void;
 
 /**
- * Replicates between nodes over gRPC with mutual TLS, which is the transport production clusters use.
+ * Sends replication messages between nodes over gRPC. Unless you set `insecure`, it requires `tlsCert` and `tlsKey`,
+ * and when you also set `tlsCaCert`, each side of a connection verifies the other's certificate against it.
  *
  * @public
  */
@@ -342,12 +346,21 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     syncCompleteHandler: SyncCompleteHandler | null;
     /** @internal */
     syncAckHandler: SyncAckHandler | null;
+    private runtime;
     constructor(options?: GrpcReplicationOptions);
-    /** Returns the port the gRPC server bound to, which is the resolved port when you asked for 0. */
+    /**
+     * Returns the port that the gRPC server listens on, including the port that the operating system picks when `port`
+     * is 0, and 0 while no server is listening.
+     */
     getPort(): number;
-    /** Connects to the configured peers and announces this node. */
+    /**
+     * Loads the gRPC packages, starts the gRPC server when this node is the primary or has a group ID, and dials every
+     * configured endpoint.
+     *
+     * @throws A `SirannonError` with code `TRANSPORT_DEPENDENCY_MISSING` when this process cannot load `@grpc/grpc-js`, `@bufbuild/protobuf`, or `grpc-health-check`.
+     */
     connect(localNodeId: string, config: TransportConfig): Promise<void>;
-    /** Closes every peer connection. */
+    /** Closes every peer connection and shuts down the gRPC server. */
     disconnect(): Promise<void>;
     /** Sends one batch of changes to one peer. */
     send(peerId: string, batch: ReplicationBatch): Promise<void>;
@@ -361,15 +374,15 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     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. */
+    /** Tells a joining node that first sync is complete, and sends the manifests that the node checks its copy against. */
     sendSyncComplete(peerId: string, complete: SyncComplete): Promise<void>;
-    /** Confirms to the source that a joining node stored one first-sync page. */
+    /** Tells the source whether this 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. */
+    /** Registers the handler that executes a write that a replica forwards. */
     onForwardReceived(handler: ForwardHandler): void;
     /** Registers the handler that serves a first-sync request. */
     onSyncRequested(handler: SyncRequestHandler): void;
@@ -379,11 +392,11 @@ declare class GrpcReplicationTransport implements ReplicationTransport {
     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. */
+    /** Registers the handler that the transport calls when a peer connects. */
     onPeerConnected(handler: PeerConnectedHandler): void;
-    /** Registers the handler that runs when a peer disconnects. */
+    /** Registers the handler that the transport calls when a peer disconnects. */
     onPeerDisconnected(handler: PeerDisconnectedHandler): void;
-    /** Returns every connected peer, keyed by identifier. */
+    /** Returns every connected peer, keyed by node ID. */
     peers(): ReadonlyMap<string, NodeInfo>;
     private extractTlsCN;
     /** @internal */