@lix-js/sdk 0.6.0-preview.4 → 0.6.0-preview.5

package/dist-engine-src/src/untracked_state/types.rs

@@ -1,4 +1,4 @@
-use crate::entity_identity::EntityIdentity;
+use crate::entity_pk::EntityPk;
 use crate::NullableKeyFilter;
 
 /// Durable local row excluded from changelog and commit membership.
@@ -7,7 +7,7 @@ use crate::NullableKeyFilter;
 /// directly, and mutable JSON payloads are stored inline in the sidecar row.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct UntrackedStateRow {
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) entity_pk: EntityPk,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
     pub(crate) snapshot_content: Option<String>,
@@ -15,13 +15,13 @@ pub(crate) struct UntrackedStateRow {
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
-    pub(crate) version_id: String,
+    pub(crate) branch_id: String,
 }
 
 impl UntrackedStateRow {
     pub(crate) fn as_ref(&self) -> UntrackedStateRowRef<'_> {
         UntrackedStateRowRef {
-            entity_id: &self.entity_id,
+            entity_pk: &self.entity_pk,
             schema_key: &self.schema_key,
             file_id: self.file_id.as_deref(),
             snapshot_content: self.snapshot_content.as_deref(),
@@ -29,7 +29,7 @@ impl UntrackedStateRow {
             created_at: &self.created_at,
             updated_at: &self.updated_at,
             global: self.global,
-            version_id: &self.version_id,
+            branch_id: &self.branch_id,
         }
     }
 }
@@ -40,7 +40,7 @@ impl UntrackedStateRow {
 /// without making untracked_state depend on transaction or live-state types.
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct UntrackedStateRowRef<'a> {
-    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) entity_pk: &'a EntityPk,
     pub(crate) schema_key: &'a str,
     pub(crate) file_id: Option<&'a str>,
     pub(crate) snapshot_content: Option<&'a str>,
@@ -48,13 +48,13 @@ pub(crate) struct UntrackedStateRowRef<'a> {
     pub(crate) created_at: &'a str,
     pub(crate) updated_at: &'a str,
     pub(crate) global: bool,
-    pub(crate) version_id: &'a str,
+    pub(crate) branch_id: &'a str,
 }
 
 /// Hydrated boundary shape for callers that still work with JSON payloads.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub(crate) struct MaterializedUntrackedStateRow {
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) entity_pk: EntityPk,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
     pub(crate) snapshot_content: Option<String>,
@@ -63,32 +63,32 @@ pub(crate) struct MaterializedUntrackedStateRow {
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
-    pub(crate) version_id: String,
+    pub(crate) branch_id: String,
 }
 
 /// Stable identity for one local untracked overlay row.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub(crate) struct UntrackedStateIdentity {
-    pub(crate) version_id: String,
+    pub(crate) branch_id: String,
     pub(crate) schema_key: String,
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) entity_pk: EntityPk,
     pub(crate) file_id: Option<String>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct UntrackedStateIdentityRef<'a> {
-    pub(crate) version_id: &'a str,
+    pub(crate) branch_id: &'a str,
     pub(crate) schema_key: &'a str,
-    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) entity_pk: &'a EntityPk,
     pub(crate) file_id: Option<&'a str>,
 }
 
 impl UntrackedStateIdentity {
     pub(crate) fn as_ref(&self) -> UntrackedStateIdentityRef<'_> {
         UntrackedStateIdentityRef {
-            version_id: &self.version_id,
+            branch_id: &self.branch_id,
             schema_key: &self.schema_key,
-            entity_id: &self.entity_id,
+            entity_pk: &self.entity_pk,
             file_id: self.file_id.as_deref(),
         }
     }
