@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/{client-base-CLWmH5Ln.d.ts → client-base-CmZO0v3m.d.ts}

@@ -1,27 +1,38 @@
-import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-1JHu8pid.js';
-import { R as ResultOp, a as LiveQuery } from './types-CL6piSnD.js';
-import { O as OperationRef, b as OperationArguments } from './operation-registry-9DcvxcE5.js';
-import { P as Params, R as ReadConcern, W as WriteConcern, h as ChangeEvent, Q as QueryOptions } from './types-zhnRXrsb.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-6KrSq2Hy.js';
-
-/** What a server announces: the capability tokens and the operation registry it serves. */
-interface CapabilityReport {
-    capabilities: string[];
-    registryDigest: string | undefined;
-}
+import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-Dab_Jvd_.js';
+import { R as ResultOp, a as LiveQuery } from './types-BCejqzNA.js';
+import { O as OperationRef, b as OperationArguments } from './operation-registry-hlbhqu7q.js';
+import { P as Params, R as ReadConcern, W as WriteConcern, C as ChangeEvent, Q as QueryOptions } from './query-types-DL3LtPvY.js';
+import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-rqANt-9Q.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);
-    read(refresh?: boolean): Promise<CapabilityReport>;
+    private read;
     registryDigest(refresh?: boolean): Promise<string | undefined>;
     assertSqlAccepted(): Promise<void>;
     private fetch;
