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

package/src/database/kysely-plugin/json-column-plugin.ts

@@ -11,11 +11,18 @@ import {
 	type PluginTransformQueryArgs,
 } from "kysely";
 
+type JsonColumnConfig = {
+	type:
+		| "object"
+		| Array<"string" | "number" | "boolean" | "object" | "array" | "null">;
+};
+
 export function JSONColumnPlugin(
-	jsonColumns: Record<string, string[]>
+	jsonColumns: Record<string, Record<string, JsonColumnConfig>>
 ): KyselyPlugin {
-	const jsonColumnNames = Object.keys(jsonColumns).flatMap(
-		(key) => jsonColumns[key]!
+	// Build a flat list of all JSON column names for the result transformer
+	const jsonColumnNames = Object.keys(jsonColumns).flatMap((table) =>
+		Object.keys(jsonColumns[table]!)
 	);
 
 	return {
@@ -70,12 +77,15 @@ export function JSONColumnPlugin(
 }
 
 class SerializeJsonbTransformer extends OperationNodeTransformer {
-	private readonly jsonbColumns: Record<string, string[]>;
+	private readonly jsonbColumns: Record<
+		string,
+		Record<string, JsonColumnConfig>
+	>;
 	private readonly table: string | undefined;
 	private readonly columns: ReadonlyArray<ColumnNode> | undefined;
 
 	constructor(
-		jsonbColumns: Record<string, string[]>,
+		jsonbColumns: Record<string, Record<string, JsonColumnConfig>>,
 		table: string | undefined,
 		columns: ReadonlyArray<ColumnNode> | undefined
 	) {
@@ -85,9 +95,26 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 		this.columns = columns;
 	}
 
+	private getJsonColumnConfig(
+		columnName: string
+	): JsonColumnConfig | undefined {
+		if (!this.table || !columnName) return undefined;
+		return this.jsonbColumns[this.table]?.[columnName];
+	}
+
 	private isJsonbColumn(columnName: string): boolean {
-		if (!this.table || !columnName) return false;
-		return this.jsonbColumns[this.table]?.includes(columnName) ?? false;
+		return this.getJsonColumnConfig(columnName) !== undefined;
+	}
+
+	private isSqlExpression(node: any): boolean {
+		// Check if the node is a SQL expression that shouldn't be wrapped
+		// Common SQL expression node types:
+		// - RawNode: Created by sql`` template literals
+		// - FunctionNode: SQL functions like json_set()
+		// - BinaryOperationNode: SQL operations
+		// - etc.
+		// ValueNode is the only type we want to wrap in json()
+		return node && node.kind !== "ValueNode";
 	}
 
 	override transformOnConflict(node: OnConflictNode): OnConflictNode {
@@ -103,13 +130,20 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 				const columnName = updateItem.column.column.name;
 				if (this.isJsonbColumn(columnName)) {
 					const valueNode = updateItem.value;
+					// Check if the value is a SQL expression - if so, don't wrap it
+					if (this.isSqlExpression(valueNode)) {
+						return updateItem;
+					}
 					// Check if the value part is specifically a ValueNode
 					if (valueNode.kind === "ValueNode") {
 						// If it is, serialize it
 						return {
 							...updateItem,
-							// @ts-expect-error - kysely type narrowing
-							value: this.serializeValue(valueNode),
+							value: this.serializeValue(
+								// @ts-expect-error - kysely type narrowing
+								valueNode,
+								this.getJsonColumnConfig(columnName)
+							),
 						};
 					}
 				}
@@ -139,10 +173,17 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 		// @ts-expect-error - kysely type narrowing
 		const columnName = node.column.column.name;
 		if (this.isJsonbColumn(columnName)) {
+			// Check if the value is a SQL expression (RawNode, etc.) - if so, don't wrap it
+			if (this.isSqlExpression(node.value)) {
+				return node;
+			}
 			return {
 				...node,
-				// @ts-expect-error - kysely type narrowing
-				value: this.serializeValue(node.value),
+				value: this.serializeValue(
+					// @ts-expect-error - kysely type narrowing
+					node.value,
+					this.getJsonColumnConfig(columnName)
+				),
 			} as ColumnUpdateNode;
 		}
 		return super.transformColumnUpdate(node);
@@ -153,9 +194,16 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 		// node.column.column.name is the column name for SetOperationNode
 		const columnName = node.column?.column?.name;
 		if (columnName && this.isJsonbColumn(columnName)) {
+			// Check if the value is a SQL expression - if so, don't wrap it
+			if (this.isSqlExpression(node.value)) {
+				return node;
+			}
 			return {
 				...node,
-				value: this.serializeValue(node.value),
+				value: this.serializeValue(
+					node.value,
+					this.getJsonColumnConfig(columnName)
+				),
 			};
 		}
 		return super.transformSetOperation(node);
@@ -172,7 +220,8 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 						colNode?.kind === "ColumnNode" &&
 						this.isJsonbColumn(colNode.column.name)
 					) {
-						return this.serializeValue(valNode);
+						const config = this.getJsonColumnConfig(colNode.column.name);
+						return this.serializeValue(valNode, config);
 					}
 					return valNode;
 				});
@@ -189,7 +238,8 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 						colNode?.kind === "ColumnNode" &&
 						this.isJsonbColumn(colNode.column.name)
 					) {
-						return this.serializeValue(valNode as ValueNode);
+						const config = this.getJsonColumnConfig(colNode.column.name);
+						return this.serializeValue(valNode as ValueNode, config);
 					}
 					return valNode;
 				});
