@delali/sirannon-db 0.1.7 → 0.2.0

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

@@ -0,0 +1,234 @@
+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;
+}
+
+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.";
+interface ServerCapabilityCheck {
+    assertSqlAccepted(): Promise<void>;
+    registryDigest(refresh?: boolean): Promise<string | undefined>;
+}
+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>;
+    registryDigest(refresh?: boolean): Promise<string | undefined>;
+    assertSqlAccepted(): Promise<void>;
+    private fetch;
+}
+
+/** Optional behaviours for a CDC subscription. */
+interface SubscribeOptions {
+    /**
+     * 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;
+    deviceId?: string;
+    tables?: readonly string[];
+    schemaVersion?: number;
+    getResumeSeq?: () => bigint | undefined;
+    sinceSeq?: bigint;
+    epoch?: string;
+    /**
+     * Declares that this device stages pulled changes durably and
+     * acknowledges staged sequences, so 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;
+    onSubscribed?: (info: {
+        seq: bigint | undefined;
+        epoch: string | undefined;
+        resync: boolean;
+        maxUnacknowledgedChanges: number | undefined;
+    }) => void;
+}
+interface LiveHandlers<T = Record<string, unknown>> {
+    onRows(rows: T[]): void;
+    onOps(ops: ResultOp<T>[]): void;
+    onRevalidating(): void;
+    onError(error: RemoteError): void;
+}
+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.
+ */
+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;
+    query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    transaction(statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<TransactionResponse>;
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    queryNamed(name: string, args?: Record<string, unknown>, readConcern?: ReadConcern): Promise<QueryResponse>;
+    executeNamed(name: string, args?: Record<string, unknown>, writeConcern?: WriteConcern): Promise<TransactionResponse>;
+    liveSubscribe(name: string, args: Record<string, unknown> | undefined, handlers: LiveHandlers, registryDigest?: RegistryDigestSource): Promise<RemoteSubscription>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
+    close(): void;
+}
+/** Handle for an active remote subscription. */
+interface RemoteSubscription {
+    unsubscribe(): void;
+}
+/** Builder for creating remote CDC subscriptions with optional filters. */
+interface RemoteSubscriptionBuilder {
+    filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
+    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.
+ */
+declare class RemoteError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+/** Options for {@link RemoteDatabase.loadAll}. */
+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
+ * {@link Database} query interface with async methods that send
+ * requests to the server via the configured transport.
+ */
+declare class RemoteDatabase {
+    readonly id: string;
+    private readonly transport;
+    private readonly capabilities;
+    private readonly onDispose?;
+    constructor(id: string, transport: Transport, capabilities: ServerCapabilityCheck, onDispose?: (() => void) | undefined);
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    query<Args, Row>(operation: OperationRef<Args, Row>, args: Args, options?: QueryOptions): Promise<Row[]>;
+    private assertReadConcernReaches;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    execute<Args>(operation: OperationRef<Args, unknown>, args: Args, writeConcern?: WriteConcern): Promise<ExecuteResponse[]>;
+    live<T = Record<string, unknown>>(name: string, args?: OperationArguments): Promise<LiveQuery<T>>;
+    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
+     * 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 load} for anything larger than a single request:
+     * it runs the finalize itself, so there is no checkpoint flag to forget.
+     *
+     * Accepts a synchronous or asynchronous iterable of parameter sets, so 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 loadAll} for a dataset that spans more
+     * than one request, since it runs the finalize 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()
+     * ```
+     */
+    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;
+}
+declare abstract class DatabaseClient {
+    protected readonly settings: TransportSettings;
+    private readonly databases;
+    private closed;
+    constructor(options?: ClientOptions);
+    database(id: string): RemoteDatabase;
+    protected createCapabilities(databaseId: string): ServerCapabilities;
+    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 };

package/dist/codegen/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/codegen/cli.mjs

@@ -0,0 +1,11 @@
+import { runCodegen } from '../chunk-TJF5GZSV.mjs';
+import '../chunk-JU64Y7HM.mjs';
+import '../chunk-TUD5CJ76.mjs';
+import '../chunk-GVCNMPOS.mjs';
+import '../chunk-UC3SCMIN.mjs';
+
+// src/codegen/cli.ts
+runCodegen(process.argv.slice(2)).catch((err) => {
+  process.exitCode = 1;
+  console.error(err instanceof Error ? err.message : String(err));
+});

package/dist/codegen/index.d.ts

@@ -0,0 +1,30 @@
+import { a as OperationRegistry } from '../operation-registry-9DcvxcE5.js';
+import '../types-zhnRXrsb.js';
+
+declare const OPERATION_MANIFEST_VERSION = 1;
+interface OperationShape {
+    args: string[];
+    identityArgs: string[];
+    columns: string[] | null;
+}
+interface DatabaseManifest {
+    reads: Record<string, OperationShape>;
+    writes: Record<string, OperationShape>;
+}
+interface OperationManifest {
+    version: number;
+    digest: string | undefined;
+    databases: Record<string, DatabaseManifest>;
+}
+declare function buildOperationManifest<I>(registry: OperationRegistry<I>): OperationManifest;
+declare function selectColumns(sql: string): string[] | null;
+
+interface RenderOptions {
+    packageName?: string;
+}
+declare function renderOperationTypes(manifest: OperationManifest, options?: RenderOptions): string;
+
+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.";
+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

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

package/dist/core/index.d.ts

@@ -1,12 +1,16 @@
-import { g as BulkLoadDurability, e as SQLiteConnection, s as SynchronousLevel, h as BulkLoadResult, a as SQLiteDriver, t as WorkerHostOptions, D as DatabaseOptions, L as LifecycleConfig, P as Params, E as ExecuteResult } from '../types-D_hQW1hr.js';
-export { A as AfterQueryHook, f as BackupScheduleOptions, u as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, l as BeforeSubscribeHook, q as BulkLoadOptions, o as CDCMetrics, C as ChangeEvent, v as ChangeOperation, w as ClientOptions, x as ClusterReadEndpointInfo, y as ClusterStatusInfo, k as ConnectionHookContext, n as ConnectionMetrics, z as CorsOptions, d as DatabaseCloseHook, c as DatabaseOpenHook, F as DriverCapabilities, G as DriverWorkerEntry, H as HookConfig, M as MetricsConfig, O as OnRequestHook, I as OpenOptions, Q as QueryHookContext, m as QueryMetrics, p as QueryOptions, R as ReadConcern, J as ReadConcernLevel, K as ReplicationStatusInfo, N as RequestContext, U as RequestDenial, V as RunResult, X as SQLiteStatement, Y as ServerExecutionTarget, Z as ServerExecutionTargetResolver, i as ServerOptions, S as SirannonOptions, _ as Subscription, r as SubscriptionBuilder, T as Transaction, j as WSHandlerOptions, W as WriteConcern, $ as WriteConcernLevel, a0 as WriterWorkerOptions } from '../types-D_hQW1hr.js';
-export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-CbmaMO-N.js';
-import { D as Database } from '../database-DuGp0Rtr.js';
-export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-DuGp0Rtr.js';
-export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-5Nf5ZAEC.js';
-import { M as Migration, a as MigrationResult, R as RollbackResult } from '../types-D4p4UyDK.js';
-export { A as AppliedMigration, b as AppliedMigrationEntry } from '../types-D4p4UyDK.js';
-export { S as Sirannon } from '../sirannon-4SspRvP5.js';
+import { e as SQLiteConnection, s as SynchronousLevel, a as SQLiteDriver, t as WorkerHostOptions, P as Params, E as ExecuteResult, D as DatabaseOptions, L as LifecycleConfig, M as Migration, q as MigrationResult, r as RollbackResult } from '../types-zhnRXrsb.js';
+export { A as AfterQueryHook, u as AppliedMigration, v as AppliedMigrationEntry, f as BackupScheduleOptions, w as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, k as BeforeSubscribeHook, o as CDCMetrics, h as ChangeEvent, x as ChangeOperation, y as ClusterReadEndpointInfo, C as ClusterStatusInfo, j as ConnectionHookContext, n as ConnectionMetrics, d as DatabaseCloseHook, c as DatabaseOpenHook, z as DriverCapabilities, F as DriverWorkerEntry, H as HookConfig, G as MIGRATION_NAME_RE, l as MetricsConfig, I as MigrationBaseline, J as MigrationSource, N as NodeHealth, K as NodeHealthReason, O as NodeHealthState, U as OpenOptions, i as QueryHookContext, m as QueryMetrics, Q as QueryOptions, R as ReadConcern, g as ReadConcernLevel, V as RunResult, X as SQLiteStatement, S as SirannonOptions, Y as Subscription, p as SubscriptionBuilder, T as Transaction, W as WriteConcern, Z as WriteConcernLevel, _ as WriterWorkerOptions } from '../types-zhnRXrsb.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-1JHu8pid.js';
+export { c as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, R as ReplicationStatusInfo, f as RequestContext, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-1JHu8pid.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DKRVUC3l.js';
+import { D as Database } from '../database-BY0L5Q2n.js';
+export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-BY0L5Q2n.js';
+export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, d as RequestDeniedError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-Bw5MdNCu.js';
+export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-CL6piSnD.js';
+import { B as BaselineFileOption } from '../baseline-Br77Fnhb.js';
+export { S as Sirannon } from '../sirannon-DaQSyhbJ.js';
+export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-9DcvxcE5.js';
+import '../types-C_D8IhpO.js';
 
 declare function isBulkLoadDurability(value: unknown): value is BulkLoadDurability;
 interface BulkLoadRun {
@@ -81,6 +85,11 @@ declare class ConnectionPool {
     close(): Promise<void>;
 }
 
+declare function query<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T[]>;
+declare function queryOne<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T | undefined>;
+declare function execute(conn: SQLiteConnection, sql: string, params?: Params, trusted?: boolean): Promise<ExecuteResult>;
+declare function executeBatch(conn: SQLiteConnection, sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
+
 declare function defineDriver(config: SQLiteDriver): SQLiteDriver;
 
 declare const DEFAULT_SYNCHRONOUS: SynchronousLevel;
@@ -128,16 +137,28 @@ declare function createTenantResolver(options: TenantResolverOptions): (id: stri
     options?: DatabaseOptions;
 } | undefined;
 
+declare const MIGRATION_FILENAME_PATTERN: RegExp;
+interface ParsedMigrationFilename {
+    version: number;
+    name: string;
+    direction: 'up' | 'down';
+}
+declare function parseMigrationFilename(filename: string): ParsedMigrationFilename | null;
+
+interface MigrationsFromFilesOptions {
+    baseline?: BaselineFileOption;
+}
+declare function migrationsFromFiles(files: Record<string, unknown>, options?: MigrationsFromFilesOptions): Migration[];
+
 declare class MigrationRunner {
     static run(conn: SQLiteConnection, migrations: Migration[]): Promise<MigrationResult>;
+    private static retryOnConcurrentConflict;
+    private static applyPending;
     static rollback(conn: SQLiteConnection, migrations: Migration[], version?: number): Promise<RollbackResult>;
+    private static resolveDownMigration;
     private static validateMigrations;
-    private static getAppliedVersions;
+    private static highestVersion;
+    private static getAppliedRows;
 }
 
-declare function query<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T[]>;
-declare function queryOne<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T | undefined>;
-declare function execute(conn: SQLiteConnection, sql: string, params?: Params): Promise<ExecuteResult>;
-declare function executeBatch(conn: SQLiteConnection, sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
-
-export { BulkLoadDurability, BulkLoadResult, ConnectionPool, type ConnectionPoolOptions, DEFAULT_SYNCHRONOUS, Database, DatabaseOptions, ExecuteResult, type LifecycleCallbacks, LifecycleConfig, LifecycleManager, Migration, MigrationResult, MigrationRunner, Params, RollbackResult, SQLiteConnection, SQLiteDriver, SynchronousLevel, type TenantResolverOptions, createTenantResolver, defineDriver, execute, executeBatch, isBulkLoadDurability, isSynchronousLevel, query, queryOne, runBulkLoad, sanitizeTenantId, synchronousPragmaValue, tenantPath };
+export { BaselineFileOption, BulkLoadDurability, BulkLoadResult, ConnectionPool, type ConnectionPoolOptions, DEFAULT_SYNCHRONOUS, Database, DatabaseOptions, ExecuteResult, type LifecycleCallbacks, LifecycleConfig, LifecycleManager, MIGRATION_FILENAME_PATTERN, Migration, MigrationResult, MigrationRunner, type MigrationsFromFilesOptions, Params, type ParsedMigrationFilename, RollbackResult, SQLiteConnection, SQLiteDriver, SynchronousLevel, type TenantResolverOptions, createTenantResolver, defineDriver, execute, executeBatch, isBulkLoadDurability, isSynchronousLevel, migrationsFromFiles, parseMigrationFilename, query, queryOne, runBulkLoad, sanitizeTenantId, synchronousPragmaValue, tenantPath };