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

package/src/engine/deterministic-mode/options.test.ts

@@ -1,159 +0,0 @@
-import { test, expect } from "vitest";
-import {
-	LixDeterministicModeOptionsSchema,
-	type DeterministicModeOptions,
-} from "./options.js";
-import {
-	validateLixSchema,
-	validateLixSchemaDefinition,
-} from "../../schema-definition/validate-lix-schema.js";
-
-test("deterministic mode options schema is a valid LixSchemaDefinition", () => {
-	expect(() =>
-		validateLixSchemaDefinition(LixDeterministicModeOptionsSchema)
-	).not.toThrow();
-});
-
-test("validates correct deterministic mode options", () => {
-	const validOptions: DeterministicModeOptions = {
-		enabled: true,
-		randomLixId: false,
-		timestamp: true,
-		random_seed: "test-seed",
-		nano_id: true,
-		uuid_v7: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, validOptions)
-	).not.toThrow();
-});
-
-test("validates minimal deterministic mode options with only required fields", () => {
-	const minimalOptions: DeterministicModeOptions = {
-		enabled: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, minimalOptions)
-	).not.toThrow();
-});
-
-test("fails validation when enabled is missing", () => {
-	// @ts-expect-error - Testing missing required field
-	const invalidOptions: DeterministicModeOptions = {
-		randomLixId: false,
-		timestamp: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("fails validation when enabled is not a boolean", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		// @ts-expect-error - Testing invalid type for enabled field
-		enabled: "true", // string instead of boolean
-		randomLixId: false,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("fails validation with additional properties", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		enabled: true,
-		// @ts-expect-error - Testing additional properties
-		unknown_property: "value",
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("validates all boolean fields correctly", () => {
-	const options: DeterministicModeOptions = {
-		enabled: false,
-		randomLixId: true,
-		timestamp: false,
-		random_seed: "custom-seed",
-		nano_id: false,
-		uuid_v7: true,
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, options)
-	).not.toThrow();
-});
-
-test("fails validation when boolean fields have wrong types", () => {
-	const testCases: DeterministicModeOptions[] = [
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for randomLixId
-			randomLixId: "true",
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for timestamp
-			timestamp: 1,
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for nano_id
-			nano_id: null,
-		},
-		{
-			enabled: true,
-			// @ts-expect-error - Testing invalid type for uuid_v7
-			uuid_v7: {},
-		},
-	];
-
-	for (const testCase of testCases) {
-		expect(() =>
-			validateLixSchema(LixDeterministicModeOptionsSchema, testCase)
-		).toThrow(/Data validation failed/);
-	}
-});
-
-test("fails validation when random_seed is not a string", () => {
-	const invalidOptions: DeterministicModeOptions = {
-		enabled: true,
-		// @ts-expect-error - Testing invalid type for random_seed
-		random_seed: 12345, // number instead of string
-	};
-
-	expect(() =>
-		validateLixSchema(LixDeterministicModeOptionsSchema, invalidOptions)
-	).toThrow(/Data validation failed/);
-});
-
-test("schema has correct metadata", () => {
-	expect(LixDeterministicModeOptionsSchema["x-lix-key"]).toBe(
-		"lix_deterministic_mode"
-	);
-	expect(LixDeterministicModeOptionsSchema["x-lix-version"]).toBe("1.0");
-	expect(LixDeterministicModeOptionsSchema.type).toBe("object");
-	expect(LixDeterministicModeOptionsSchema.required).toEqual(["enabled"]);
-	expect(LixDeterministicModeOptionsSchema.additionalProperties).toBe(false);
-});
-
-test("schema has correct default values", () => {
-	const properties = LixDeterministicModeOptionsSchema.properties;
-
-	expect(properties.randomLixId["x-lix-default"]).toBe("false");
-	expect(properties.timestamp["x-lix-default"]).toBe("true");
-	expect(properties.random_seed["x-lix-default"]).toBe(
-		"'lix-deterministic-seed'"
-	);
-	expect(properties.nano_id["x-lix-default"]).toBe("true");
-	expect(properties.uuid_v7["x-lix-default"]).toBe("true");
-
-	// enabled should not have a default
-	expect(properties.enabled).not.toHaveProperty("x-lix-default");
-});

package/src/engine/deterministic-mode/options.ts

@@ -1,57 +0,0 @@
-import type {
-	FromLixSchemaDefinition,
-	LixInsertable,
-	LixSchemaDefinition,
-} from "../../schema-definition/index.js";
-
-/**
- * Schema definition for deterministic mode options.
- *
- * @example
- * const options = {
- *   enabled: true,
- *   randomLixId: false,
- *   timestamp: true,
- *   random_seed: "default-seed",
- *   nano_id: true,
- *   uuid_v7: true
- * };
- */
-export const LixDeterministicModeOptionsSchema = {
-	"x-lix-key": "lix_deterministic_mode",
-	"x-lix-version": "1.0",
-	type: "object",
-	properties: {
-		enabled: {
-			type: "boolean",
-		},
-		randomLixId: {
-			type: "boolean",
-			"x-lix-default": "false",
-		},
-		timestamp: {
-			type: "boolean",
-			"x-lix-default": "true",
-		},
-		random_seed: {
-			type: "string",
-			"x-lix-default": "'lix-deterministic-seed'",
-		},
-		nano_id: {
-			type: "boolean",
-			"x-lix-default": "true",
-		},
-		uuid_v7: {
-			type: "boolean",
-			"x-lix-default": "true",
-		},
-	},
-	required: ["enabled"],
-	additionalProperties: false,
-} as const;
-
-export type DeterministicModeOptions = LixInsertable<
-	FromLixSchemaDefinition<typeof LixDeterministicModeOptionsSchema>
->;
-
-LixDeterministicModeOptionsSchema satisfies LixSchemaDefinition;

package/src/engine/entity-views/README.md

@@ -1,214 +0,0 @@
-# Entity Views
-
-## Overview
-
-Entity views are SQL views that provide a typed, structured interface over the underlying `state` table. They transform the generic state storage into domain-specific entity tables, making it easy to work with entities using standard SQL operations while maintaining version control and change tracking.
-
-## Architecture
-
-Entity views are "merely a view over the state table" - they don't store any data themselves but provide a convenient interface:
-
-```
-┌─────────────────────────────────────────────────┐
-│             User SQL Queries                    │
-│   (SELECT, INSERT, UPDATE, DELETE on entities)  │
-└─────────────────────┬───────────────────────────┘
-                      │
-                      v
-┌─────────────────────────────────────────────────┐
-│              Entity Views                       │
-│                                                 │
-│  • Extract JSON properties as columns           │
-│  • Add operational metadata (lixcol_*)          │
-│  • Provide CRUD operations via triggers         │
-└─────────────────────┬───────────────────────────┘
-                      │
-                      v
-┌─────────────────────────────────────────────────┐
-│          State Virtual Table                    │
-│                                                 │
-│  • Generic entity storage                       │
-│  • Version control                              │
-│  • Change tracking                              │
-└─────────────────────────────────────────────────┘
-```
-
-## Example: Views as Filters
-
-Entity views are essentially filters over the generic state table. Here's how it works:
-
-### What's in the state_by_version table
-
-```sql
-state_by_version:
-┌─────────────┬─────────────────┬──────────┬───────────────────────────────────┐
-│ entity_id   │ schema_key      │ file_id  │ snapshot_content                  │
-├─────────────┼─────────────────┼──────────┼───────────────────────────────────┤
-│ greeting    │ lix:key_value   │ file1    │ {"key":"greeting","value":"hello"}│
-│ farewell    │ lix:key_value   │ file1    │ {"key":"farewell","value":"bye"}  │
-│ user123     │ lix:account     │ lix      │ {"id":"user123","name":"Alice"}   │
-│ config1     │ lix:key_value   │ file2    │ {"key":"config1","value":"true"}  │
-└─────────────┴─────────────────┴──────────┴───────────────────────────────────┘
-```
-
-### What the key_value view returns
-
-```sql
-SELECT * FROM key_value;
-
-┌──────────┬───────┬─────────────────┬──────────────────┐
-│ key      │ value │ lixcol_file_id  │ lixcol_change_id │
-├──────────┼───────┼─────────────────┼──────────────────┤
-│ greeting │ hello │ file1           │ change-123       │
-│ farewell │ bye   │ file1           │ change-124       │
-│ config1  │ true  │ file2           │ change-125       │
-└──────────┴───────┴─────────────────┴──────────────────┘
-```
-
-The view:
-
-- **Filters** rows where `schema_key = 'lix:key_value'`
-- **Extracts** JSON properties (`key`, `value`) as columns
-- **Excludes** entities with different schemas (like `lix:account`)
-- **Adds** operational columns prefixed with `lixcol_`
-
-## Three Types of Entity Views
-
-For each entity schema, three views are created:
-
-### 1. Primary View (e.g., `key_value`)
-
-- **Purpose**: Work with entities in the active version only
-- **Based on**: `state` view (filtered to current version)
-- **Features**:
-  - Hides `lixcol_version_id` to prevent cross-version accidents
-  - Full CRUD support via INSTEAD OF triggers
-  - Most commonly used for application logic
-
-### 2. All-Versions View (e.g., `key_value_by_version`)
-
-- **Purpose**: Work with entities across all versions
-- **Based on**: `state_by_version` virtual table
-- **Features**:
-  - Exposes `lixcol_version_id` for version-specific queries
-  - Full CRUD support with explicit version control
-  - Used for cross-version operations and migrations
-
-### 3. History View (e.g., `key_value_history`)
-
-- **Purpose**: Read historical states and track changes
-- **Based on**: `state_history` table
-- **Features**:
-  - Read-only (no CRUD triggers)
-  - Includes depth information for blame functionality
-  - Used for audit trails and debugging
-
-## How Entity Views Work
-
-### JSON Property Extraction
-
-Entity properties are stored as JSON in the state table's `snapshot_content` column. Views extract these as proper columns:
-
-```sql
--- State table stores generic JSON
-snapshot_content: {"value": "hello", "description": "greeting"}
-
--- Entity view exposes as columns
-SELECT value, description FROM key_value
--- Returns: value='hello', description='greeting'
-```
-
-### Operational Columns (lixcol\_\*)
-
-Entity views add metadata columns prefixed with `lixcol_`:
-
-- `lixcol_file_id` - Links entity to a file
-- `lixcol_created_at` - When entity was created in this version
-- `lixcol_updated_at` - When entity was last updated in this version
-- `lixcol_change_id` - Links to the change that created/modified the entity
-- `lixcol_untracked` - Bypasses change tracking (for UI state)
-- `lixcol_inherited_from_version_id` - Tracks entity lineage across branches
-- `lixcol_version_id` - Version ID (only in `_by_version` views)
-
-### INSTEAD OF Triggers
-
-Entity views use SQLite's INSTEAD OF triggers to intercept CRUD operations and redirect them to the state table:
-
-```sql
--- User writes to entity view
-INSERT INTO key_value (key, value) VALUES ('greeting', 'hello')
-
--- Trigger converts to state table operation
-INSERT INTO state_by_version (
-  entity_id: 'greeting',
-  schema_key: 'lix:key_value',
-  snapshot_content: '{"key": "greeting", "value": "hello"}'
-  -- ... other metadata
-)
-```
-
-## Type Safety
-
-The TypeScript type system ensures compile-time safety:
-
-```typescript
-// Schema definition
-type KeyValue = {
-	key: string;
-	value: string;
-	description?: string;
-};
-
-// Generated types for queries
-type KeyValueRow = State<KeyValue>; // For SELECT from key_value
-type NewKeyValueRow = NewState<KeyValue>; // For INSERT into key_value
-```
-
-## Usage Examples
-
-### Working with Active Version
-
-```sql
--- Insert a new entity (goes through state virtual table)
-INSERT INTO key_value (key, value) VALUES ('greeting', 'hello');
-
--- Update an entity
-UPDATE key_value SET value = 'hi' WHERE key = 'greeting';
-
--- Delete an entity
-DELETE FROM key_value WHERE key = 'greeting';
-
--- Query entities
-SELECT * FROM key_value WHERE value LIKE 'h%';
-```
-
-### Working Across Versions
-
-```sql
--- Query specific version
-SELECT * FROM key_value_by_version WHERE lixcol_version_id = 'version-123';
-
--- Insert into specific version
-INSERT INTO key_value_by_version (key, value, lixcol_version_id)
-VALUES ('greeting', 'hello', 'version-123');
-```
-
-### Viewing History
-
-```sql
--- See all historical states of an entity
-SELECT * FROM key_value_history WHERE key = 'greeting' ORDER BY depth;
-
--- Find who changed an entity
-SELECT * FROM key_value_history
-WHERE key = 'greeting' AND lixcol_change_id IS NOT NULL;
-```
-
-## Benefits
-
-1. **Natural SQL Interface** - Work with entities using familiar SQL
-2. **Type Safety** - Full TypeScript types for all operations
-3. **Version Control** - Built-in branching and merging support
-4. **Change Tracking** - Automatic audit trail for all modifications
-5. **Performance** - Leverages SQLite's query optimizer
-6. **Flexibility** - JSON storage allows schema evolution

package/src/engine/entity-views/build-json-object-entries.test.ts

@@ -1,42 +0,0 @@
-import { expect, test } from "vitest";
-import { buildJsonObjectEntries } from "./build-json-object-entries.js";
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-
-const TestSchema = {
-	"x-lix-key": "test_schema",
-	"x-lix-version": "1.0",
-	"x-lix-primary-key": ["/id"],
-	type: "object",
-	properties: {
-		id: { type: "string" },
-		name: { type: "string" },
-		version: { type: "string" },
-		count: { type: "number" },
-		flag: { type: "boolean" },
-		data: { type: "object" },
-		arr: { type: "array" },
-	},
-	additionalProperties: false,
-} as const satisfies LixSchemaDefinition;
-
-test("uses json_quote for string fields to prevent coercion", () => {
-	const sql = buildJsonObjectEntries({
-		schema: TestSchema,
-		ref: (p) => `NEW.${p}`,
-	});
-	expect(sql).toContain("'name', json_quote(NEW.name)");
-	expect(sql).toContain("'version', json_quote(NEW.version)");
-});
-
-test("uses json/json_quote combo for object/array fields", () => {
-	const sql = buildJsonObjectEntries({
-		schema: TestSchema,
-		ref: (p) => `NEW.${p}`,
-	});
-	expect(sql).toContain(
-		"'data', CASE WHEN json_valid(NEW.data) THEN json(NEW.data) ELSE json_quote(NEW.data) END"
-	);
-	expect(sql).toContain(
-		"'arr', CASE WHEN json_valid(NEW.arr) THEN json(NEW.arr) ELSE json_quote(NEW.arr) END"
-	);
-});

package/src/engine/entity-views/build-json-object-entries.ts

@@ -1,43 +0,0 @@
-import type { LixSchemaDefinition } from "../../schema-definition/definition.js";
-import { isJsonType } from "../../schema-definition/json-type.js";
-
-/**
- * Builds a json_object entries list for snapshot_content serialization that respects schema types.
- * - For JSON-like props (object/array): accept raw JSON when valid, otherwise quote
- * - For string props: always json_quote to avoid coercion (e.g. "1.0" -> 1)
- * - For others (number/boolean/null): generic JSON handling
- */
-export function buildJsonObjectEntries(args: {
-	schema: LixSchemaDefinition;
-	ref: (prop: string) => string;
-}): string {
-	const properties = Object.keys((args.schema as any).properties);
-
-	return properties
-		.map((prop) => {
-			const def: any = (args.schema as any).properties[prop];
-			const ref = () => args.ref(prop);
-			const jsonLike = isJsonType(def);
-			const types = def?.type
-				? Array.isArray(def.type)
-					? def.type
-					: [def.type]
-				: [];
-			const isString = !jsonLike && types.includes("string");
-
-			if (jsonLike) {
-				const first = ref();
-				const second = ref();
-				const third = ref();
-				return `'${prop}', CASE WHEN json_valid(${first}) THEN json(${second}) ELSE json_quote(${third}) END`;
-			}
-			if (isString) {
-				return `'${prop}', json_quote(${ref()})`;
-			}
-			const first = ref();
-			const second = ref();
-			const third = ref();
-			return `'${prop}', CASE WHEN json_valid(${first}) THEN json(${second}) ELSE json_quote(${third}) END`;
-		})
-		.join(", ");
-}