@@ -200,12 +250,27 @@ class SerializeJsonbTransformer extends OperationNodeTransformer {
 		return { ...node, values: newValues };
 	}
 
-	private serializeValue(node: ValueNode): any {
+	private serializeValue(node: ValueNode, config?: JsonColumnConfig): any {
 		const val = node.value;
 		if (val instanceof ArrayBuffer || ArrayBuffer.isView(val) || val === null) {
 			return node;
 		}
+
+		// Check if this column only accepts objects and we have a string
+		// that might be pre-serialized JSON
+		if (config?.type === "object" && typeof val === "string") {
+			// For object-only columns, assume string values are pre-serialized JSON
+			// to avoid double serialization
+			return {
+				kind: "FunctionNode",
+				func: "json",
+				arguments: [{ kind: "ValueNode", value: val }],
+			};
+		}
+
+		// For all other cases, stringify the value
 		const jsonText = JSON.stringify(val);
+
 		return {
 			kind: "FunctionNode",
 			func: "json",

package/src/database/nano-id.test.ts

@@ -1,8 +1,8 @@
 import { expect, test, vi } from "vitest";
-import { _nanoIdAlphabet, nanoid } from "./nano-id.js";
+import { _nanoIdAlphabet, randomNanoId } from "./nano-id.js";
 
 test("length is obeyed", () => {
-	const id = nanoid(10);
+	const id = randomNanoId(10);
 	expect(id.length).toBe(10);
 });
 
@@ -28,7 +28,7 @@ test("polyfill works when crypto is not available", () => {
 	vi.stubGlobal("crypto", undefined);
 
 	try {
-		const id = nanoid(10);
+		const id = randomNanoId(10);
 		expect(id.length).toBe(10);
 		expect(typeof id).toBe("string");
 		// Check that it only contains characters from our alphabet

package/src/database/nano-id.ts

@@ -89,9 +89,12 @@ export const _nanoIdAlphabet =
 /**
  * Generate secure URL-friendly unique ID.
  *
+ * NOTE: This is the non-deterministic version. For deterministic IDs in tests,
+ * use `nanoid({ lix })` from './functions.js' instead.
+ *
  * Use https://zelark.github.io/nano-id-cc/ to calculate the length
  * of the ID for the use case with the alphabet provided in the
  * implementation.
  */
-export const nanoid: (size?: number) => string =
+export const randomNanoId: (size?: number) => string =
 	customAlphabet(_nanoIdAlphabet);

package/src/database/schema.ts

@@ -1,42 +1,42 @@
 import type { ChangeView, InternalChangeTable } from "../change/schema.js";
 import {
-	LixChangeSetEdgeSchema,
 	LixChangeSetElementSchema,
 	LixChangeSetLabelSchema,
 	LixChangeSetSchema,
 } from "../change-set/schema.js";
+import { LixCommitSchema, LixCommitEdgeSchema } from "../commit/schema.js";
 import {
 	LixVersionSchema,
-	type ActiveVersion,
+	type LixActiveVersion,
 	// type ActiveVersionTable,
 } from "../version/schema.js";
 import { type InternalSnapshotTable } from "../snapshot/schema.js";
 import { LixStoredSchemaSchema } from "../stored-schema/schema.js";
 import type { LixSchemaDefinition } from "../schema-definition/definition.js";
-import { LixKeyValueSchema, type KeyValue } from "../key-value/schema.js";
+import { LixKeyValueSchema, type LixKeyValue } from "../key-value/schema.js";
 import type {
 	StateView,
-	InternalStateCacheTable,
 	InternalChangeInTransactionTable,
 	StateAllView,
 } from "../state/schema.js";
 import type { StateHistoryView } from "../state-history/schema.js";
 import { LixFileDescriptorSchema } from "../file/schema.js";
 import { LixLogSchema } from "../log/schema.js";
-import {
-	LixAccountSchema,
-	type ActiveAccountTable,
-} from "../account/schema.js";
+import { LixAccountSchema, type LixActiveAccount } from "../account/schema.js";
 import { LixChangeAuthorSchema } from "../change-author/schema.js";
 import { LixLabelSchema } from "../label/schema.js";
+import { LixEntityLabelSchema } from "../entity/label/schema.js";
+import { LixEntityThreadSchema } from "../entity/thread/schema.js";
 import {
 	LixThreadSchema,
 	LixThreadCommentSchema,
-	type ThreadComment,
+	type LixThreadComment,
 } from "../thread/schema.js";
-import { LixChangeSetThreadSchema } from "../change-set/schema.js";
 import type { EntityViews } from "../entity-views/entity-view-builder.js";
 import type { ToKysely } from "../entity-views/types.js";
+import type { InternalStateCacheTable } from "../state/cache/schema.js";
+import type { InternalResolvedStateAllView } from "../state/resolved-state-view.js";
+import type { InternalStateAllUntrackedTable } from "../state/untracked/schema.js";
 
 export const LixDatabaseSchemaJsonColumns = {
 	snapshot: ["content"],
@@ -48,15 +48,17 @@ export type LixInternalDatabaseSchema = LixDatabaseSchema & {
 	internal_change: InternalChangeTable;
 	internal_snapshot: InternalSnapshotTable;
 	internal_state_cache: InternalStateCacheTable;
+	internal_state_all_untracked: InternalStateAllUntrackedTable;
+	internal_resolved_state_all: InternalResolvedStateAllView;
 };
 
 export const LixSchemaViewMap: Record<string, LixSchemaDefinition> = {
 	version: LixVersionSchema,
 	change_set: LixChangeSetSchema,
 	change_set_element: LixChangeSetElementSchema,
-	change_set_edge: LixChangeSetEdgeSchema,
 	change_set_label: LixChangeSetLabelSchema,
-	change_set_thread: LixChangeSetThreadSchema,
+	commit: LixCommitSchema,
+	commit_edge: LixCommitEdgeSchema,
 	file: LixFileDescriptorSchema,
 	log: LixLogSchema,
 	stored_schema: LixStoredSchemaSchema,
@@ -64,43 +66,43 @@ export const LixSchemaViewMap: Record<string, LixSchemaDefinition> = {
 	account: LixAccountSchema,
 	change_author: LixChangeAuthorSchema,
 	label: LixLabelSchema,
+	entity_label: LixEntityLabelSchema,
+	entity_thread: LixEntityThreadSchema,
 	thread: LixThreadSchema,
 	thread_comment: LixThreadCommentSchema,
 };
 
 export type LixDatabaseSchema = {
+	active_account: ToKysely<LixActiveAccount>;
+	active_version: ToKysely<LixActiveVersion>;
+
 	state: StateView;
 	state_all: StateAllView;
 	state_history: StateHistoryView;
-	// account
-	active_account: ActiveAccountTable;
 
 	change: ChangeView;
-
-	// // change proposal
-	// // change_proposal: ChangeProposalTable;
-
-	active_version: ToKysely<ActiveVersion>;
 } & EntityViews<
 	typeof LixKeyValueSchema,
 	"key_value",
-	{ value: KeyValue["value"] }
+	{ value: LixKeyValue["value"] }
 > &
 	EntityViews<typeof LixAccountSchema, "account"> &
 	EntityViews<typeof LixChangeSetSchema, "change_set"> &
 	EntityViews<typeof LixChangeSetElementSchema, "change_set_element"> &
-	EntityViews<typeof LixChangeSetEdgeSchema, "change_set_edge"> &
 	EntityViews<typeof LixChangeSetLabelSchema, "change_set_label"> &
-	EntityViews<typeof LixChangeSetThreadSchema, "change_set_thread"> &
 	EntityViews<typeof LixChangeAuthorSchema, "change_author"> &
 	EntityViews<typeof LixFileDescriptorSchema, "file", { data: Uint8Array }> &
 	EntityViews<typeof LixLabelSchema, "label"> &
+	EntityViews<typeof LixEntityLabelSchema, "entity_label"> &
+	EntityViews<typeof LixEntityThreadSchema, "entity_thread"> &
 	EntityViews<typeof LixStoredSchemaSchema, "stored_schema", { value: any }> &
 	EntityViews<typeof LixLogSchema, "log"> &
 	EntityViews<typeof LixThreadSchema, "thread"> &
 	EntityViews<
 		typeof LixThreadCommentSchema,
 		"thread_comment",
-		{ body: ThreadComment["body"] }
+		{ body: LixThreadComment["body"] }
 	> &
-	EntityViews<typeof LixVersionSchema, "version">;
+	EntityViews<typeof LixVersionSchema, "version"> &
+	EntityViews<typeof LixCommitSchema, "commit"> &
+	EntityViews<typeof LixCommitEdgeSchema, "commit_edge">;

package/src/deterministic/generate-human-id.test.ts

@@ -0,0 +1,154 @@
+import { test, expect } from "vitest";
+import { generateHumanId } from "./generate-human-id.js";
+import { openLix } from "../lix/open-lix.js";
+
+test("returns deterministic names in deterministic mode", async () => {
+	// Open two separate lix instances with deterministic mode
+	const lix1 = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+	const lix2 = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate IDs from both instances - they should match
+	const id1_lix1 = generateHumanId({ lix: lix1 });
+	const id1_lix2 = generateHumanId({ lix: lix2 });
+
+	const id2_lix1 = generateHumanId({ lix: lix1 });
+	const id2_lix2 = generateHumanId({ lix: lix2 });
+
+	const id3_lix1 = generateHumanId({ lix: lix1 });
+	const id3_lix2 = generateHumanId({ lix: lix2 });
+
+	// Both instances should generate the same sequence
+	expect(id1_lix1).toBe(id1_lix2);
+	expect(id2_lix1).toBe(id2_lix2);
+	expect(id3_lix1).toBe(id3_lix2);
+});
+
+test("cycles through names when exceeding array length", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate many IDs to test cycling
+	const names: string[] = [];
+	for (let i = 0; i < 45; i++) {
+		names.push(generateHumanId({ lix }));
+	}
+
+	// Find where the cycle starts repeating
+	let firstRepeatIndex = -1;
+	for (let i = 1; i < names.length; i++) {
+		if (names[i] === names[0]) {
+			firstRepeatIndex = i;
+			break;
+		}
+	}
+
+	// Should cycle after 40 names
+	expect(firstRepeatIndex).toBe(40);
+
+	// Verify cycling pattern
+	expect(names[40]).toBe(names[0]);
+	expect(names[41]).toBe(names[1]);
+	expect(names[42]).toBe(names[2]);
+});
+
+test("returns non-deterministic names in normal mode", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+	});
+
+	const id1 = generateHumanId({ lix });
+	const id2 = generateHumanId({ lix });
+
+	// Names should be strings
+	expect(typeof id1).toBe("string");
+	expect(typeof id2).toBe("string");
+
+	// Names should not be empty
+	expect(id1.length).toBeGreaterThan(0);
+	expect(id2.length).toBeGreaterThan(0);
+
+	// Names should be capitalized
+	expect(id1[0]).toBe(id1[0]?.toUpperCase());
+	expect(id2[0]).toBe(id2[0]?.toUpperCase());
+});
+
+test("uses custom separator when provided", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+	});
+
+	const idWithDash = generateHumanId({ lix, separator: "-" });
+	const idWithSpace = generateHumanId({ lix, separator: " " });
+	const idWithUnderscore = generateHumanId({ lix, separator: "_" });
+
+	// All should be strings
+	expect(typeof idWithDash).toBe("string");
+	expect(typeof idWithSpace).toBe("string");
+	expect(typeof idWithUnderscore).toBe("string");
+
+	// Should not contain separators (since we extract only first word)
+	expect(idWithDash).not.toContain("-");
+	expect(idWithSpace).not.toContain(" ");
+	expect(idWithUnderscore).not.toContain("_");
+});
+
+test("persists sequence across lix instances", async () => {
+	// Create first lix instance
+	const lix1 = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate some IDs
+	const id1 = generateHumanId({ lix: lix1 });
+	const id2 = generateHumanId({ lix: lix1 });
+	const id3 = generateHumanId({ lix: lix1 });
+
+	// Get the blob
+	const blob = await lix1.toBlob();
+
+	// Create new lix instance from blob
+	const lix2 = await openLix({
+		blob,
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate next ID - should continue from where we left off
+	const id4 = generateHumanId({ lix: lix2 });
+
+	// Verify it's not repeating the sequence
+	expect(id4).not.toBe(id1);
+	expect(id4).not.toBe(id2);
+	expect(id4).not.toBe(id3);
+});
+
+test("handles capitalize option", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	// Generate IDs with different capitalize options
+	const capitalizedId = generateHumanId({ lix, capitalize: true });
+	const lowercaseId = generateHumanId({ lix, capitalize: false });
+
+	// Capitalized should be uppercase first letter
+	expect(capitalizedId[0]).toBe(capitalizedId[0]?.toUpperCase());
+
+	// Lowercase should be all lowercase
+	expect(lowercaseId).toBe(lowercaseId.toLowerCase());
+});
+
+test("default capitalize is true", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+	});
+
+	const id = generateHumanId({ lix });
+
+	// Should be capitalized by default
+	expect(id[0]).toBe(id[0]?.toUpperCase());
+});

