@lix-js/sdk 0.11.0 → 0.12.1

package/dist/open-lix.js

@@ -1,52 +1,15 @@
-import { localFilesystemAlreadyOpen, localFilesystemNotOpen, } from "./errors.js";
-import { ACTIVE_ACCOUNT_CLIENT_STATE_KEY, ACTIVE_BRANCH_CLIENT_STATE_KEY, openClientState, openStoredClientState, } from "./client-state.js";
 import { Lix } from "./lix.js";
+import { isLixStorage } from "./storage-adapter.js";
 export { Lix, LixTransaction, ObserveEvents } from "./lix.js";
-const openLocalFilesystems = new WeakMap();
-export class LocalFilesystem {
-    path;
-    lixDir;
-    syncAllFiles;
+const openStorages = new WeakSet();
+const openIndexedDbStorageNames = new Set();
+export class IndexedDbStorage {
+    name;
     constructor(options) {
-        if (!options ||
-            typeof options.path !== "string" ||
-            options.path.length === 0) {
-            throw new TypeError("LocalFilesystem requires a non-empty path");
+        if (!options || typeof options.name !== "string" || options.name.length === 0) {
+            throw new TypeError("IndexedDbStorage requires a non-empty name");
         }
-        if (options.lixDir !== undefined &&
-            (typeof options.lixDir !== "string" || options.lixDir.length === 0)) {
-            throw new TypeError("LocalFilesystem lixDir must be a non-empty string");
-        }
-        if (typeof options.syncAllFiles !== "boolean") {
-            throw new TypeError("LocalFilesystem syncAllFiles must be a boolean");
-        }
-        this.path = options.path;
-        this.lixDir = options.lixDir;
-        this.syncAllFiles = options.syncAllFiles;
-    }
-    async importPaths(paths) {
-        if (!Array.isArray(paths)) {
-            throw new TypeError("importPaths() paths must be an array");
-        }
-        for (const path of paths) {
-            if (typeof path !== "string" || path.length === 0) {
-                throw new TypeError("importPaths() paths must contain non-empty strings");
-            }
-            if (path.endsWith("/")) {
-                throw new TypeError("importPaths() paths must not end with a trailing slash");
-            }
-        }
-        await this.client("importPaths").importFilesystemPaths([...paths]);
-    }
-    async syncDiskToLix() {
-        return this.client("syncDiskToLix").syncDiskToLix();
-    }
-    client(operation) {
-        const client = openLocalFilesystems.get(this);
-        if (!client) {
-            throw localFilesystemNotOpen(operation);
-        }
-        return client;
+        this.name = options.name;
     }
 }
 export async function openLix(options = {}) {
@@ -63,116 +26,63 @@ export async function openLix(options = {}) {
     }
     if (options.server !== undefined) {
         const { openRemoteLixBinding } = await import("./remote/client.js");
-        if (options.storage === undefined) {
-            return new Lix(await openRemoteLixBinding(options.server));
-        }
-        assertSnapshotStorage(options.storage);
-        const clientState = await openStoredClientState({
-            storage: options.storage,
-            namespace: remoteClientStateNamespace(options.server.url),
-        });
-        const restoredBranchId = clientState.get(ACTIVE_BRANCH_CLIENT_STATE_KEY);
-        const restoredAccountId = clientState.get(ACTIVE_ACCOUNT_CLIENT_STATE_KEY);
-        let remoteBinding;
-        try {
-            try {
-                remoteBinding = await openRemoteLixBinding(options.server, {
-                    initialActiveBranchId: restoredBranchId,
-                    initialActiveAccountId: restoredAccountId,
-                });
-            }
-            catch (error) {
-                if (!restoredBranchId || !isBranchNotFoundError(error))
-                    throw error;
-                remoteBinding = await openRemoteLixBinding(options.server, {
-                    initialActiveAccountId: restoredAccountId,
-                });
-            }
-            const activeBranchId = await remoteBinding.activeBranchId();
-            const activeAccountId = await remoteBinding.activeAccountId();
-            if (activeBranchId !== restoredBranchId) {
-                await clientState.set(ACTIVE_BRANCH_CLIENT_STATE_KEY, activeBranchId);
-            }
-            if (activeAccountId !== restoredAccountId) {
-                await clientState.set(ACTIVE_ACCOUNT_CLIENT_STATE_KEY, activeAccountId);
-            }
-            return new Lix(remoteBinding, clientState);
-        }
-        catch (error) {
-            await remoteBinding?.close().catch(() => undefined);
-            await clientState.close().catch(() => undefined);
-            throw error;
+        if ("storage" in options && options.storage !== undefined) {
+            throw new TypeError("openLix() remote mode does not accept storage");
         }
+        return new Lix(await openRemoteLixBinding(options.server));
     }
     const { openLixWorkerBinding } = await import("./worker/client.js");
     if (options.storage === undefined) {
         return new Lix(await openLixWorkerBinding({ kind: "memory" }, undefined, options.telemetry));
     }
-    if (options.storage instanceof LocalFilesystem) {
+    if (isLixStorage(options.storage)) {
         const storage = options.storage;
-        if (openLocalFilesystems.has(storage)) {
-            throw localFilesystemAlreadyOpen();
+        if (openStorages.has(storage)) {
+            throw storageAlreadyOpen();
         }
-        openLocalFilesystems.set(storage, null);
+        openStorages.add(storage);
+        let binding;
+        const disconnect = () => {
+            storage.lixStorage.connect(undefined);
+            openStorages.delete(storage);
+        };
         try {
-            const binding = await openLixWorkerBinding({
-                kind: "localFilesystem",
-                path: storage.path,
-                lixDir: storage.lixDir,
-                syncAllFiles: storage.syncAllFiles,
-            }, () => openLocalFilesystems.delete(storage), options.telemetry);
-            openLocalFilesystems.set(storage, binding);
+            binding = await openLixWorkerBinding(storage.lixStorage.config, disconnect, options.telemetry);
+            storage.lixStorage.connect({
+                importFilesystemPaths: (paths) => binding.importFilesystemPaths(paths),
+                syncDiskToLix: () => binding.syncDiskToLix(),
+            });
             return new Lix(binding);
         }
         catch (error) {
-            openLocalFilesystems.delete(storage);
+            disconnect();
+            await binding?.close().catch(() => undefined);
             throw error;
         }
     }
-    if (isSnapshotStorage(options.storage)) {
-        const { openPersistentLixWorkerBinding } = await import("./worker/client.js");
-        const binding = await openPersistentLixWorkerBinding({
-            storage: options.storage,
-            namespace: "local",
-            telemetry: options.telemetry,
-        });
+    if (options.storage instanceof IndexedDbStorage) {
+        const storage = options.storage;
+        const databaseName = storage.name;
+        if (openIndexedDbStorageNames.has(databaseName)) {
+            throw new Error("IndexedDbStorage is already open");
+        }
+        openIndexedDbStorageNames.add(databaseName);
+        let binding;
         try {
-            const clientState = await openClientState({ binding });
-            return new Lix(binding, clientState);
+            binding = await openLixWorkerBinding({ kind: "indexedDb", name: databaseName }, () => openIndexedDbStorageNames.delete(databaseName), options.telemetry);
+            return new Lix(binding);
         }
         catch (error) {
-            await binding.close().catch(() => undefined);
+            openIndexedDbStorageNames.delete(databaseName);
+            await binding?.close().catch(() => undefined);
             throw error;
         }
     }
-    throw new TypeError("openLix() requires storage to be LocalFilesystem or a Lix snapshot storage adapter");
-}
-function isSnapshotStorage(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        typeof value.load === "function" &&
-        typeof value.save === "function");
-}
-function assertSnapshotStorage(value) {
-    if (!isSnapshotStorage(value)) {
-        throw new TypeError("openLix() remote storage must implement load() and save()");
-    }
-}
-function remoteClientStateNamespace(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        throw new TypeError("openLix() remote server url must be an absolute URL");
-    }
-    url.pathname = url.pathname.replace(/\/$/, "");
-    url.search = "";
-    url.hash = "";
-    return `remote:${url.href}`;
+    throw new TypeError("openLix() requires a Lix storage adapter or IndexedDbStorage");
 }
-function isBranchNotFoundError(error) {
-    return (error instanceof Error &&
-        "code" in error &&
-        error.code === "LIX_BRANCH_NOT_FOUND");
+function storageAlreadyOpen() {
+    const error = new Error("openLix() storage is already open; close the existing Lix or create a new storage adapter");
+    error.name = "LixError";
+    error.code = "LIX_STORAGE_IN_USE";
+    return error;
 }

package/dist/remote/client.d.ts

@@ -1,9 +1,8 @@
 import type { LixBinding } from "../binding-types.js";
 import type { RemoteLixServerOptions } from "../types.js";
-import { type RemoteHandshakeRequest } from "./protocol.js";
+import { type ServerProtocolHandshakeRequest } from "./server-protocol.js";
 type RemoteLixClientOptions = {
-    initialActiveBranchId?: RemoteHandshakeRequest["activeBranchId"];
-    initialActiveAccountId?: RemoteHandshakeRequest["activeAccountId"];
+    initialActiveBranchId?: ServerProtocolHandshakeRequest["activeBranchId"];
 };
 export declare function openRemoteLixBinding(options: RemoteLixServerOptions, clientOptions?: RemoteLixClientOptions): Promise<LixBinding>;
 export {};

package/dist/remote/client.js

@@ -1,4 +1,4 @@
-import { decodeExecuteBatchResult, decodeExecuteResult, decodeHandshake, decodeObserveEvent, encodeWireValue, errorFromResponseBody, protocolError, record, REMOTE_PROTOCOL_PATH, remoteError, } from "./protocol.js";
+import { decodeExecuteBatchResult, decodeExecuteResult, decodeHandshake, decodeObserveEvent, encodeWireValue, errorFromResponseBody, protocolError, record, SERVER_PROTOCOL_PATH, remoteError, } from "./server-protocol.js";
 import { readSseEvents } from "./sse.js";
 const OBSERVE_RETRY_BASE_MS = 100;
 const OBSERVE_RETRY_MAX_MS = 5_000;
@@ -32,7 +32,6 @@ class RemoteLixBinding {
     #fetch;
     #headers;
     #initialActiveBranchId;
-    #initialActiveAccountId;
     #observationHub;
     #requestBlobBases = new Map();
     #sessionId;
@@ -66,11 +65,6 @@ class RemoteLixBinding {
             throw new TypeError("initialActiveBranchId must be a non-empty string");
         }
         this.#initialActiveBranchId = clientOptions.initialActiveBranchId;
-        if (clientOptions.initialActiveAccountId !== undefined &&
-            clientOptions.initialActiveAccountId.length === 0) {
-            throw new TypeError("initialActiveAccountId must be a non-empty string");
-        }
-        this.#initialActiveAccountId = clientOptions.initialActiveAccountId;
         this.#observationHub = new RemoteObservationHub({
             openStream: (subscriptions, signal) => this.#requestObserveStream(subscriptions, signal),
             refreshObservation: (subscription) => this.#refreshObservation(subscription),
@@ -81,9 +75,6 @@ class RemoteLixBinding {
         if (this.#initialActiveBranchId !== undefined) {
             query.set("activeBranchId", this.#initialActiveBranchId);
         }
-        if (this.#initialActiveAccountId !== undefined) {
-            query.set("activeAccountId", this.#initialActiveAccountId);
-        }
         const path = query.size === 0 ? "" : `?${query}`;
         const handshake = decodeHandshake(await this.#requestJson(path, { method: "GET" }));
         this.#sessionId = handshake.sessionId;
@@ -225,7 +216,7 @@ class RemoteLixBinding {
             if (this.#activeBranchId === undefined) {
                 const handshake = decodeHandshake(await this.#requestJson("", { method: "GET" }));
                 if (handshake.sessionId !== this.#sessionId) {
-                    throw protocolError("remote handshake changed sessionId");
+                    throw protocolError("Lix Server Protocol handshake changed sessionId");
                 }
                 this.#activeBranchId = handshake.activeBranchId;
             }
@@ -238,7 +229,7 @@ class RemoteLixBinding {
             if (this.#activeAccountId === undefined) {
                 const handshake = decodeHandshake(await this.#requestJson("", { method: "GET" }));
                 if (handshake.sessionId !== this.#sessionId) {
-                    throw protocolError("remote handshake changed sessionId");
+                    throw protocolError("Lix Server Protocol handshake changed sessionId");
                 }
                 this.#activeAccountId = handshake.activeAccountId;
             }
@@ -1092,7 +1083,7 @@ function isRetryableObserveError(error) {
 function asObserveProtocolError(error, event) {
     if (error instanceof Error &&
         "code" in error &&
-        error.code === "LIX_REMOTE_PROTOCOL_ERROR") {
+        error.code === "LIX_SERVER_PROTOCOL_ERROR") {
         return error;
     }
     return protocolError(`remote observe ${event} event contains invalid data: ${errorMessage(error)}`);
@@ -1119,8 +1110,8 @@ function nativeValuesEqual(left, right) {
             return (right.kind === "blob" &&
                 left.blob.length === right.blob.length &&
                 left.blob.every((byte, index) => byte === right.blob[index]));
-        case "json":
-            return right.kind === "json" && jsonValuesEqual(left.value, right.value);
+        case "jsonb":
+            return right.kind === "jsonb" && jsonValuesEqual(left.value, right.value);
         default:
             return left.value === right.value;
     }
@@ -1152,21 +1143,22 @@ function stringArraysEqual(left, right) {
         left.every((value, index) => value === right[index]));
 }
 function protocolBaseUrl(value) {
-    let workspaceUrl;
+    let repositoryUrl;
     try {
-        workspaceUrl = new URL(value);
+        repositoryUrl = new URL(value);
     }
     catch {
         throw new TypeError("openLix() remote server url must be an absolute URL");
     }
-    if (workspaceUrl.protocol !== "http:" && workspaceUrl.protocol !== "https:") {
+    if (repositoryUrl.protocol !== "http:" &&
+        repositoryUrl.protocol !== "https:") {
         throw new TypeError("openLix() remote server url must use http or https");
     }
-    if (workspaceUrl.search || workspaceUrl.hash) {
+    if (repositoryUrl.search || repositoryUrl.hash) {
         throw new TypeError("openLix() remote server url must not contain a query or fragment");
     }
-    workspaceUrl.pathname = `${workspaceUrl.pathname.replace(/\/$/, "")}${REMOTE_PROTOCOL_PATH}`;
-    return workspaceUrl;
+    repositoryUrl.pathname = `${repositoryUrl.pathname.replace(/\/$/, "")}${SERVER_PROTOCOL_PATH}`;
+    return repositoryUrl;
 }
 function unsupportedRemoteOperation(operation) {
     return remoteError("LIX_UNSUPPORTED_REMOTE_OPERATION", `${operation} is not supported in remote mode`, { details: { operation } });

package/dist/remote/{protocol.d.ts → server-protocol.d.ts}

@@ -1,7 +1,7 @@
 import type { BindingExecuteResult, BindingObserveEvent } from "../binding-types.js";
 import type { NativeLixValue } from "../value.js";
-export declare const REMOTE_PROTOCOL_VERSION = 2;
-export declare const REMOTE_PROTOCOL_PATH = "/lix/v1/";
+export declare const SERVER_PROTOCOL_VERSION = 2;
+export declare const SERVER_PROTOCOL_PATH = "/lix/v1/";
 export type WireValue = {
     kind: "null";
     value: null;
@@ -18,8 +18,11 @@ export type WireValue = {
     kind: "text";
     value: string;
 } | {
-    kind: "json";
+    kind: "jsonb";
     value: unknown;
+} | {
+    kind: "timestamptz";
+    value: string;
 } | {
     kind: "blob";
     base64: string;
@@ -33,17 +36,16 @@ export type WireRequestBlobSplice = {
     insertBase64: string;
 };
 export type WireRequestValue = WireValue | WireRequestBlobSplice;
-export type RemoteHandshake = {
+export type ServerProtocolHandshake = {
     protocolVersion: number;
     activeBranchId: string;
     activeAccountId: string;
     sessionId: string;
 };
-export type RemoteHandshakeRequest = {
+export type ServerProtocolHandshakeRequest = {
     activeBranchId?: string;
-    activeAccountId?: string;
 };
-export type RemoteExecuteRequest = {
+export type ServerProtocolExecuteRequest = {
     sql: string;
     params: WireRequestValue[];
     options?: {
@@ -51,7 +53,7 @@ export type RemoteExecuteRequest = {
     };
     cacheBlobs?: true;
 };
-export type RemoteExecuteBatchRequest = {
+export type ServerProtocolExecuteBatchRequest = {
     statements: Array<{
         sql: string;
         params: WireRequestValue[];
@@ -62,7 +64,7 @@ export type RemoteExecuteBatchRequest = {
     };
     cacheBlobs?: true;
 };
-export type RemoteExecuteResponse = {
+export type ServerProtocolExecuteResponse = {
     columns: string[];
     rows: WireValue[][];
     rowsAffected: number;
@@ -72,80 +74,80 @@ export type RemoteExecuteResponse = {
         hint?: string;
     }>;
 };
-export type RemoteExecuteBatchResponse = RemoteExecuteResponse & {
+export type ServerProtocolExecuteBatchResponse = ServerProtocolExecuteResponse & {
     statementIndex: number;
     label?: string;
 };
-export type RemoteObserveRequest = {
+export type ServerProtocolObserveRequest = {
     sql: string;
     params: WireValue[];
 };
-export type RemoteObserveSubscription = RemoteObserveRequest & {
+export type ServerProtocolObserveSubscription = ServerProtocolObserveRequest & {
     id: string;
 };
-export type RemoteMultiplexObserveRequest = {
-    subscriptions: RemoteObserveSubscription[];
+export type ServerProtocolMultiplexObserveRequest = {
+    subscriptions: ServerProtocolObserveSubscription[];
 };
-type RemoteObserveEventBase = {
+type ServerProtocolObserveEventBase = {
     sequence: number;
     mutationSequence: number;
 };
-export type RemoteObserveBlobDelta = {
+export type ServerProtocolObserveBlobDelta = {
     kind: "single-blob-splice";
     baseSequence: number;
     prefixBytes: number;
     suffixBytes: number;
     insertBase64: string;
 };
-type RemoteObserveRowSplice = {
+type ServerProtocolObserveRowSplice = {
     kind: "row-splice";
     baseSequence: number;
     prefixRows: number;
     deleteRows: number;
     insertRows: WireValue[][];
 };
-type RemoteObserveDelta = RemoteObserveBlobDelta | RemoteObserveRowSplice;
-export type RemoteObserveEvent = RemoteObserveEventBase & ({
-    result: RemoteExecuteResponse;
+type ServerProtocolObserveDelta = ServerProtocolObserveBlobDelta | ServerProtocolObserveRowSplice;
+export type ServerProtocolObserveEvent = ServerProtocolObserveEventBase & ({
+    result: ServerProtocolExecuteResponse;
     delta?: never;
 } | {
     result?: never;
-    delta: RemoteObserveDelta;
+    delta: ServerProtocolObserveDelta;
 });
-export type RemoteMultiplexObserveEvent = RemoteObserveEvent & {
+export type ServerProtocolMultiplexObserveEvent = ServerProtocolObserveEvent & {
     subscriptionId: string;
 };
-export type RemoteCreateBranchRequest = {
+export type ServerProtocolCreateBranchRequest = {
     id?: string;
     name: string;
     fromCommitId?: string;
 };
-export type RemoteCreateBranchResponse = {
+export type ServerProtocolCreateBranchResponse = {
     id: string;
     name: string;
     hidden: boolean;
     commitId: string;
 };
-export type RemoteCreateCheckpointResponse = {
+export type ServerProtocolCreateCheckpointResponse = {
     commitId: string;
 };
-export type RemoteUndoResponse = {
+export type ServerProtocolUndoResponse = {
     branchId: string;
     targetCommitId: string;
     inverseCommitId: string;
 };
-export type RemoteRedoResponse = {
+export type ServerProtocolRedoResponse = {
     branchId: string;
     targetCommitId: string;
     replayCommitId: string;
 };
-export type RemoteSwitchBranchRequest = {
+export type ServerProtocolSwitchBranchRequest = {
     branchId: string;
 };
-export type RemoteSwitchBranchResponse = {
+export type ServerProtocolSwitchBranchResponse = {
     branchId: string;
 };
-export type RemoteErrorBody = {
+export type ServerProtocolErrorBody = {
     error: {
         code?: string;
         message?: string;
@@ -153,16 +155,16 @@ export type RemoteErrorBody = {
         details?: unknown;
     };
 };
-export type RemoteObserveErrorEvent = RemoteErrorBody & {
+export type ServerProtocolObserveErrorEvent = ServerProtocolErrorBody & {
     retryable?: boolean;
 };
-export type RemoteMultiplexObserveErrorEvent = RemoteObserveErrorEvent & {
+export type ServerProtocolMultiplexObserveErrorEvent = ServerProtocolObserveErrorEvent & {
     subscriptionId?: string;
 };
 export declare function encodeWireValue(value: NativeLixValue): WireValue;
 export declare function decodeExecuteResult(value: unknown): BindingExecuteResult;
 export declare function decodeExecuteBatchResult(value: unknown): BindingExecuteResult;
-export declare function decodeHandshake(value: unknown): RemoteHandshake;
+export declare function decodeHandshake(value: unknown): ServerProtocolHandshake;
 export declare function decodeObserveEvent(value: unknown, base?: BindingObserveEvent): BindingObserveEvent;
 export declare function remoteError(code: string, message: string, options?: {
     hint?: string;

package/dist/remote/{protocol.js → server-protocol.js}

@@ -1,5 +1,5 @@
-export const REMOTE_PROTOCOL_VERSION = 2;
-export const REMOTE_PROTOCOL_PATH = "/lix/v1/";
+export const SERVER_PROTOCOL_VERSION = 2;
+export const SERVER_PROTOCOL_PATH = "/lix/v1/";
 export function encodeWireValue(value) {
     switch (value.kind) {
         case "null":
@@ -12,8 +12,10 @@ export function encodeWireValue(value) {
             return { kind: "float", value: value.value };
         case "text":
             return { kind: "text", value: value.value };
-        case "json":
-            return { kind: "json", value: value.value };
+        case "jsonb":
+            return { kind: "jsonb", value: value.value };
+        case "timestamptz":
+            return { kind: "timestamptz", value: value.value };
         case "blob":
             return { kind: "blob", base64: bytesToBase64(value.blob) };
     }
@@ -70,24 +72,24 @@ export function decodeExecuteBatchResult(value) {
     };
 }
 export function decodeHandshake(value) {
-    const handshake = record(value, "remote handshake");
-    if (handshake.protocolVersion !== REMOTE_PROTOCOL_VERSION) {
-        throw protocolError(`unsupported remote protocol version: ${String(handshake.protocolVersion)}`);
+    const handshake = record(value, "Lix Server Protocol handshake");
+    if (handshake.protocolVersion !== SERVER_PROTOCOL_VERSION) {
+        throw protocolError(`unsupported Lix Server Protocol version: ${String(handshake.protocolVersion)}`);
     }
     if (typeof handshake.activeBranchId !== "string" ||
         handshake.activeBranchId.length === 0) {
-        throw protocolError("remote handshake requires activeBranchId");
+        throw protocolError("Lix Server Protocol handshake requires activeBranchId");
     }
     if (typeof handshake.activeAccountId !== "string" ||
         handshake.activeAccountId.length === 0) {
-        throw protocolError("remote handshake requires activeAccountId");
+        throw protocolError("Lix Server Protocol handshake requires activeAccountId");
     }
     if (typeof handshake.sessionId !== "string" ||
         !/^[\x21-\x7e]{1,256}$/.test(handshake.sessionId)) {
-        throw protocolError("remote handshake requires a valid sessionId");
+        throw protocolError("Lix Server Protocol handshake requires a valid sessionId");
     }
     return {
-        protocolVersion: REMOTE_PROTOCOL_VERSION,
+        protocolVersion: SERVER_PROTOCOL_VERSION,
         activeBranchId: handshake.activeBranchId,
         activeAccountId: handshake.activeAccountId,
         sessionId: handshake.sessionId,
@@ -240,11 +242,11 @@ export function remoteError(code, message, options = {}) {
     return error;
 }
 export function protocolError(message) {
-    return remoteError("LIX_REMOTE_PROTOCOL_ERROR", message);
+    return remoteError("LIX_SERVER_PROTOCOL_ERROR", message);
 }
 export function errorFromResponseBody(value, status) {
-    const body = record(value, "remote error response");
-    const rawError = record(body.error, "remote error response error");
+    const body = record(value, "Lix Server Protocol error response");
+    const rawError = record(body.error, "Lix Server Protocol error response error");
     return remoteError(typeof rawError.code === "string"
         ? rawError.code
         : "LIX_REMOTE_REQUEST_FAILED", typeof rawError.message === "string"
@@ -293,9 +295,14 @@ function decodeWireValue(value) {
                 throw protocolError("text wire value is invalid");
             }
             return { kind: "text", value: wire.value };
-        case "json":
-            assertJsonValue(wire.value, "json wire value");
-            return { kind: "json", value: wire.value };
+        case "jsonb":
+            assertJsonValue(wire.value, "jsonb wire value");
+            return { kind: "jsonb", value: wire.value };
+        case "timestamptz":
+            if (typeof wire.value !== "string") {
+                throw protocolError("timestamptz wire value is invalid");
+            }
+            return { kind: "timestamptz", value: wire.value };
         case "blob":
             if (typeof wire.base64 !== "string") {
                 throw protocolError("blob wire value is invalid");

package/dist/storage-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Operations exposed to a storage adapter while its Lix is open.
+ *
+ * This is intentionally narrower than the engine binding. Storage packages
+ * receive only the controls required to manage their own persistence layer.
+ */
+export type LixStorageConnection = {
+    importFilesystemPaths(paths: string[]): Promise<void>;
+    syncDiskToLix(): Promise<void>;
+};
+/** Engine configuration currently supported by external JavaScript storage packages. */
+export type LixStorageAdapterConfig = {
+    kind: "filesystem";
+    path: string;
+    syncAllFiles: boolean;
+};
+/**
+ * Protocol implemented by JavaScript storage packages accepted by `openLix()`.
+ *
+ * Applications normally use a concrete package such as
+ * `@lix-js/storage-filesystem` rather than implementing this directly.
+ */
+export type LixStorage = {
+    readonly lixStorage: {
+        readonly version: 1;
+        readonly config: LixStorageAdapterConfig;
+        connect(connection: LixStorageConnection | undefined): void;
+    };
+};
+export declare function isLixStorage(value: unknown): value is LixStorage;

package/dist/storage-adapter.js

@@ -0,0 +1,12 @@
+export function isLixStorage(value) {
+    if (!value || typeof value !== "object" || !("lixStorage" in value)) {
+        return false;
+    }
+    const adapter = value.lixStorage;
+    return Boolean(adapter &&
+        typeof adapter === "object" &&
+        adapter.version === 1 &&
+        typeof adapter.connect === "function" &&
+        adapter.config?.kind ===
+            "filesystem");
+}