@@ -43,7 +54,7 @@ interface SubscribeOptions {
     epoch?: string;
     /**
      * Declares that this device stages pulled changes durably and
-     * acknowledges staged sequences, so the server may pack several events
+     * 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.
      */
@@ -55,16 +66,33 @@ interface SubscribeOptions {
         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 {
     /**
@@ -75,39 +103,61 @@ interface Transport {
      * 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. */
+/** 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. */
+/** Builder for creating remote CDC subscriptions with optional filters.
+ * @public
+ */
 interface RemoteSubscriptionBuilder {
+    /** Narrows the subscription to rows whose columns equal the given values. */
     filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
+    /** Starts the subscription and calls back on each change. */
     subscribe(callback: (event: ChangeEvent) => 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}. */
+/** Options for {@link RemoteDatabase.loadAll}.
+ * @public
+ */
 interface LoadAllOptions {
     /**
      * Rows per batch sent to the server. Each batch is one request, so it must
@@ -120,27 +170,81 @@ interface LoadAllOptions {
 }
 /**
  * Proxy for a remote sirannon-db database. Mirrors the core
- * {@link Database} query interface with async methods that send
+ * `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(id: string, transport: Transport, capabilities: ServerCapabilityCheck, onDispose?: (() => void) | undefined);
+    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.
+     * @returns The live query, already subscribed.
+     */
     live<T = Record<string, unknown>>(name: string, args?: OperationArguments): 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.
+     * @returns The live query, already subscribed.
+     */
     live<Args, Row>(operation: OperationRef<Args, Row>, args: Args): Promise<LiveQuery<Row>>;
     /**
      * Execute multiple statements as a single atomic transaction.
      * Returns an array of results, one per statement.
      *
-     * The whole list travels in one request and commits or rolls back as a
+     * 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<{
@@ -159,10 +263,10 @@ declare class RemoteDatabase {
      * 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 load} for anything larger than a single request:
-     * it runs the finalize itself, so there is no checkpoint flag to forget.
+     * 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 rows
+     * 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.
      *
@@ -178,8 +282,8 @@ declare class RemoteDatabase {
     /**
      * 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 loadAll} for a dataset that spans more
-     * than one request, since it runs the finalize itself rather than relying on
+     * 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
@@ -202,6 +306,11 @@ declare class RemoteDatabase {
      * // 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;
     /**

package/dist/codegen/cli.mjs

@@ -1,8 +1,8 @@
-import { runCodegen } from '../chunk-TJF5GZSV.mjs';
-import '../chunk-JU64Y7HM.mjs';
+import { runCodegen } from '../chunk-VOSJBZ6Q.mjs';
+import '../chunk-SBL6GN43.mjs';
 import '../chunk-TUD5CJ76.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import '../chunk-PBRXXISQ.mjs';
 
 // src/codegen/cli.ts
 runCodegen(process.argv.slice(2)).catch((err) => {

package/dist/codegen/index.d.ts

@@ -1,30 +1,120 @@
-import { a as OperationRegistry } from '../operation-registry-9DcvxcE5.js';
-import '../types-zhnRXrsb.js';
+import { a as OperationRegistry } from '../operation-registry-hlbhqu7q.js';
+import '../query-types-DL3LtPvY.js';
 
+/**
+ * @public
+ *
+ * Version of the manifest format the generator writes.
+ */
 declare const OPERATION_MANIFEST_VERSION = 1;
+/**
+ * @public
+ *
+ * The arguments and columns of one registered operation, as code generation reads them.
+ */
 interface OperationShape {
+    /**
+     * Argument names the caller supplies.
+     */
     args: string[];
+    /**
+     * Argument names the server fills from the authenticated identity.
+     */
     identityArgs: string[];
+    /**
+     * Columns every row of a read carries, or null when the generator cannot tell.
+     */
     columns: string[] | null;
 }
+/**
+ * @public
+ *
+ * The reads and writes one database exposes by name.
+ */
 interface DatabaseManifest {
+    /**
+     * Registered reads, keyed by operation name.
+     */
     reads: Record<string, OperationShape>;
+    /**
+     * Registered writes, keyed by operation name.
+     */
     writes: Record<string, OperationShape>;
 }
+/**
+ * @public
+ *
+ * Every database's registered operations, in the form code generation reads.
+ */
 interface OperationManifest {
+    /**
+     * Version of the manifest format.
+     */
     version: number;
+    /**
+     * Digest of the registry, which a client compares against the server's.
+     */
     digest: string | undefined;
+    /**
+     * One manifest per database, keyed by database identifier.
+     */
     databases: Record<string, DatabaseManifest>;
 }
+/**
+ * @public
+ *
+ * Reads a registry and describes each operation's arguments and columns.
+ *
+ * @param registry - The registered operations to describe.
+ * @returns The manifest code generation renders types from.
+ */
 declare function buildOperationManifest<I>(registry: OperationRegistry<I>): OperationManifest;
+/**
+ * @public
+ *
+ * Reads the column names a SELECT statement produces.
+ *
+ * @param sql - The statement to inspect.
+ * @returns The column names, or null when the statement's columns cannot be read from its text.
+ */
 declare function selectColumns(sql: string): string[] | null;
 
+/**
+ * @public
+ *
+ * How the generated TypeScript is written.
+ */
 interface RenderOptions {
+    /**
+     * Package the generated file imports its types from. Default: `@delali/sirannon-db`.
+     */
     packageName?: string;
 }
+/**
+ * @public
+ *
+ * Renders typed references for every operation in a manifest.
+ *
+ * @param manifest - The operations to render.
+ * @param options - The package the generated file imports from.
+ * @returns The TypeScript source to write.
+ */
 declare function renderOperationTypes(manifest: OperationManifest, options?: RenderOptions): string;
 
+/**
+ * @public
+ *
+ * Usage text the code generator prints when its arguments do not parse.
+ */
 declare const CODEGEN_USAGE = "sirannon-codegen --registry <module> --out <file> [--manifest <file>] [--export <name>] [--package <name>]\n\nReads the operation registry a server is built from and writes the typed\nreferences a client calls it through. The registry module is imported, so run\nit under a loader that reads your source format when it is not JavaScript.";
+/**
+ * @public
+ *
+ * Runs the code generator: it loads a registry module, builds the manifest, and writes the typed references.
+ *
+ * @param argv - Command-line arguments, without the executable and script names.
+ * @throws When an argument is missing or the registry module cannot be loaded.
+ */
 declare function runCodegen(argv: readonly string[]): Promise<void>;
 
 export { CODEGEN_USAGE, type DatabaseManifest, OPERATION_MANIFEST_VERSION, type OperationManifest, type OperationShape, type RenderOptions, buildOperationManifest, renderOperationTypes, runCodegen, selectColumns };

package/dist/codegen/index.mjs

@@ -1,5 +1,5 @@
-export { CODEGEN_USAGE, OPERATION_MANIFEST_VERSION, buildOperationManifest, renderOperationTypes, runCodegen, selectColumns } from '../chunk-TJF5GZSV.mjs';
-import '../chunk-JU64Y7HM.mjs';
+export { CODEGEN_USAGE, OPERATION_MANIFEST_VERSION, buildOperationManifest, renderOperationTypes, runCodegen, selectColumns } from '../chunk-VOSJBZ6Q.mjs';
+import '../chunk-SBL6GN43.mjs';
 import '../chunk-TUD5CJ76.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import '../chunk-PBRXXISQ.mjs';