package/src/deterministic/generate-human-id.ts

@@ -0,0 +1,94 @@
+import type { Lix } from "../lix/open-lix.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { nextDeterministicSequenceNumber } from "./sequence.js";
+import { humanId } from "human-id";
+
+// Deterministic names for anonymous accounts
+const DETERMINISTIC_NAMES = [
+	"Plum",
+	"Coin",
+	"Bird",
+	"Fish",
+	"Tree",
+	"Star",
+	"Moon",
+	"Sun",
+	"Wave",
+	"Rock",
+	"Fox",
+	"Bear",
+	"Wolf",
+	"Lion",
+	"Eagle",
+	"Hawk",
+	"Dove",
+	"Swan",
+	"Crow",
+	"Owl",
+	"Rose",
+	"Lily",
+	"Iris",
+	"Sage",
+	"Mint",
+	"Fern",
+	"Palm",
+	"Oak",
+	"Pine",
+	"Elm",
+	"Gold",
+	"Ruby",
+	"Pearl",
+	"Jade",
+	"Opal",
+	"Onyx",
+	"Zinc",
+	"Iron",
+	"Clay",
+	"Sand",
+];
+
+/**
+ * Generates a human-readable ID that is deterministic in deterministic mode.
+ *
+ * @example
+ * ```ts
+ * const name = generateHumanId({ lix });
+ * // In deterministic mode: returns deterministic names like "Plum", "Coin", etc.
+ * // In normal mode: returns random human-id names
+ *
+ * const lowercaseName = generateHumanId({ lix, capitalize: false });
+ * // Returns lowercase names like "plum", "coin", etc.
+ * ```
+ */
+export function generateHumanId(args: {
+	lix: Pick<Lix, "sqlite" | "db">;
+	separator?: string;
+	capitalize?: boolean;
+}): string {
+	const capitalize = args.capitalize ?? true;
+	const separator = args.separator ?? "_";
+
+	if (isDeterministicMode({ lix: args.lix })) {
+		// In deterministic mode, use sequence to get deterministic index
+		const sequence = nextDeterministicSequenceNumber({
+			lix: args.lix,
+		});
+
+		// Use modulo to cycle through names
+		const name = DETERMINISTIC_NAMES[sequence % DETERMINISTIC_NAMES.length]!;
+		return capitalize ? name : name.toLowerCase();
+	} else {
+		// In non-deterministic mode, use human-id library
+		const name = humanId({
+			capitalize: capitalize,
+			adjectiveCount: 0,
+			separator: separator,
+		})
+			// Human ID has two words, remove the last one
+			.split(separator)[0]!
+			// Human ID uses plural, remove the last character to make it singular
+			.slice(0, -1);
+
+		return name;
+	}
+}

package/src/deterministic/index.ts

@@ -0,0 +1,7 @@
+export { isDeterministicMode } from "./is-deterministic-mode.js";
+export { nextDeterministicSequenceNumber } from "./sequence.js";
+export { timestamp } from "./timestamp.js";
+export { uuidV7 } from "./uuid-v7.js";
+export { nanoId } from "./nano-id.js";
+export { random } from "./random.js";
+export { generateHumanId } from "./generate-human-id.js";