@lix-js/sdk 0.12.3 → 0.15.0

package/dist/types.d.ts

@@ -1,36 +1,106 @@
-export type IndexedDbStorageOptions = {
-    /**
-     * Identifies one persistent Lix database within the current origin.
-     * A database name can be opened by only one Lix handle at a time.
-     */
-    name: string;
-};
 export type RemoteLixFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export type RemoteLixServerOptions = {
     mode: "remote";
+    /** Stable HTTPS locator whose path is exactly `/lix/{uuid}`. HTTP is loopback-only. */
     url: string | URL;
     headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     fetch?: RemoteLixFetch;
 };
+/**
+ * Opens a local native replica that synchronizes with the server in the
+ * background. Sync mode keeps the normal local storage/read path and works
+ * with browser storage such as OPFS as well as native storage.
+ */
+export type SyncLixServerOptions = {
+    mode: "sync";
+    /** Stable HTTPS locator whose path is exactly `/lix/{uuid}`. HTTP is loopback-only. */
+    url: string | URL;
+    /** Resolved for every browser sync request, including reconnect handshakes. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Browser fetch override. Functions cross the worker boundary through RPC. */
+    fetch?: RemoteLixFetch;
+};
+export type LixTelemetrySpanLink = {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    traceState?: string;
+};
+/** W3C/OpenTelemetry context used as the remote parent of engine root spans. */
+export type LixTelemetryParentContext = {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    traceState?: string;
+};
 export type LixTelemetrySpan = {
-    schemaVersion: 1;
+    schemaVersion: 3;
     name: string;
+    kind: "internal" | "server" | "client" | "producer" | "consumer";
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    traceState?: string;
+    parentSpanId?: string;
+    links?: LixTelemetrySpanLink[];
     startedAtUnixMs: number;
     durationMs: number;
-    status: "ok" | "error";
+    status: {
+        code: "unset" | "error" | "ok";
+        description?: string;
+    };
     attributes: Record<string, string | number | boolean>;
 };
 export type LixTelemetryOptions = {
     onSpan(span: LixTelemetrySpan): void;
+    /** Read immediately before each serialized engine operation. */
+    parentContext?(): LixTelemetryParentContext | undefined;
+};
+/** Stable phases emitted while a local repository is opened. */
+export type LixOpenPhase = "inspecting" | "migrating" | "validating" | "opening" | "complete";
+/** One observational repository-open progress snapshot. */
+export type LixOpenProgress = {
+    phase: LixOpenPhase;
+    fromFormat?: number;
+    toFormat: number;
+    completed?: number;
+    total?: number;
+};
+/** The automatic repository migration performed by an open, if any. */
+export type LixOpenMigrationReport = {
+    fromFormat: number;
+    toFormat: number;
+};
+/** Immutable facts about how a local Lix handle was opened. */
+export type LixOpenReport = {
+    format: number;
+    initialized: boolean;
+    migration?: LixOpenMigrationReport;
+};
+export type LixOpenProgressOptions = {
+    /** Observes local inspection, automatic migration, and opening. */
+    onProgress?(progress: LixOpenProgress): void;
 };
 export type OpenLixOptions = {
-    storage?: import("./storage-adapter.js").LixStorage | import("./open-lix.js").IndexedDbStorage;
+    storage?: import("./storage-adapter.js").LixStorage;
     server?: never;
     telemetry?: LixTelemetryOptions;
-} | {
+} & LixOpenProgressOptions | {
     storage?: never;
     server: RemoteLixServerOptions;
     telemetry?: never;
+    onProgress?: never;
+} | {
+    storage: import("./storage-adapter.js").LixStorage;
+    server: SyncLixServerOptions;
+    telemetry?: LixTelemetryOptions;
+} & LixOpenProgressOptions;
+/** Selects the initial context for an additional independent session. */
+export type OpenAnotherSessionOptions = {
+    /** Defaults to the current branch of the session opening it. */
+    branchId?: string;
+    /** Defaults to the current account. Remote sessions cannot override identity. */
+    accountId?: string;
 };
 export type LixValue = {
     kind: "null";
@@ -50,6 +120,9 @@ export type LixValue = {
 } | {
     kind: "jsonb";
     value: JsonValue;
+} | {
+    kind: "row_ref";
+    value: string;
 } | {
     kind: "timestamptz";
     value: string;
@@ -63,6 +136,8 @@ export type JsonValue = null | boolean | number | string | readonly JsonValue[]
 export type SqlParam = JsonValue | Uint8Array | import("./value.js").Value;
 export type ExecuteOptions = {
     originKey?: string;
+    /** Returns positional arrays instead of plain objects. Defaults to "object". */
+    rowMode?: "object" | "array";
     /**
      * Stable identity for one logical remote SQL mutation. Supply the same key
      * when retrying after a lost response; remote Lix generates one per call
@@ -77,14 +152,24 @@ export type LixBatchStatement = {
 };
 export type LixBatchOptions = {
     originKey?: string;
+    /** Returns positional arrays instead of plain objects. Defaults to "object". */
+    rowMode?: "object" | "array";
     /** See {@link ExecuteOptions.idempotencyKey}. */
     idempotencyKey?: string;
 };
-export type ExecuteResult = {
+export type ResultColumnType = LixValue["kind"];
+export type ResultColumn = {
+    name: string;
+    type: ResultColumnType;
+};
+export type ResultObjectRow = Record<string, unknown>;
+export type ResultArrayRow = unknown[];
+export type ResultRow = ResultObjectRow | ResultArrayRow;
+export type ExecuteResult<TRow extends object = ResultObjectRow> = {
     statementIndex?: number;
     label?: string;
-    columns: string[];
-    rows: RowLike[];
+    columns: ResultColumn[];
+    rows: TRow[];
     rowsAffected: number;
     notices: Array<{
         code: string;
@@ -92,30 +177,19 @@ export type ExecuteResult = {
         hint?: string;
     }>;
 };
-export type ExecuteBatchResult = ExecuteResult & {
+export type ExecuteBatchResult<TRow extends object = ResultObjectRow> = ExecuteResult<TRow> & {
     statementIndex: number;
 };
 export type ObserveEvent = {
     sequence: number;
     mutationSequence: number;
     /**
-     * The current result of the observed query. Remote observations reconcile
-     * the first frame of every stream through execute before publishing it, so
-     * reconnects cannot expose a stale server snapshot to consumers.
+     * The current result of the observed query. Remote rows and
+     * `mutationSequence` come from the same authoritative observation frame;
+     * reconnect frames are coalesced when their rows are unchanged.
      */
     result: ExecuteResult;
 };
-export type RowLike = {
-    get(column: string): unknown;
-    value(column: string): ValueLike;
-    toObject(): Record<string, unknown>;
-    toValueMap(): Record<string, ValueLike>;
-};
-export type ValueLike = {
-    readonly kind: LixValue["kind"];
-    toJS(): unknown;
-    asBytes(): Uint8Array | undefined;
-};
 export type CreateBranchOptions = {
     id?: string;
     name: string;
@@ -127,9 +201,6 @@ export type CreateBranchReceipt = {
     hidden: boolean;
     commitId: string;
 };
-export type CreateCheckpointReceipt = {
-    commitId: string;
-};
 export type UndoReceipt = {
     branchId: string;
     targetCommitId: string;
@@ -179,8 +250,7 @@ export type MergeChangeStats = {
 };
 export type MergeConflict = {
     kind: "sameRowChanged";
-    schemaKey: string;
-    rowPk: unknown;
+    rowRef: string;
     fileId: string | null;
     target: MergeConflictSide;
     source: MergeConflictSide;

package/dist/value.d.ts

@@ -9,6 +9,7 @@ export declare class Value {
     static real(value: number): Value;
     static text(value: string): Value;
     static jsonb(value: JsonValue): Value;
+    static rowRef(value: string): Value;
     static timestamptz(value: string): Value;
     static blob(value: Uint8Array): Value;
     static from(value: SqlParam): Value;

package/dist/value.js

@@ -25,6 +25,9 @@ export class Value {
     static jsonb(value) {
         return new Value({ kind: "jsonb", value });
     }
+    static rowRef(value) {
+        return new Value({ kind: "row_ref", value });
+    }
     static timestamptz(value) {
         return new Value({ kind: "timestamptz", value });
     }
@@ -122,6 +125,7 @@ function unwrapValue(value) {
         case "text":
         case "timestamptz":
         case "jsonb":
+        case "row_ref":
             return cloneJsonValue(value.value);
         case "blob":
             return new Uint8Array(value.value);
@@ -204,6 +208,10 @@ function validateExplicitValue(value) {
         case "jsonb":
             assertJsonSerializable(value.value, new WeakSet(), 0);
             return;
+        case "row_ref":
+            if (typeof value.value === "string" && isWellFormedString(value.value))
+                return;
+            break;
         case "timestamptz":
             if (typeof value.value === "string" && !Number.isNaN(Date.parse(value.value))) {
                 return;

package/dist/wasm/lix_js_sdk.d.ts

@@ -10,15 +10,19 @@ export class WasmLix {
     beginTransaction(): Promise<WasmLixTransaction>;
     close(): Promise<void>;
     createBranch(options: any): Promise<any>;
-    createCheckpoint(): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     executeBatch(statements: any, options?: any | null): Promise<any>;
-    exportSnapshot(): Promise<Uint8Array>;
+    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>;
+    openReport(): any;
     redo(): Promise<any>;
+    setTelemetryParent(parent?: any | null): void;
     switchBranch(options: any): Promise<any>;
+    syncDiskToLix(): Promise<void>;
     undo(): Promise<any>;
 }
 
@@ -37,15 +41,78 @@ export class WasmObserveEvents {
     [Symbol.dispose](): void;
     close(): void;
     next(): Promise<any>;
+    setTelemetryParent(parent?: any | null): void;
 }
 
-export function openIndexedDb(backend: any, telemetry_dispatch?: Function | null): Promise<WasmLix>;
+export class WasmRemoteLix {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    activeAccountId(): Promise<string>;
+    activeBranchId(): Promise<string>;
+    beginTransaction(): Promise<WasmRemoteLixTransaction>;
+    close(): Promise<void>;
+    createBranch(options: any): Promise<any>;
+    execute(sql: string, params: any, options?: any | null): Promise<any>;
+    executeBatch(statements: any, options?: any | null): 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>;
+    redo(): Promise<any>;
+    setTelemetryParent(_parent?: any | null): void;
+    switchBranch(options: any): Promise<any>;
+    syncDiskToLix(): Promise<void>;
+    undo(): Promise<any>;
+}
+
+export class WasmRemoteLixTransaction {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    commit(): Promise<void>;
+    execute(sql: string, params: any, options?: any | null): Promise<any>;
+    rollback(): Promise<void>;
+}
+
+export class WasmRemoteObserveEvents {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    close(): void;
+    next(): Promise<any>;
+    setTelemetryParent(_parent?: any | null): void;
+}
+
+export class WasmSnapshotExport {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): Promise<void>;
+    next(): Promise<Uint8Array | undefined>;
+}
+
+export class WasmSnapshotRestore {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): Promise<void>;
+    finish(): Promise<WasmLix>;
+    isComplete(): boolean;
+    write(chunk: Uint8Array): 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>;
+
+export function openJsStorageFromSnapshot(provider: any, telemetry_dispatch?: Function | null, telemetry_parent?: any | null, open_progress_dispatch?: Function | null): WasmSnapshotRestore;
 
-export function openMemory(telemetry_dispatch?: Function | null): Promise<WasmLix>;
+export function openMemory(telemetry_dispatch?: Function | null, telemetry_parent?: any | null, server?: any | null, open_progress_dispatch?: Function | null): Promise<WasmLix>;
 
-export function openMemoryFromSnapshot(telemetry_dispatch?: Function | null, snapshot?: Uint8Array | null): Promise<WasmLix>;
+export function openMemoryFromSnapshot(telemetry_dispatch?: Function | null, telemetry_parent?: any | null, open_progress_dispatch?: Function | null): WasmSnapshotRestore;
 
-export function parseSqlScript(sql: string, provided_param_count: number): any;
+export function openRemote(url: string, fetch: Function, headers: any, initial_active_branch_id?: string | null): Promise<WasmRemoteLix>;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
@@ -54,32 +121,74 @@ export interface InitOutput {
     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;
-    readonly openIndexedDb: (a: number, b: number) => number;
-    readonly openMemory: (a: number) => number;
+    readonly __wbg_wasmremotelix_free: (a: number, b: number) => void;
+    readonly __wbg_wasmremotelixtransaction_free: (a: number, b: number) => void;
+    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 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 parseSqlScript: (a: number, b: number, c: number, d: number) => void;
+    readonly openRemote: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
     readonly wasmlix_activeAccountId: (a: number) => number;
     readonly wasmlix_activeBranchId: (a: number) => number;
     readonly wasmlix_beginTransaction: (a: number) => number;
     readonly wasmlix_close: (a: number) => number;
     readonly wasmlix_createBranch: (a: number, b: number) => number;
-    readonly wasmlix_createCheckpoint: (a: 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_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_openReport: (a: number, b: number) => void;
     readonly wasmlix_redo: (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_undo: (a: number) => number;
     readonly wasmlixtransaction_commit: (a: number) => number;
     readonly wasmlixtransaction_execute: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly wasmlixtransaction_rollback: (a: number) => number;
     readonly wasmobserveevents_close: (a: number) => void;
     readonly wasmobserveevents_next: (a: number) => number;
-    readonly __wasm_bindgen_func_elem_119238: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_119240: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmobserveevents_setTelemetryParent: (a: number, b: number, c: number) => void;
+    readonly wasmremotelix_activeAccountId: (a: number) => number;
+    readonly wasmremotelix_activeBranchId: (a: number) => number;
+    readonly wasmremotelix_beginTransaction: (a: number) => number;
+    readonly wasmremotelix_close: (a: number) => number;
+    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_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_redo: (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_undo: (a: number) => number;
+    readonly wasmremotelixtransaction_commit: (a: number) => number;
+    readonly wasmremotelixtransaction_execute: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmremotelixtransaction_rollback: (a: number) => number;
+    readonly wasmremoteobserveevents_close: (a: number) => void;
+    readonly wasmremoteobserveevents_next: (a: number) => number;
+    readonly wasmremoteobserveevents_setTelemetryParent: (a: number, b: number) => void;
+    readonly wasmsnapshotexport_cancel: (a: number) => number;
+    readonly wasmsnapshotexport_next: (a: number) => number;
+    readonly wasmsnapshotrestore_cancel: (a: number) => number;
+    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_92635: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_92637: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_16813: (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;
@@ -88,18 +197,6 @@ export interface InitOutput {
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
 }
 
-export type SyncInitInput = BufferSource | WebAssembly.Module;
-
-/**
- * Instantiates the given `module`, which can either be bytes or
- * a precompiled `WebAssembly.Module`.
- *
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
- *
- * @returns {InitOutput}
- */
-export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
-
 /**
  * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
  * for everything else, calls `WebAssembly.instantiate` directly.