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

package/dist/client-base-Cmd9EVme.d.ts

@@ -1,397 +0,0 @@
-import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-Bj5iJnjx.js';
-import { R as ResultOp, L as LiveQueryOptions, a as LiveQuery } from './types-DTO4CYhW.js';
-import { O as OperationRef, b as OperationArguments } from './operation-registry-oiPuSYI6.js';
-import { P as Params, R as ReadConcern, W as WriteConcern, C as ChangeEvent, Q as QueryOptions } from './query-types-p1liOP-b.js';
-import { Q as QueryResponse, E as ExecuteResponse, T as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-HI-nY8DD.js';
-
-/**
- * Message a client raises when the server accepts no SQL over the network.
- *
- * @internal
- */
-declare const SQL_REFUSED_MESSAGE = "This server does not accept SQL over the network. Call a registered operation by name, or start the server with acceptSql: true.";
-/**
- * Capability questions a remote database asks before it sends a statement.
- *
- * @public
- */
-interface ServerCapabilityCheck {
-    /** Throws when the server accepts no SQL over the network, so a client refuses to send any. */
-    assertSqlAccepted(): Promise<void>;
-    /** Reads the digest of the server's operation registry, or undefined when the server announces none. */
-    registryDigest(refresh?: boolean): Promise<string | undefined>;
-}
-/**
- * Reads and caches the capability report a server announces.
- *
- * @internal
- */
-declare class ServerCapabilities implements ServerCapabilityCheck {
-    private readonly resolveUrl;
-    private readonly headers;
-    private readonly requestTimeoutMs;
-    private pending;
-    constructor(resolveUrl: () => string | Promise<string>, headers: Record<string, string> | undefined, requestTimeoutMs?: number);
-    private read;
-    registryDigest(refresh?: boolean): Promise<string | undefined>;
-    assertSqlAccepted(): Promise<void>;
-    private fetch;
-}
-
-/** Optional behaviours for a CDC subscription.
- * @public
- */
-interface SubscribeOptions {
-    /**
-     * Receives the failure of a change callback, and the error raised by a change frame the
-     * client cannot decode. The subscription never waits for what the callback returns, so a
-     * throw and a rejection both arrive here. Sirannon drops whatever this reporter itself throws.
-     */
-    onError?: (error: Error) => void;
-    /**
-     * Invoked when a reconnect cannot replay missed changes because they fell
-     * outside the server's retained history. The subscription continues live
-     * from the current moment; treat any prior state as stale and re-read.
-     */
-    onReset?: () => void;
-    /** Identity of the device this subscription belongs to, which the server uses to withhold that device's own writes. */
-    deviceId?: string;
-    /** Tables one subscription covers, so a transaction spanning them arrives as one ascending stream. */
-    tables?: readonly string[];
-    /** Highest migration version this device has applied, which the server gates the subscription on. */
-    schemaVersion?: number;
-    /** Returns the sequence to resume from, read afresh on each reconnect so a durable cursor stays current. */
-    getResumeSeq?: () => bigint | undefined;
-    /** Sequence to resume after on the first subscribe. Where it is absent, the subscription starts live from now. */
-    sinceSeq?: bigint;
-    /** Change-log epoch the resume cursor belongs to, so a cursor from another database file forces a resync. */
-    epoch?: string;
-    /**
-     * Declares that this device stages pulled changes durably and
-     * acknowledges staged sequences so that the server may pack several events
-     * per frame and pace the delivery window continuously. Send only to a
-     * server that announces the `sync.staged-stream` capability.
-     */
-    stagedStream?: boolean;
-    /** Receives what the server confirmed on subscribe: the baseline sequence, the epoch, whether a resync is due, and the delivery window. */
-    onSubscribed?: (info: {
-        seq: bigint | undefined;
-        epoch: string | undefined;
-        resync: boolean;
-        maxUnacknowledgedChanges: number | undefined;
-    }) => void;
-}
-/**
- * Callbacks a transport delivers a live query's updates through.
- *
- * @public
- */
-interface LiveHandlers<T = Record<string, unknown>> {
-    /** Receives a complete replacement result set. */
-    onRows(rows: T[]): void;
-    /** Receives the individual edits that move the result set to its new state. */
-    onOps(ops: ResultOp<T>[]): void;
-    /** Called when the server starts re-reading the query. */
-    onRevalidating(): void;
-    /** Called when the query fails. */
-    onError(error: RemoteError): void;
-}
-/**
- * Reads the digest of the server's operation registry so that a client notices when
- * the registered operations behind a live query change.
- *
- * @public
- */
-type RegistryDigestSource = (refresh: boolean) => Promise<string | undefined>;
-/**
- * Transport layer for communicating with a sirannon-db server.
- * Each transport instance is bound to a specific database.
- *
- * @public
- */
-interface Transport {
-    /**
-     * Whether a read concern passed to {@link Transport.query} or
-     * {@link Transport.queryNamed} reaches the server. Topology routing applies
-     * the client-wide setting when it chooses a node, so it leaves this unset and
-     * a caller asking for a per-read concern is refused rather than served a read
-     * at another level.
-     */
-    readonly carriesReadConcern?: boolean;
-    /** Sends a read and returns its rows. */
-    query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
-    /** Sends one write. */
-    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
-    /** Sends several statements the server runs in one transaction. */
-    transaction(statements: Array<{
-        sql: string;
-        params?: Params;
-    }>): Promise<TransactionResponse>;
-    /** Sends one statement over many parameter sets, which the server runs in one transaction. */
-    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
-    /** Sends a bulk load, which the server runs at relaxed durability. */
-    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
-    /** Runs a registered read by name and returns its rows. */
-    queryNamed(name: string, args?: Record<string, unknown>, readConcern?: ReadConcern): Promise<QueryResponse>;
-    /** Runs a registered write by name. */
-    executeNamed(name: string, args?: Record<string, unknown>, writeConcern?: WriteConcern): Promise<TransactionResponse>;
-    /** Opens a live query on a registered read and delivers its updates to the handlers. */
-    liveSubscribe(name: string, args: Record<string, unknown> | undefined, handlers: LiveHandlers, registryDigest?: RegistryDigestSource): Promise<RemoteSubscription>;
-    /** Opens a change subscription on a watched table. */
-    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
-    /** Closes the transport and every subscription running on it. */
-    close(): void;
-}
-/** Handle for an active remote subscription.
- * @public
- */
-interface RemoteSubscription {
-    /** Ends the subscription, so the callback receives no further events. */
-    unsubscribe(): void;
-}
-/** Builder for creating remote CDC subscriptions with optional filters.
- * @public
- */
-interface RemoteSubscriptionBuilder {
-    /**
-     * Narrows the subscription to rows whose columns equal the given values.
-     *
-     * The filter reports membership of the matching set, so an update that moves a row
-     * into the set arrives as an insert carrying no `oldRow`, and one that moves a row
-     * out arrives as a delete carrying the old row and an empty `row`. An update that
-     * leaves the row in the set arrives unchanged, and one that never touches the set
-     * is not delivered. A synthesised event is indistinguishable from a real insert or
-     * delete, so read `type` as the row's arrival or departure from the filter.
-     *
-     * The subscriber chooses this filter, so it decides how much the server delivers,
-     * and an operator who needs to bound what a caller may read does that in the
-     * `authenticate` hook.
-     */
-    filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
-    /**
-     * Starts the subscription and calls back on each change.
-     *
-     * The subscription never waits for what your callback returns, so two calls to an
-     * asynchronous callback can overlap. Chain the work onto one promise where each change
-     * has to finish before the next one starts. A throw, and a rejection of what the callback
-     * returns, both reach `options.onError`.
-     *
-     * @typeParam T - Shape of the rows this table holds, which types `row` and `oldRow`.
-     * @param callback - Receives each change this subscription matches.
-     * @param options - Carries `onError` and the device-sync fields.
-     * @returns A handle whose `unsubscribe` ends the subscription.
-     */
-    subscribe<T = Record<string, unknown>>(callback: (event: ChangeEvent<T>) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
-}
-/**
- * Error originating from a remote sirannon-db server.
- * Carries the machine-readable error code from the server's error response.
- *
- * @public
- */
-declare class RemoteError extends Error {
-    /** Machine-readable code the server sent with the error. */
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-
-/** Options for {@link RemoteDatabase.loadAll}.
- * @public
- */
-interface LoadAllOptions {
-    /**
-     * Rows per batch sent to the server. Each batch is one request, so it must
-     * fit under the server's `maxBodyBytes`; widen that cap or lower this for
-     * wide rows. Default: 1000.
-     */
-    batchSize?: number;
-    /** Durability during the load. Default: 'off'. */
-    durability?: BulkLoadDurability;
-}
-/**
- * Proxy for a remote sirannon-db database. Mirrors the core
- * `Database` query interface with async methods that send
- * requests to the server via the configured transport.
- *
- * @public
- */
-declare class RemoteDatabase {
-    /**
-     * Identifier of the database on the server.
-     */
-    readonly id: string;
-    private readonly transport;
-    private readonly capabilities;
-    private readonly onDispose?;
-    constructor(
-    /**
-     * Identifier of the database on the server.
-     */
-    id: string, transport: Transport, capabilities: ServerCapabilityCheck, onDispose?: (() => void) | undefined);
-    /**
-     * Sends a read to the server and returns its rows.
-     *
-     * @param sql - The statement to run. The server refuses it unless it accepts SQL.
-     * @param params - Values bound to the statement, named or positional.
-     * @param options - Read concern for this statement.
-     * @returns The rows the server returned.
-     */
-    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
-    /**
-     * Runs a registered read by name and returns its rows.
-     *
-     * @param operation - Reference to the registered read, which carries its argument and row types.
-     * @param args - Arguments the read takes.
-     * @param options - Read concern for this statement.
-     * @returns The rows the server returned.
-     */
-    query<Args, Row>(operation: OperationRef<Args, Row>, args: Args, options?: QueryOptions): Promise<Row[]>;
-    private assertReadConcernReaches;
-    /**
-     * Sends one write to the server.
-     *
-     * @param sql - The statement to run. The server refuses it unless it accepts SQL.
-     * @param params - Values bound to the statement, named or positional.
-     * @returns How many rows changed, and the last inserted row id.
-     */
-    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
-    /**
-     * Runs a registered write by name.
-     *
-     * @param operation - Reference to the registered write, which carries its argument type.
-     * @param args - Arguments the write takes.
-     * @param writeConcern - Acknowledgements the write waits for.
-     * @returns One result per statement the operation ran.
-     */
-    execute<Args>(operation: OperationRef<Args, unknown>, args: Args, writeConcern?: WriteConcern): Promise<ExecuteResponse[]>;
-    /**
-     * Opens a live query on a registered read, which keeps its rows current as the tables behind it change.
-     *
-     * @param name - Name of the registered read.
-     * @param args - Arguments the read takes.
-     * @param options - Carries `onError`, which receives a failure of any listener on this query.
-     * @returns The live query, already subscribed.
-     */
-    live<T = Record<string, unknown>>(name: string, args?: OperationArguments, options?: LiveQueryOptions): Promise<LiveQuery<T>>;
-    /**
-     * Opens a live query on a registered read, which keeps its rows current as the tables behind it change.
-     *
-     * @param operation - Reference to the registered read, which carries its argument and row types.
-     * @param args - Arguments the read takes.
-     * @param options - Carries `onError`, which receives a failure of any listener on this query.
-     * @returns The live query, already subscribed.
-     */
-    live<Args, Row>(operation: OperationRef<Args, Row>, args: Args, options?: LiveQueryOptions): Promise<LiveQuery<Row>>;
-    /**
-     * Execute multiple statements as a single atomic transaction.
-     * Returns an array of results, one per statement.
-     *
-     * The whole list is sent in one request and commits or rolls back as a
-     * unit, so the client is never in the loop between statements.
-     */
-    transaction(statements: Array<{
-        sql: string;
-        params?: Params;
-    }>): Promise<ExecuteResponse[]>;
-    /**
-     * Run the same statement once per parameter set as a single atomic
-     * transaction that commits with one fsync. Returns one result per
-     * parameter set, in order. Use this for a burst of same-shape writes
-     * (an import, a bulk insert) that must all commit or all roll back.
-     */
-    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<ExecuteResponse[]>;
-    /**
-     * Load a whole dataset through the same statement, batching it into requests
-     * for you and paying the one fsyncing WAL checkpoint once, after the final
-     * batch. The configured durability is restored after every batch, so an
-     * import that stops partway never leaves the writer at the relaxed level.
-     * Prefer this over {@link RemoteDatabase.load} for anything larger than a single request:
-     * it finalises the load itself, so there is no checkpoint flag to forget.
-     *
-     * Accepts a synchronous or asynchronous iterable of parameter sets so that rows
-     * can stream from a file or the network without being held in memory at
-     * once. Returns the total rows loaded and changes applied.
-     *
-     * ```ts
-     * const summary = await db.loadAll(
-     *   'INSERT INTO events (id, payload) VALUES (?, ?)',
-     *   rowStream,
-     *   { batchSize: 5000, durability: 'off' },
-     * )
-     * ```
-     */
-    loadAll(sql: string, rows: Iterable<Params> | AsyncIterable<Params>, options?: LoadAllOptions): Promise<BulkLoadResult>;
-    /**
-     * Load one batch of rows through the same statement with writer durability
-     * relaxed for the duration, then restored before this resolves. This is the
-     * low-level primitive; prefer {@link RemoteDatabase.loadAll} for a dataset that spans more
-     * than one request, since it finalises the load itself rather than relying on
-     * a `checkpoint` flag.
-     *
-     * Returns the total rows loaded and changes applied. When splitting a dataset
-     * across many `load` calls by hand, pass `checkpoint: false` on every call
-     * but the last so the one fsyncing WAL checkpoint runs once at the end; the
-     * configured durability is restored after each call regardless.
-     */
-    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<BulkLoadResult>;
-    /**
-     * Start building a CDC subscription for the given table.
-     * Chain `.filter()` to narrow the events, then call `.subscribe()`
-     * with a callback to begin receiving real-time change events.
-     *
-     * ```ts
-     * const sub = await db
-     *   .on('orders')
-     *   .filter({ status: 'pending' })
-     *   .subscribe(event => console.log(event))
-     *
-     * // Later:
-     * sub.unsubscribe()
-     * ```
-     *
-     * Begins a change subscription on a watched table.
-     *
-     * @param table - Name of the watched table.
-     * @returns A builder you narrow with a filter and then subscribe to.
-     */
-    on(table: string): RemoteSubscriptionBuilder;
-    /**
-     * Close the transport for this database. After calling `close()`,
-     * all pending requests are rejected and new calls will throw.
-     */
-    close(): void;
-}
-
-interface TransportSettings {
-    transport: 'websocket' | 'http';
-    headers: Record<string, string> | undefined;
-    webSocketProtocols: string | string[] | undefined;
-    autoReconnect: boolean;
-    reconnectInterval: number;
-    requestTimeout: number | undefined;
-}
-/**
- * Opens one database handle per identifier and keeps it, so a later call for the same identifier returns the handle already open.
- */
-declare abstract class DatabaseClient {
-    protected readonly settings: TransportSettings;
-    private readonly databases;
-    private closed;
-    constructor(options?: ClientOptions);
-    /**
-     * Returns the handle a caller queries and writes one database through, opening it on the first call for that identifier.
-     *
-     * @param id - Identifier the server registered the database under.
-     * @returns The database handle, which stays open until the caller closes it.
-     */
-    database(id: string): RemoteDatabase;
-    protected createCapabilities(databaseId: string): ServerCapabilities;
-    /**
-     * Closes every database this client opened, which ends their transports and stops their subscriptions.
-     */
-    close(): void;
-    protected abstract createTransport(databaseId: string): Transport;
-    protected abstract resolveServerUrl(databaseId: string): string | Promise<string>;
-}
-
-export { DatabaseClient as D, type LiveHandlers as L, type RemoteSubscription as R, type SubscribeOptions as S, type Transport as T, type RemoteSubscriptionBuilder as a, type RegistryDigestSource as b, type LoadAllOptions as c, RemoteDatabase as d, RemoteError as e, SQL_REFUSED_MESSAGE as f, ServerCapabilities as g, type ServerCapabilityCheck as h };