@@ -97,9 +97,9 @@ impl UntrackedStateIdentity {
 impl<'a> From<UntrackedStateRowRef<'a>> for UntrackedStateIdentityRef<'a> {
     fn from(row: UntrackedStateRowRef<'a>) -> Self {
         Self {
-            version_id: row.version_id,
+            branch_id: row.branch_id,
             schema_key: row.schema_key,
-            entity_id: row.entity_id,
+            entity_pk: row.entity_pk,
             file_id: row.file_id,
         }
     }
@@ -111,9 +111,9 @@ pub(crate) struct UntrackedStateFilter {
     #[serde(default)]
     pub(crate) schema_keys: Vec<String>,
     #[serde(default)]
-    pub(crate) entity_ids: Vec<EntityIdentity>,
+    pub(crate) entity_pks: Vec<EntityPk>,
     #[serde(default)]
-    pub(crate) version_ids: Vec<String>,
+    pub(crate) branch_ids: Vec<String>,
     #[serde(default)]
     pub(crate) file_ids: Vec<NullableKeyFilter<String>>,
 }
@@ -140,7 +140,7 @@ pub(crate) struct UntrackedStateScanRequest {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct UntrackedStateRowRequest {
     pub(crate) schema_key: String,
-    pub(crate) version_id: String,
-    pub(crate) entity_id: EntityIdentity,
+    pub(crate) branch_id: String,
+    pub(crate) entity_pk: EntityPk,
     pub(crate) file_id: NullableKeyFilter<String>,
 }

package/package.json

@@ -1,69 +1,72 @@
 {
-	"name": "@lix-js/sdk",
-	"type": "module",
-	"version": "0.6.0-preview.4",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"files": [
-		"dist",
-		"dist-engine-src",
-		"SKILL.md"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"default": "./dist/index.js"
-		},
-		"./sqlite": {
-			"types": "./dist/sqlite/index.d.ts",
-			"default": "./dist/sqlite/index.js"
-		}
-	},
-	"description": "WASM-backed JS SDK wrapper for Lix",
-	"scripts": {
-		"build": "node ./scripts/build.js",
-		"sync:builtin-schemas": "node ./scripts/sync-builtin-schemas.js",
-		"sync:engine-src": "node ./scripts/sync-engine-src.js",
-		"prepack": "node ./scripts/sync-engine-src.js",
-		"typecheck": "pnpm run sync:builtin-schemas && tsc -p tsconfig.json --noEmit",
-		"test": "node ./scripts/build.js && vitest run",
-		"test:watch": "node ./scripts/build.js && vitest"
-	},
-	"peerDependencies": {
-		"better-sqlite3": "^12.9.0"
-	},
-	"peerDependenciesMeta": {
-		"better-sqlite3": {
-			"optional": true
-		}
-	},
-	"devDependencies": {
-		"better-sqlite3": "^12.9.0",
-		"typescript": "^5.5.4",
-		"vitest": "^4.0.18"
-	},
-	"nx": {
-		"targets": {
-			"build": {
-				"inputs": [
-					"default",
-					"^default",
-					"publicEnv",
-					"nodeVersion",
-					"platform",
-					"{workspaceRoot}/Cargo.toml",
-					"{workspaceRoot}/Cargo.lock",
-					"{workspaceRoot}/packages/engine/**/*",
-					"{workspaceRoot}/packages/rs-sdk/**/*",
-					"{workspaceRoot}/packages/js-sdk/Cargo.toml",
-					"{workspaceRoot}/packages/js-sdk/wasm-bindgen.rs"
-				],
-				"outputs": [
-					"{projectRoot}/dist",
-					"{projectRoot}/dist-engine-src",
-					"{projectRoot}/src/engine-wasm/wasm"
-				]
-			}
-		}
-	}
-}
+  "name": "@lix-js/sdk",
+  "type": "module",
+  "version": "0.6.0-preview.5",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "dist-engine-src",
+    "SKILL.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite/index.d.ts",
+      "default": "./dist/sqlite/index.js"
+    }
+  },
+  "description": "WASM-backed JS SDK wrapper for Lix",
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "^12.9.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "better-sqlite3": "^12.10.0",
+    "typescript": "^5.5.4",
+    "vitest": "^4.0.18"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": [
+          "default",
+          "^default",
+          "publicEnv",
+          "nodeVersion",
+          "platform",
+          "{workspaceRoot}/Cargo.toml",
+          "{workspaceRoot}/Cargo.lock",
+          "{workspaceRoot}/packages/engine/**/*",
+          "{workspaceRoot}/packages/rs-sdk/**/*",
+          "{workspaceRoot}/packages/js-sdk/Cargo.toml",
+          "{workspaceRoot}/packages/js-sdk/wasm-bindgen.rs"
+        ],
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/dist-engine-src",
+          "{projectRoot}/src/engine-wasm/wasm"
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "node ./scripts/build.js",
+    "sync:builtin-schemas": "node ./scripts/sync-builtin-schemas.js",
+    "sync:engine-src": "node ./scripts/sync-engine-src.js",
+    "typecheck": "pnpm run sync:builtin-schemas && tsc -p tsconfig.json --noEmit",
+    "test": "node ./scripts/build.js && vitest run",
+    "test:watch": "node ./scripts/build.js && vitest",
+    "format": "prettier --write --ignore-unknown ."
+  }
+}

