@lix-js/sdk 0.6.0-preview.0 → 0.6.0-preview.2

package/dist/generated/builtin-schemas.js

@@ -52,30 +52,6 @@ export const LixActiveAccountSchema = {
     ],
     "additionalProperties": false
 };
-export const LixActiveVersionSchema = {
-    "x-lix-key": "lix_active_version",
-    "x-lix-version": "1",
-    "description": "Singleton tracking which version is currently checked out in the local runtime. Exactly one row exists at all times; writing to this surface is how clients switch versions.",
-    "x-lix-primary-key": [
-        "/id"
-    ],
-    "type": "object",
-    "properties": {
-        "id": {
-            "type": "string",
-            "description": "Fixed singleton key (constant, not a UUID); the primary-key column exists to satisfy entity-model requirements and enforces the one-row invariant."
-        },
-        "version_id": {
-            "type": "string",
-            "description": "The currently active version; references `lix_version_descriptor.id` and drives the default scope for reads and writes in the session."
-        }
-    },
-    "required": [
-        "id",
-        "version_id"
-    ],
-    "additionalProperties": false
-};
 export const LixBinaryBlobRefSchema = {
     "x-lix-key": "lix_binary_blob_ref",
     "x-lix-version": "1",
@@ -109,7 +85,7 @@ export const LixBinaryBlobRefSchema = {
 export const LixChangeSchema = {
     "x-lix-key": "lix_change",
     "x-lix-version": "1",
-    "description": "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts. The public `untracked` field is retained as convenience metadata and should not be treated as proof that trackedness is intrinsic to the canonical fact row itself.",
+    "description": "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts.",
     "x-lix-primary-key": [
         "/id"
     ],
@@ -139,13 +115,6 @@ export const LixChangeSchema = {
             ],
             "description": "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, versions, settings)."
         },
-        "plugin_key": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "Plugin that authored the change; NULL for engine-internal changes."
-        },
         "metadata": {
             "type": [
                 "object",
@@ -157,10 +126,6 @@ export const LixChangeSchema = {
             "type": "string",
             "description": "ISO-8601 timestamp at which the change was recorded (set via `lix_timestamp()` at write time)."
         },
-        "untracked": {
-            "type": "boolean",
-            "description": "Public convenience field indicating that the change currently participates in non-commit visibility rather than commit lineage. This is intended to become derived metadata rather than intrinsic canonical storage truth."
-        },
         "snapshot_content": {
             "type": [
                 "object",
@@ -175,9 +140,7 @@ export const LixChangeSchema = {
         "schema_key",
         "schema_version",
         "file_id",
-        "plugin_key",
-        "created_at",
-        "untracked"
+        "created_at"
     ],
     "additionalProperties": false
 };
@@ -248,7 +211,7 @@ export const LixChangeSetSchema = {
 export const LixChangeSetElementSchema = {
     "x-lix-key": "lix_change_set_element",
     "x-lix-version": "1",
-    "description": "Derived relational index mapping a change_set to the canonical changes it contains. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
+    "description": "Derived relational index mapping a change_set to the canonical changes introduced by its commit relative to the commit's first parent. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
     "x-lix-primary-key": [
         "/change_set_id",
         "/change_id"
@@ -293,7 +256,7 @@ export const LixChangeSetElementSchema = {
         },
         "change_id": {
             "type": "string",
-            "description": "The canonical change included in the change_set (references `lix_change.id`)."
+            "description": "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`)."
         },
         "entity_id": {
             "type": "string",
@@ -323,7 +286,7 @@ export const LixChangeSetElementSchema = {
 export const LixCommitSchema = {
     "x-lix-key": "lix_commit",
     "x-lix-version": "1",
-    "description": "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of non-header member changes for this commit. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.",
+    "description": "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of canonical changes whose effects this commit introduces relative to its first parent. A merge commit may reference canonical changes originally authored in another parent instead of copying them. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.",
     "x-lix-primary-key": [
         "/id"
     ],
@@ -357,7 +320,7 @@ export const LixCommitSchema = {
             "items": {
                 "type": "string"
             },
-            "description": "Canonical ordered membership list of non-header change IDs that belong to this commit. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows."
+            "description": "Canonical ordered membership list of non-header change IDs whose effects this commit introduces relative to its first parent. Merge commits may reference existing changes from another parent instead of minting equivalent copies. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows."
         },
         "author_account_ids": {
             "type": "array",
@@ -440,6 +403,19 @@ export const LixDirectoryDescriptorSchema = {
             "/name"
         ]
     ],
+    "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/parent_id"
+            ],
+            "references": {
+                "schemaKey": "lix_directory_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        }
+    ],
     "type": "object",
     "properties": {
         "id": {
@@ -540,10 +516,22 @@ export const LixFileDescriptorSchema = {
     "x-lix-unique": [
         [
             "/directory_id",
-            "/name",
-            "/extension"
+            "/name"
         ]
     ],
+    "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/directory_id"
+            ],
+            "references": {
+                "schemaKey": "lix_directory_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        }
+    ],
     "type": "object",
     "properties": {
         "id": {
@@ -558,14 +546,7 @@ export const LixFileDescriptorSchema = {
         },
         "name": {
             "type": "string",
-            "pattern": "^[^/\\\\]+$"
-        },
-        "extension": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "pattern": "^[^./\\\\]+$"
+            "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
         },
         "hidden": {
             "type": "boolean",
@@ -575,8 +556,7 @@ export const LixFileDescriptorSchema = {
     "required": [
         "id",
         "directory_id",
-        "name",
-        "extension"
+        "name"
     ],
     "additionalProperties": false
 };
@@ -681,12 +661,17 @@ export const LixVersionDescriptorSchema = {
     "x-lix-primary-key": [
         "/id"
     ],
+    "x-lix-unique": [
+        [
+            "/name"
+        ]
+    ],
     "type": "object",
     "properties": {
         "id": {
             "type": "string",
             "x-lix-default": "lix_uuid_v7()",
-            "description": "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id` and `lix_active_version.version_id`."
+            "description": "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id`."
         },
         "name": {
             "type": "string",
@@ -712,6 +697,17 @@ export const LixVersionRefSchema = {
         "/id"
     ],
     "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/id"
+            ],
+            "references": {
+                "schemaKey": "lix_version_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        },
         {
             "properties": [
                 "/commit_id"

package/dist/open-lix.d.ts

@@ -3,19 +3,34 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type LixRuntimeValue = JsonValue | Uint8Array | ArrayBuffer | Value;
-export type RowSet = {
+export type LixNativeValue = JsonValue | Uint8Array;
+export type ExecuteResult = {
     columns: string[];
-    rows: Value[][];
+    rows: Row[];
+    rowsAffected: number;
+    notices: LixNotice[];
 };
-export type ExecuteResult = {
-    kind: "rows";
-    rows: RowSet;
-} | {
-    kind: "affectedRows";
-    affectedRows: number;
+export type LixNotice = {
+    code: string;
+    message: string;
+    hint?: string;
 };
-export type TransactionBeginMode = "read" | "write" | "deferred";
-export type KvScanRange = {
+export declare class Row {
+    readonly columns: string[];
+    private readonly valuesByIndex;
+    constructor(columns: string[], values: Value[]);
+    get(columnName: string): LixNativeValue;
+    tryGet(columnName: string): LixNativeValue | undefined;
+    value(columnName: string): Value;
+    tryValue(columnName: string): Value | undefined;
+    getAt(index: number): LixNativeValue;
+    valueAt(index: number): Value;
+    values(): Value[];
+    toObject(): Record<string, LixNativeValue>;
+    toValueMap(): Record<string, Value>;
+    private availableColumns;
+}
+export type BackendKvScanRange = {
     kind: "prefix";
     prefix: Uint8Array;
 } | {
@@ -23,22 +38,78 @@ export type KvScanRange = {
     start: Uint8Array;
     end: Uint8Array;
 };
-export type KvPair = {
+export type BackendKvGetRequest = {
+    groups: BackendKvGetGroup[];
+};
+export type BackendKvGetGroup = {
+    namespace: string;
+    keys: Uint8Array[];
+};
+export type BackendKvValueBatch = {
+    groups: BackendKvValueGroup[];
+};
+export type BackendKvValueGroup = {
+    namespace: string;
+    values: Array<Uint8Array | null>;
+};
+export type BackendKvExistsBatch = {
+    groups: BackendKvExistsGroup[];
+};
+export type BackendKvExistsGroup = {
+    namespace: string;
+    exists: boolean[];
+};
+export type BackendKvScanRequest = {
+    namespace: string;
+    range: BackendKvScanRange;
+    after?: Uint8Array | null;
+    limit: number;
+};
+export type BackendKvKeyPage = {
+    keys: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvValuePage = {
+    values: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvEntryPage = {
+    keys: Uint8Array[];
+    values: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvPut = {
     key: Uint8Array;
     value: Uint8Array;
 };
-export type LixBackendTransaction = {
-    kvGet(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
-    kvScan(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
-    kvPut(namespace: string, key: Uint8Array, value: Uint8Array): void;
-    kvDelete(namespace: string, key: Uint8Array): void;
-    commit(): void;
+export type BackendKvWriteBatch = {
+    groups: BackendKvWriteGroup[];
+};
+export type BackendKvWriteGroup = {
+    namespace: string;
+    puts: BackendKvPut[];
+    deletes: Uint8Array[];
+};
+export type BackendKvWriteStats = {
+    puts: number;
+    deletes: number;
+    bytesWritten: number;
+};
+export type LixBackendReadTransaction = {
+    getValues(request: BackendKvGetRequest): BackendKvValueBatch;
+    existsMany(request: BackendKvGetRequest): BackendKvExistsBatch;
+    scanKeys(request: BackendKvScanRequest): BackendKvKeyPage;
+    scanValues(request: BackendKvScanRequest): BackendKvValuePage;
+    scanEntries(request: BackendKvScanRequest): BackendKvEntryPage;
     rollback(): void;
 };
+export type LixBackendWriteTransaction = LixBackendReadTransaction & {
+    writeKvBatch(batch: BackendKvWriteBatch): BackendKvWriteStats;
+    commit(): void;
+};
 export type LixBackend = {
-    beginTransaction(mode: TransactionBeginMode): LixBackendTransaction;
-    kvGet?(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
-    kvScan?(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
+    beginReadTransaction(): LixBackendReadTransaction;
+    beginWriteTransaction(): LixBackendWriteTransaction;
     close?(): void;
 };
 export type OpenLixOptions = {
@@ -47,9 +118,13 @@ export type OpenLixOptions = {
 export type CreateVersionOptions = {
     id?: string;
     name: string;
+    fromCommitId?: string;
 };
 export type CreateVersionResult = {
-    versionId: string;
+    id: string;
+    name: string;
+    hidden: boolean;
+    commitId: string;
 };
 export type SwitchVersionOptions = {
     versionId: string;
@@ -60,23 +135,65 @@ export type SwitchVersionResult = {
 export type MergeVersionOptions = {
     sourceVersionId: string;
 };
-export type MergeVersionOutcome = "alreadyUpToDate" | "mergeCommitted";
+export type MergeVersionOutcome = "alreadyUpToDate" | "fastForward" | "mergeCommitted";
 export type MergeVersionResult = {
+    /**
+     * How the merge was applied. `fastForward` advances the target ref without
+     * creating a merge commit, but can still make source changes visible.
+     */
     outcome: MergeVersionOutcome;
     targetVersionId: string;
     sourceVersionId: string;
-    mergeBaseCommitId: string | null;
+    baseCommitId: string;
     targetHeadBeforeCommitId: string;
     sourceHeadBeforeCommitId: string;
     targetHeadAfterCommitId: string;
     createdMergeCommitId: string | null;
-    appliedChangeCount: number;
+    changeStats: MergeChangeStats;
+};
+export type MergeVersionPreviewResult = {
+    outcome: MergeVersionOutcome;
+    targetVersionId: string;
+    sourceVersionId: string;
+    baseCommitId: string;
+    targetHeadCommitId: string;
+    sourceHeadCommitId: string;
+    changeStats: MergeChangeStats;
+    conflicts: MergeConflict[];
+};
+export type MergeChangeStats = {
+    total: number;
+    added: number;
+    modified: number;
+    removed: number;
+};
+export type MergeConflict = {
+    kind: "sameEntityChanged";
+    schemaKey: string;
+    entityId: string;
+    fileId: string | null;
+    target: MergeConflictSide;
+    source: MergeConflictSide;
+};
+export type MergeConflictSide = {
+    kind: "added" | "modified" | "removed";
+    beforeChangeId: string | null;
+    afterChangeId: string | null;
 };
 export type Lix = {
+    /**
+     * Executes one DataFusion SQL statement against this Lix session.
+     *
+     * This is not SQLite SQL. Use the DataFusion SQL dialect; positional
+     * placeholders are `$1`, `$2`, and so on. SQLite-specific catalog tables and
+     * transaction statements such as `sqlite_master`, `BEGIN`, and `COMMIT` are
+     * not available. Use `information_schema` for catalog inspection.
+     */
     execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
     activeVersionId(): Promise<string>;
     createVersion(options: CreateVersionOptions): Promise<CreateVersionResult>;
     switchVersion(options: SwitchVersionOptions): Promise<SwitchVersionResult>;
+    mergeVersionPreview(options: MergeVersionOptions): Promise<MergeVersionPreviewResult>;
     mergeVersion(options: MergeVersionOptions): Promise<MergeVersionResult>;
     close(): Promise<void>;
 };