@lix-js/sdk 0.16.0 → 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;
@@ -75,23 +84,90 @@ export type LixOpenReport = {
     initialized: boolean;
     migration?: LixOpenMigrationReport;
 };
+/** A retained local generation. Presence does not mean recovery is complete. */
+export type ReplicaRecoverySource = {
+    id: string;
+    sourceFormat: number;
+    repositoryId: string;
+    accountId: string;
+    recoveryRequired: boolean;
+};
+export type ReplicaRecoveryRow = {
+    rowPk: JsonValue;
+    schemaKey: string;
+    fileId: string | null;
+    snapshot: JsonValue;
+    metadata: JsonValue;
+    deleted: boolean;
+    untracked: boolean;
+    global: boolean;
+    changeId: string | null;
+    commitId: string | null;
+};
+export type ReplicaRecoveryBranch = {
+    branchId: string;
+    headCommitId: string;
+    checkpointCommitId: string | null;
+    rows: ReplicaRecoveryRow[];
+};
+export type ReplicaRecoveryBlob = {
+    id: string;
+    contentBase64: string;
+};
+export type ReplicaRecoveryFile = {
+    branchId: string;
+    id: string;
+    path: string;
+    untracked: boolean;
+    blobId: string | null;
+};
+/** Portable recovery data; unresolved entries identify data not reconstructed. */
+export type ReplicaRecoveryExport = {
+    version: number;
+    source: ReplicaRecoverySource;
+    branches: ReplicaRecoveryBranch[];
+    commits: JsonValue[];
+    uploads: JsonValue[];
+    blobs: ReplicaRecoveryBlob[];
+    files: ReplicaRecoveryFile[];
+    unresolved: string[];
+};
+/** Local recovery result. This does not acknowledge durable server storage. */
+export type ReplicaRecoveryReceipt = {
+    branchIds: string[];
+    restoredFiles: number;
+    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. */
@@ -135,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";
     /**
@@ -151,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}. */
@@ -164,7 +252,19 @@ export type ResultColumn = {
 export type ResultObjectRow = Record<string, unknown>;
 export type ResultArrayRow = unknown[];
 export type ResultRow = ResultObjectRow | ResultArrayRow;
-export type ExecuteResult<TRow extends object = ResultObjectRow> = {
+/**
+ * The active-branch commits a write moved between.
+ *
+ * `before` is the active branch's head before the write and `after` the head
+ * it published, so `lix_diff('lix_file', before, after)` is exactly what the
+ * write changed. A write that published no commit on the active branch
+ * reports both ids equal; a restore reports the commit it moved the head to.
+ */
+export type CommitSpan = {
+    before: string;
+    after: string;
+};
+export type StatementResult<TRow extends object = ResultObjectRow> = {
     statementIndex?: number;
     label?: string;
     columns: ResultColumn[];
@@ -176,9 +276,18 @@ export type ExecuteResult<TRow extends object = ResultObjectRow> = {
         hint?: string;
     }>;
 };
-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;
@@ -239,7 +348,6 @@ export type MergeBranchPreview = {
     targetHeadCommitId: string;
     sourceHeadCommitId: string;
     changeStats: MergeChangeStats;
-    conflicts: MergeConflict[];
 };
 export type MergeChangeStats = {
     total: number;
@@ -247,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;
@@ -13,17 +20,22 @@ export class WasmLix {
     createHosted(server: any): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     executeBatch(statements: any, options?: any | null): Promise<any>;
+    exportReplicaRecovery(id: string): Promise<any>;
     exportSnapshot(): WasmSnapshotExport;
     importFilesystemPaths(_paths: any): Promise<void>;
     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>;
 }
 
@@ -31,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>;
 }
@@ -56,16 +68,21 @@ export class WasmRemoteLix {
     createBranch(options: any): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     executeBatch(statements: any, options?: any | null): Promise<any>;
+    exportReplicaRecovery(_id: string): Promise<any>;
     exportSnapshot(): WasmSnapshotExport;
     importFilesystemPaths(_paths: any): Promise<void>;
     mergeBranch(options: any): Promise<any>;
     mergeBranchPreview(options: any): Promise<any>;
     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>;
 }
 
@@ -73,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>;
 }
@@ -109,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;
@@ -131,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;
@@ -146,17 +177,22 @@ export interface InitOutput {
     readonly wasmlix_createHosted: (a: number, b: number) => number;
     readonly wasmlix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly wasmlix_executeBatch: (a: number, b: number, c: number) => number;
+    readonly wasmlix_exportReplicaRecovery: (a: number, b: number, c: number) => number;
     readonly wasmlix_exportSnapshot: (a: number) => number;
     readonly wasmlix_importFilesystemPaths: (a: number, b: number) => number;
     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;
@@ -171,16 +207,21 @@ export interface InitOutput {
     readonly wasmremotelix_createBranch: (a: number, b: number) => number;
     readonly wasmremotelix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly wasmremotelix_executeBatch: (a: number, b: number, c: number) => number;
+    readonly wasmremotelix_exportReplicaRecovery: (a: number, b: number, c: number) => number;
     readonly wasmremotelix_exportSnapshot: (a: number) => number;
     readonly wasmremotelix_importFilesystemPaths: (a: number, b: number) => number;
     readonly wasmremotelix_mergeBranch: (a: number, b: number) => number;
     readonly wasmremotelix_mergeBranchPreview: (a: number, b: number) => number;
     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;
@@ -194,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_95597: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_95599: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_17533: (a: number, b: number, c: number) => number;
-    readonly __wasm_bindgen_func_elem_17532: (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;