package/dist-engine-src/src/backend/kv.rs

@@ -1,358 +0,0 @@
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
-pub struct BytePage {
-    bytes: Vec<u8>,
-    offsets: Vec<u32>,
-}
-
-impl BytePage {
-    pub fn new() -> Self {
-        Self {
-            bytes: Vec::new(),
-            offsets: vec![0],
-        }
-    }
-
-    pub fn len(&self) -> usize {
-        self.offsets.len().saturating_sub(1)
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.len() == 0
-    }
-
-    pub fn get(&self, index: usize) -> Option<&[u8]> {
-        let start = usize::try_from(*self.offsets.get(index)?).ok()?;
-        let end = usize::try_from(*self.offsets.get(index + 1)?).ok()?;
-        self.bytes.get(start..end)
-    }
-
-    pub fn iter(&self) -> BytePageIter<'_> {
-        BytePageIter {
-            page: self,
-            index: 0,
-        }
-    }
-}
-
-pub struct BytePageIter<'a> {
-    page: &'a BytePage,
-    index: usize,
-}
-
-impl<'a> Iterator for BytePageIter<'a> {
-    type Item = &'a [u8];
-
-    fn next(&mut self) -> Option<Self::Item> {
-        let value = self.page.get(self.index)?;
-        self.index += 1;
-        Some(value)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
-pub struct BytePageBuilder {
-    bytes: Vec<u8>,
-    offsets: Vec<u32>,
-}
-
-impl BytePageBuilder {
-    pub fn new() -> Self {
-        Self {
-            bytes: Vec::new(),
-            offsets: vec![0],
-        }
-    }
-
-    pub fn with_capacity(items: usize, bytes: usize) -> Self {
-        let mut offsets = Vec::with_capacity(items.saturating_add(1));
-        offsets.push(0);
-        Self {
-            bytes: Vec::with_capacity(bytes),
-            offsets,
-        }
-    }
-
-    pub fn from_page(page: BytePage) -> Self {
-        Self {
-            bytes: page.bytes,
-            offsets: page.offsets,
-        }
-    }
-
-    pub fn len(&self) -> usize {
-        self.offsets.len().saturating_sub(1)
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.len() == 0
-    }
-
-    pub fn get(&self, index: usize) -> Option<&[u8]> {
-        let start = usize::try_from(*self.offsets.get(index)?).ok()?;
-        let end = usize::try_from(*self.offsets.get(index + 1)?).ok()?;
-        self.bytes.get(start..end)
-    }
-
-    pub fn push(&mut self, value: impl AsRef<[u8]>) {
-        let value = value.as_ref();
-        self.bytes.extend_from_slice(value);
-        let end = u32::try_from(self.bytes.len()).expect("byte page exceeds u32 offset capacity");
-        self.offsets.push(end);
-    }
-
-    pub fn finish(self) -> BytePage {
-        BytePage {
-            bytes: self.bytes,
-            offsets: self.offsets,
-        }
-    }
-}
-
-/// Ordered byte range for backend KV scans.
-///
-/// Ranges are half-open: `start <= key < end`. `Prefix` is explicit because it
-/// is a common access pattern and lets each backend choose the safest
-/// implementation for its storage engine.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum BackendKvScanRange {
-    Prefix(Vec<u8>),
-    Range { start: Vec<u8>, end: Vec<u8> },
-}
-
-impl BackendKvScanRange {
-    pub fn prefix(prefix: impl Into<Vec<u8>>) -> Self {
-        Self::Prefix(prefix.into())
-    }
-
-    pub fn range(start: impl Into<Vec<u8>>, end: impl Into<Vec<u8>>) -> Self {
-        Self::Range {
-            start: start.into(),
-            end: end.into(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvGetRequest {
-    pub groups: Vec<BackendKvGetGroup>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvGetGroup {
-    pub namespace: String,
-    pub keys: Vec<Vec<u8>>,
-}
-
-impl BackendKvGetGroup {
-    pub fn namespace(&self) -> &str {
-        &self.namespace
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvValueBatch {
-    pub groups: Vec<BackendKvValueGroup>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvValueGroup {
-    namespace: String,
-    values: BytePage,
-    present: Vec<bool>,
-}
-
-impl BackendKvValueGroup {
-    pub fn new(namespace: impl Into<String>, values: BytePage, present: Vec<bool>) -> Self {
-        assert_eq!(
-            values.len(),
-            present.len(),
-            "backend value batch must have one value slot per presence bit"
-        );
-        Self {
-            namespace: namespace.into(),
-            values,
-            present,
-        }
-    }
-
-    pub fn namespace(&self) -> &str {
-        &self.namespace
-    }
-
-    pub fn len(&self) -> usize {
-        self.present.len()
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.present.is_empty()
-    }
-
-    pub fn value(&self, index: usize) -> Option<Option<&[u8]>> {
-        let present = *self.present.get(index)?;
-        if present {
-            Some(Some(
-                self.values
-                    .get(index)
-                    .expect("backend value batch invariant violated"),
-            ))
-        } else {
-            Some(None)
-        }
-    }
-
-    pub fn values_iter(&self) -> impl Iterator<Item = Option<&[u8]>> {
-        (0..self.len()).filter_map(|index| self.value(index))
-    }
-
-    pub fn into_parts(self) -> (String, BytePage, Vec<bool>) {
-        (self.namespace, self.values, self.present)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvExistsBatch {
-    pub groups: Vec<BackendKvExistsGroup>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvExistsGroup {
-    pub namespace: String,
-    pub exists: Vec<bool>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvScanRequest {
-    pub namespace: String,
-    pub range: BackendKvScanRange,
-    pub after: Option<Vec<u8>>,
-    pub limit: usize,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvKeyPage {
-    pub keys: BytePage,
-    pub resume_after: Option<Vec<u8>>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvValuePage {
-    pub values: BytePage,
-    pub resume_after: Option<Vec<u8>>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvEntryPage {
-    pub keys: BytePage,
-    pub values: BytePage,
-    pub resume_after: Option<Vec<u8>>,
-}
-
-impl BackendKvEntryPage {
-    pub fn len(&self) -> usize {
-        self.keys.len()
-    }
-
-    pub fn is_empty(&self) -> bool {
-        self.keys.is_empty()
-    }
-
-    pub fn key(&self, index: usize) -> Option<&[u8]> {
-        self.keys.get(index)
-    }
-
-    pub fn value(&self, index: usize) -> Option<&[u8]> {
-        self.values.get(index)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
-pub struct BackendKvWriteBatch {
-    pub groups: Vec<BackendKvWriteGroup>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct BackendKvWriteGroup {
-    namespace: String,
-    put_keys: BytePageBuilder,
-    put_values: BytePageBuilder,
-    deletes: BytePageBuilder,
-}
-
-impl BackendKvWriteGroup {
-    pub fn new(namespace: impl Into<String>) -> Self {
-        Self {
-            namespace: namespace.into(),
-            put_keys: BytePageBuilder::new(),
-            put_values: BytePageBuilder::new(),
-            deletes: BytePageBuilder::new(),
-        }
-    }
-
-    pub fn from_pages(
-        namespace: impl Into<String>,
-        put_keys: BytePage,
-        put_values: BytePage,
-        deletes: BytePage,
-    ) -> Self {
-        assert_eq!(
-            put_keys.len(),
-            put_values.len(),
-            "backend write batch must have one value per put key"
-        );
-        Self {
-            namespace: namespace.into(),
-            put_keys: BytePageBuilder::from_page(put_keys),
-            put_values: BytePageBuilder::from_page(put_values),
-            deletes: BytePageBuilder::from_page(deletes),
-        }
-    }
-
-    pub fn put(&mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>) {
-        self.put_keys.push(key);
-        self.put_values.push(value);
-    }
-
-    pub fn delete(&mut self, key: impl AsRef<[u8]>) {
-        self.deletes.push(key);
-    }
-
-    pub fn namespace(&self) -> &str {
-        &self.namespace
-    }
-
-    pub fn put_count(&self) -> usize {
-        self.put_keys.len()
-    }
-
-    pub fn delete_count(&self) -> usize {
-        self.deletes.len()
-    }
-
-    pub fn put_key(&self, index: usize) -> Option<&[u8]> {
-        self.put_keys.get(index)
-    }
-
-    pub fn put_value(&self, index: usize) -> Option<&[u8]> {
-        self.put_values.get(index)
-    }
-
-    pub fn delete_key(&self, index: usize) -> Option<&[u8]> {
-        self.deletes.get(index)
-    }
-
-    pub fn into_parts(self) -> (String, BytePage, BytePage, BytePage) {
-        (
-            self.namespace,
-            self.put_keys.finish(),
-            self.put_values.finish(),
-            self.deletes.finish(),
-        )
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
-pub struct BackendKvWriteStats {
-    pub puts: usize,
-    pub deletes: usize,
-    pub bytes_written: usize,
-}