@lix-js/sdk 0.16.1 → 0.17.0

package/dist/types.d.ts

@@ -1,8 +1,14 @@
 export type RemoteLixFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /** A Lix protocol endpoint. Host URL for creation; repository URL for opening/deletion. */
 export type LixServerOptions = {
+    /** Defaults to remote SQL execution. Partial replicas require storage. */
+    mode?: "remote" | "partial_replica";
     url: string | URL;
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Network/telemetry adapter. Preserve the supplied credential headers;
+     * delegate actual I/O to `networkFetch` to preserve typed network failures.
+     * Injecting an account through hidden cookies or replacement credentials is unsupported.
+     */
     fetch?: RemoteLixFetch;
 };
 export type HostedLix = {
@@ -54,11 +60,14 @@ export type LixTelemetryOptions = {
     /** Read immediately before each serialized engine operation. */
     parentContext?(): LixTelemetryParentContext | undefined;
 };
-/** Stable phases emitted while a local repository is opened. */
+/** Stable phases emitted while a repository is opened. */
 export type LixOpenPhase = "inspecting" | "migrating" | "validating" | "opening" | "complete";
 /** One observational repository-open progress snapshot. */
 export type LixOpenProgress = {
     phase: LixOpenPhase;
+    /** Present for an upgrade owned by the remote authority. */
+    scope?: "authority";
+    /** May be unknown while waiting for a remote authority upgrade. */
     fromFormat?: number;
     toFormat: number;
     completed?: number;
@@ -130,23 +139,35 @@ export type ReplicaRecoveryReceipt = {
     restoredRows: number;
     unresolved: string[];
 };
+/** Local persistence policy. Buffered acknowledgement can lose saves on a crash. */
+export type Durability = "durable" | "buffered";
 export type LixOpenProgressOptions = {
-    /** Observes local inspection, automatic migration, and opening. */
+    /** Observes local or authority inspection, automatic migration, and opening. */
     onProgress?(progress: LixOpenProgress): void;
 };
-/** No options: memory. Storage: local. Server: remote. Storage + server: sync. */
+export type RemoteLixServerOptions = Omit<LixServerOptions, "mode"> & {
+    mode?: "remote";
+};
+export type PartialReplicaLixServerOptions = Omit<LixServerOptions, "mode"> & {
+    mode: "partial_replica";
+};
+/** Server defaults to remote. Partial replicas explicitly opt in and require storage. */
 export type OpenLixOptions = ({
     storage?: import("./storage-adapter.js").LixStorage;
+    /** Defaults to durable; applies to all local sessions and transactions. */
+    durability?: Durability;
     server?: never;
     telemetry?: LixTelemetryOptions;
-} & LixOpenProgressOptions) | {
+} & LixOpenProgressOptions) | ({
     storage?: never;
-    server: LixServerOptions;
+    /** Remote persistence is configured by the authority. */
+    durability?: never;
+    server: RemoteLixServerOptions;
     telemetry?: never;
-    onProgress?: never;
-} | ({
+} & LixOpenProgressOptions) | ({
     storage: import("./storage-adapter.js").LixStorage;
-    server: LixServerOptions;
+    durability?: Durability;
+    server: PartialReplicaLixServerOptions;
     telemetry?: LixTelemetryOptions;
 } & LixOpenProgressOptions);
 /** Selects the initial context for an additional independent session. */
@@ -190,6 +211,12 @@ export type JsonValue = null | boolean | number | string | readonly JsonValue[]
 export type SqlParam = JsonValue | Uint8Array | import("./value.js").Value;
 export type ExecuteOptions = {
     originKey?: string;
+    /**
+     * Caps whole automatic-transaction replays after conflict or snapshot expiry.
+     * Zero fails on the first failed attempt. Omit to retain default recovery budgets.
+     * Does not control explicit transactions, read recovery, or transport retries.
+     */
+    maxAutoCommitRetries?: number;
     /** Returns positional arrays instead of plain objects. Defaults to "object". */
     rowMode?: "object" | "array";
     /**
@@ -206,6 +233,12 @@ export type LixBatchStatement = {
 };
 export type LixBatchOptions = {
     originKey?: string;
+    /**
+     * Caps whole automatic-transaction replays after conflict or snapshot expiry.
+     * Zero fails on the first failed attempt. Omit to retain default recovery budgets.
+     * Does not control explicit transactions, read recovery, or transport retries.
+     */
+    maxAutoCommitRetries?: number;
     /** Returns positional arrays instead of plain objects. Defaults to "object". */
     rowMode?: "object" | "array";
     /** See {@link ExecuteOptions.idempotencyKey}. */
@@ -231,7 +264,7 @@ export type CommitSpan = {
     before: string;
     after: string;
 };
-export type ExecuteResult<TRow extends object = ResultObjectRow> = {
+export type StatementResult<TRow extends object = ResultObjectRow> = {
     statementIndex?: number;
     label?: string;
     columns: ResultColumn[];
@@ -242,19 +275,19 @@ export type ExecuteResult<TRow extends object = ResultObjectRow> = {
         message: string;
         hint?: string;
     }>;
-    /**
-     * Present on every auto-committed write statement, including `RETURNING`
-     * writes, and on every statement of a written batch (all carry the
-     * batch's one span, read statements included). Absent for read
-     * statements outside a written batch, read-only batches, statements
-     * inside an explicit transaction (whose commit is the write), and the
-     * first commit on a branch that had no head yet.
-     */
-    commit?: CommitSpan;
 };
-export type ExecuteBatchResult<TRow extends object = ResultObjectRow> = ExecuteResult<TRow> & {
+export type ExecuteResult<TRow extends object = ResultObjectRow> = StatementResult<TRow> & CommitReceipt;
+export type CommitReceipt = {
+    /** Exact durable transition for a committed write; null for reads. */
+    commit: CommitSpan | null;
+};
+export type ExecuteBatchStatementResult<TRow extends object = ResultObjectRow> = StatementResult<TRow> & {
     statementIndex: number;
 };
+export type ExecuteBatchResult<TRow extends object = ResultObjectRow> = {
+    results: readonly ExecuteBatchStatementResult<TRow>[];
+    commit: CommitSpan | null;
+};
 export type ObserveEvent = {
     sequence: number;
     mutationSequence: number;
@@ -315,7 +348,6 @@ export type MergeBranchPreview = {
     targetHeadCommitId: string;
     sourceHeadCommitId: string;
     changeStats: MergeChangeStats;
-    conflicts: MergeConflict[];
 };
 export type MergeChangeStats = {
     total: number;
@@ -323,15 +355,17 @@ export type MergeChangeStats = {
     modified: number;
     removed: number;
 };
-export type MergeConflict = {
-    kind: "sameRowChanged";
-    rowRef: string;
-    fileId: string | null;
-    target: MergeConflictSide;
-    source: MergeConflictSide;
-};
-export type MergeConflictSide = {
-    kind: "added" | "modified" | "removed";
-    beforeChangeId: string | null;
-    afterChangeId: string | null;
+/** Local partial-replica worker health. Running does not guarantee remote freshness. */
+export type SyncHealth = {
+    state: "inactive" | "running" | "stalled" | "failed" | "stopped";
+    appliedCursor: number | null;
+    observedCursor: number | null;
+    failures: Partial<Record<"descriptor" | "publication" | "upload" | "lease", {
+        code: string;
+        message: string;
+    }>>;
+    terminalError: {
+        code: string;
+        message: string;
+    } | null;
 };

package/dist/wasm/lix_js_sdk.d.ts

@@ -1,6 +1,13 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export class BrowserComponentHost {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    call(method: string, _arguments: string): string;
+}
+
 export class WasmLix {
     private constructor();
     free(): void;
@@ -19,14 +26,16 @@ export class WasmLix {
     mergeBranch(options: any): Promise<any>;
     mergeBranchPreview(options: any): Promise<any>;
     observe(sql: string, params: any): Promise<WasmObserveEvents>;
-    openAnotherSession(options: any): Promise<WasmLix>;
+    openAnotherSession(options: any, telemetry_dispatch?: Function | null): Promise<WasmLix>;
     openReport(): any;
     recoverReplica(id: string): Promise<any>;
+    recoverReplicaWithServer(id: string, server: any): Promise<any>;
     redo(): Promise<any>;
     replicaRecoverySources(): Promise<any>;
     setTelemetryParent(parent?: any | null): void;
     switchBranch(options: any): Promise<any>;
     syncDiskToLix(): Promise<void>;
+    syncHealth(): Promise<any>;
     undo(): Promise<any>;
 }
 
@@ -34,7 +43,7 @@ export class WasmLixTransaction {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    commit(): Promise<void>;
+    commit(): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     rollback(): Promise<void>;
 }
@@ -67,11 +76,13 @@ export class WasmRemoteLix {
     observe(sql: string, params: any): Promise<WasmRemoteObserveEvents>;
     openAnotherSession(options: any): Promise<WasmRemoteLix>;
     recoverReplica(_id: string): Promise<any>;
+    recoverReplicaWithServer(_id: string, _server: any): Promise<any>;
     redo(): Promise<any>;
     replicaRecoverySources(): Promise<any>;
     setTelemetryParent(_parent?: any | null): void;
     switchBranch(options: any): Promise<any>;
     syncDiskToLix(): Promise<void>;
+    syncHealth(): Promise<any>;
     undo(): Promise<any>;
 }
 
@@ -79,7 +90,7 @@ export class WasmRemoteLixTransaction {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    commit(): Promise<void>;
+    commit(): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     rollback(): Promise<void>;
 }
@@ -115,20 +126,31 @@ export function createHosted(server: any): Promise<any>;
 
 export function deleteHosted(server: any): Promise<void>;
 
-export function openJsStorage(provider: any, telemetry_dispatch?: Function | null, telemetry_parent?: any | null, server?: any | null, open_progress_dispatch?: Function | null): Promise<WasmLix>;
+/**
+ * Read-only routing metadata; available in the current-format runtime.
+ */
+export function inspectJsStorageRepository(provider: any): Promise<any>;
+
+export function openJsStorage(provider: any, telemetry_dispatch: Function | null | undefined, telemetry_parent: any | null | undefined, server: any | null | undefined, open_progress_dispatch: Function | null | undefined, component_dispatch: Function, durability?: string | null): Promise<WasmLix>;
 
-export function openJsStorageFromSnapshot(provider: any, telemetry_dispatch?: Function | null, telemetry_parent?: any | null, open_progress_dispatch?: Function | null): WasmSnapshotRestore;
+export function openJsStorageFromSnapshot(provider: any, telemetry_dispatch: Function | null | undefined, telemetry_parent: any | null | undefined, open_progress_dispatch: Function | null | undefined, component_dispatch: Function, durability?: string | null): WasmSnapshotRestore;
 
-export function openMemory(telemetry_dispatch?: Function | null, telemetry_parent?: any | null, server?: any | null, open_progress_dispatch?: Function | null): Promise<WasmLix>;
+export function openMemory(telemetry_dispatch: Function | null | undefined, telemetry_parent: any | null | undefined, server: any | null | undefined, open_progress_dispatch: Function | null | undefined, component_dispatch: Function, durability?: string | null): Promise<WasmLix>;
 
-export function openMemoryFromSnapshot(telemetry_dispatch?: Function | null, telemetry_parent?: any | null, open_progress_dispatch?: Function | null): WasmSnapshotRestore;
+export function openMemoryFromSnapshot(telemetry_dispatch: Function | null | undefined, telemetry_parent: any | null | undefined, open_progress_dispatch: Function | null | undefined, component_dispatch: Function, durability?: string | null): WasmSnapshotRestore;
 
 export function openRemote(url: string, fetch: Function, headers: any, initial_active_branch_id?: string | null): Promise<WasmRemoteLix>;
 
+/**
+ * Parse the engine SQL dialect for hosts that authorize public SQL.
+ */
+export function parseSqlScript(sql: string, provided_param_count: number): any;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_browsercomponenthost_free: (a: number, b: number) => void;
     readonly __wbg_wasmlix_free: (a: number, b: number) => void;
     readonly __wbg_wasmlixtransaction_free: (a: number, b: number) => void;
     readonly __wbg_wasmobserveevents_free: (a: number, b: number) => void;
@@ -137,13 +159,16 @@ export interface InitOutput {
     readonly __wbg_wasmremoteobserveevents_free: (a: number, b: number) => void;
     readonly __wbg_wasmsnapshotexport_free: (a: number, b: number) => void;
     readonly __wbg_wasmsnapshotrestore_free: (a: number, b: number) => void;
+    readonly browsercomponenthost_call: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly createHosted: (a: number) => number;
     readonly deleteHosted: (a: number) => number;
-    readonly openJsStorage: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly openJsStorageFromSnapshot: (a: number, b: number, c: number, d: number) => number;
-    readonly openMemory: (a: number, b: number, c: number, d: number) => number;
-    readonly openMemoryFromSnapshot: (a: number, b: number, c: number) => number;
+    readonly inspectJsStorageRepository: (a: number) => number;
+    readonly openJsStorage: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+    readonly openJsStorageFromSnapshot: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
+    readonly openMemory: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
+    readonly openMemoryFromSnapshot: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
     readonly openRemote: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
+    readonly parseSqlScript: (a: number, b: number, c: number, d: number) => void;
     readonly wasmlix_activeAccountId: (a: number) => number;
     readonly wasmlix_activeBranchId: (a: number) => number;
     readonly wasmlix_beginTransaction: (a: number) => number;
@@ -158,14 +183,16 @@ export interface InitOutput {
     readonly wasmlix_mergeBranch: (a: number, b: number) => number;
     readonly wasmlix_mergeBranchPreview: (a: number, b: number) => number;
     readonly wasmlix_observe: (a: number, b: number, c: number, d: number) => number;
-    readonly wasmlix_openAnotherSession: (a: number, b: number) => number;
+    readonly wasmlix_openAnotherSession: (a: number, b: number, c: number) => number;
     readonly wasmlix_openReport: (a: number, b: number) => void;
     readonly wasmlix_recoverReplica: (a: number, b: number, c: number) => number;
+    readonly wasmlix_recoverReplicaWithServer: (a: number, b: number, c: number, d: number) => number;
     readonly wasmlix_redo: (a: number) => number;
     readonly wasmlix_replicaRecoverySources: (a: number) => number;
     readonly wasmlix_setTelemetryParent: (a: number, b: number, c: number) => void;
     readonly wasmlix_switchBranch: (a: number, b: number) => number;
     readonly wasmlix_syncDiskToLix: (a: number) => number;
+    readonly wasmlix_syncHealth: (a: number) => number;
     readonly wasmlix_undo: (a: number) => number;
     readonly wasmlixtransaction_commit: (a: number) => number;
     readonly wasmlixtransaction_execute: (a: number, b: number, c: number, d: number, e: number) => number;
@@ -188,11 +215,13 @@ export interface InitOutput {
     readonly wasmremotelix_observe: (a: number, b: number, c: number, d: number) => number;
     readonly wasmremotelix_openAnotherSession: (a: number, b: number) => number;
     readonly wasmremotelix_recoverReplica: (a: number, b: number, c: number) => number;
+    readonly wasmremotelix_recoverReplicaWithServer: (a: number, b: number, c: number, d: number) => number;
     readonly wasmremotelix_redo: (a: number) => number;
     readonly wasmremotelix_replicaRecoverySources: (a: number) => number;
     readonly wasmremotelix_setTelemetryParent: (a: number, b: number) => void;
     readonly wasmremotelix_switchBranch: (a: number, b: number) => number;
     readonly wasmremotelix_syncDiskToLix: (a: number) => number;
+    readonly wasmremotelix_syncHealth: (a: number) => number;
     readonly wasmremotelix_undo: (a: number) => number;
     readonly wasmremotelixtransaction_commit: (a: number) => number;
     readonly wasmremotelixtransaction_execute: (a: number, b: number, c: number, d: number, e: number) => number;
@@ -206,10 +235,10 @@ export interface InitOutput {
     readonly wasmsnapshotrestore_finish: (a: number) => number;
     readonly wasmsnapshotrestore_isComplete: (a: number) => number;
     readonly wasmsnapshotrestore_write: (a: number, b: number, c: number) => number;
-    readonly __wasm_bindgen_func_elem_95812: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_95814: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_17860: (a: number, b: number, c: number) => number;
-    readonly __wasm_bindgen_func_elem_17859: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_99617: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_99619: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_20812: (a: number, b: number, c: number) => number;
+    readonly __wasm_bindgen_func_elem_20811: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;