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

package/src/log/create-log.ts

@@ -1,7 +1,8 @@
-import { nanoId } from "../deterministic/index.js";
-import type { State } from "../entity-views/types.js";
+import { nanoId } from "../engine/functions/nano-id.js";
+import type { State } from "../engine/entity-views/types.js";
+import type { JSONType } from "../schema-definition/json-type.js";
 import type { Lix } from "../lix/open-lix.js";
-import type { LixLog } from "./schema.js";
+import type { LixLog } from "./schema-definition.js";
 
 /**
  * Directly creates a log entry in the Lix database without applying any filters.
@@ -10,35 +11,45 @@ import type { LixLog } from "./schema.js";
  * in the key-value store. It is the responsibility of the calling application
  * to implement any desired log level filtering before invoking this function.
  *
- * It is recommended to use dot notation for log keys (e.g., 'app.module.component').
+ * Use `snake_case` for log keys (e.g., `app_checkout_submit`) to keep filters predictable.
+ * Provide either a `message`, a structured `payload`, or both depending on your needs.
  *
  * @example
- * // Directly log an info message
  *
- * if (shouldLog) {
- *   await createLog({
- *     lix,
- *     key: 'app.init',
- *     level: 'info',
- *     message: 'Application initialized'
+ * await createLog({
+ *   lix,
+ *   key: 'app_init',
+ *   level: 'info',
+ *   message: 'Application initialized'
+ * });
+ *
+ * @example
+ *
+ * await createLog({
+ *   lix,
+ *   key: 'app_init_state',
+ *   level: 'debug',
+ *   payload: { ready: true }
  * });
  *
  * @returns A promise that resolves with the created log entry.
  */
 export async function createLog(args: {
-	lix: Pick<Lix, "sqlite" | "db">;
-	message: string;
+	lix: Lix;
+	message?: string | null;
+	payload?: JSONType;
 	level: string;
 	key: string;
 }): Promise<State<LixLog>> {
 	// Insert the log entry
-	const id = nanoId({ lix: args.lix });
+	const id = await nanoId({ lix: args.lix });
 	await args.lix.db
 		.insertInto("log")
 		.values({
 			id,
 			key: args.key,
-			message: args.message,
+			message: args.message ?? null,
+			payload: args.payload ?? null,
 			level: args.level,
 		})
 		.execute();

package/src/log/index.ts

@@ -1,2 +1,2 @@
-export { LixLogSchema, type LixLog as Log } from "./schema.js";
+export { LixLogSchema, type LixLog } from "./schema-definition.js";
 export { createLog } from "./create-log.js";

package/src/log/schema-definition.ts

@@ -0,0 +1,45 @@
+import type {
+	FromLixSchemaDefinition,
+	LixSchemaDefinition,
+} from "../schema-definition/definition.js";
+import { JSONTypeSchema } from "../schema-definition/json-type.js";
+
+export type LixLog = FromLixSchemaDefinition<typeof LixLogSchema>;
+
+export const LixLogSchema = {
+	"x-lix-key": "lix_log",
+	"x-lix-version": "1.0",
+	"x-lix-primary-key": ["/id"],
+	"x-lix-override-lixcols": {
+		lixcol_file_id: '"lix"',
+		lixcol_plugin_key: '"lix_sdk"',
+	},
+	type: "object",
+	properties: {
+		id: {
+			type: "string",
+			description: "The unique identifier of the log entry",
+			"x-lix-default": "lix_uuid_v7()",
+		},
+		key: {
+			type: "string",
+			description: "The key of the log entry",
+		},
+		message: {
+			type: "string",
+			description: "The message of the log entry",
+			nullable: true,
+		},
+		payload: {
+			...JSONTypeSchema,
+			description: "Structured payload for the log entry",
+		} as any,
+		level: {
+			type: "string",
+			description: "The level of the log entry",
+		},
+	},
+	required: ["id", "key", "level"],
+	additionalProperties: false,
+} as const;
+LixLogSchema satisfies LixSchemaDefinition;

package/src/log/schema.test.ts

@@ -8,19 +8,25 @@ test("log insert creates entries in the view", async () => {
 	await lix.db
 		.insertInto("log")
 		.values({
-			key: "test.log",
+			key: "test_log",
 			message: "Test log message",
+			payload: { meta: "value" },
 			level: "info",
 		})
 		.execute();
 
 	// Verify the log appears in the view
-	const logs = await lix.db.selectFrom("log").selectAll().execute();
+	const logs = await lix.db
+		.selectFrom("log")
+		.where("key", "=", "test_log")
+		.selectAll()
+		.execute();
 
 	expect(logs).toHaveLength(1);
 	expect(logs[0]).toMatchObject({
-		key: "test.log",
+		key: "test_log",
 		message: "Test log message",
+		payload: { meta: "value" },
 		level: "info",
 	});
 });
@@ -35,7 +41,8 @@ test("log insert with custom id", async () => {
 		.values({
 			id: customId,
 			key: "custom.log",
-			message: "Custom ID log",
+			message: null,
+			payload: { context: "custom" },
 			level: "debug",
 		})
 		.execute();
@@ -49,7 +56,8 @@ test("log insert with custom id", async () => {
 	expect(logs).toHaveLength(1);
 	expect(logs[0]?.id).toBe(customId);
 	expect(logs[0]?.key).toBe("custom.log");
-	expect(logs[0]?.message).toBe("Custom ID log");
+	expect(logs[0]?.message).toBeNull();
+	expect(logs[0]?.payload).toEqual({ context: "custom" });
 	expect(logs[0]?.level).toBe("debug");
 });
 
@@ -61,34 +69,45 @@ test("log delete removes entries from the view", async () => {
 		.insertInto("log")
 		.values([
 			{
-				key: "log.to.keep",
+				key: "test_log_to_keep",
 				message: "Keep this log",
+				payload: null,
 				level: "info",
 			},
 			{
-				key: "log.to.delete",
+				key: "test_log_to_delete",
 				message: "Delete this log",
+				payload: { delete: true },
 				level: "error",
 			},
 		])
 		.execute();
 
 	// Verify both logs exist
-	const allLogs = await lix.db.selectFrom("log").selectAll().execute();
+	const allLogs = await lix.db
+		.selectFrom("log")
+		.where("key", "in", ["test_log_to_keep", "test_log_to_delete"])
+		.selectAll()
+		.execute();
 	expect(allLogs).toHaveLength(2);
 
 	// Get the ID of the log to delete
-	const logToDelete = allLogs.find((log) => log.key === "log.to.delete");
+	const logToDelete = allLogs.find((log) => log.key === "test_log_to_delete");
 	expect(logToDelete).toBeDefined();
 
 	// Delete one log by ID
 	await lix.db.deleteFrom("log").where("id", "=", logToDelete!.id).execute();
 
 	// Verify only one log remains
-	const remainingLogs = await lix.db.selectFrom("log").selectAll().execute();
+	const remainingLogs = await lix.db
+		.selectFrom("log")
+		.where("key", "in", ["test_log_to_keep", "test_log_to_delete"])
+		.selectAll()
+		.execute();
 	expect(remainingLogs).toHaveLength(1);
-	expect(remainingLogs[0]?.key).toBe("log.to.keep");
+	expect(remainingLogs[0]?.key).toBe("test_log_to_keep");
 	expect(remainingLogs[0]?.message).toBe("Keep this log");
+	expect(remainingLogs[0]?.payload).toBeNull();
 
 	// Verify the deleted log is gone
 	const deletedLogs = await lix.db
@@ -107,24 +126,31 @@ test("multiple log inserts with unique ids", async () => {
 		.insertInto("log")
 		.values([
 			{
-				key: "log1",
+				key: "test_log1",
 				message: "First log",
+				payload: { idx: 1 },
 				level: "info",
 			},
 			{
-				key: "log2",
+				key: "test_log2",
 				message: "Second log",
+				payload: null,
 				level: "warn",
 			},
 			{
-				key: "log3",
+				key: "test_log3",
 				message: "Third log",
+				payload: { idx: 3 },
 				level: "error",
 			},
 		])
 		.execute();
 
-	const logs = await lix.db.selectFrom("log").selectAll().execute();
+	const logs = await lix.db
+		.selectFrom("log")
+		.where("key", "like", "test_log%")
+		.selectAll()
+		.execute();
 
 	expect(logs).toHaveLength(3);
 
@@ -134,7 +160,20 @@ test("multiple log inserts with unique ids", async () => {
 	expect(uniqueIds.size).toBe(3);
 
 	// Verify content
-	expect(logs.find((log) => log.key === "log1")?.message).toBe("First log");
-	expect(logs.find((log) => log.key === "log2")?.message).toBe("Second log");
-	expect(logs.find((log) => log.key === "log3")?.message).toBe("Third log");
+	expect(logs.find((log) => log.key === "test_log1")?.message).toBe(
+		"First log"
+	);
+	expect(logs.find((log) => log.key === "test_log1")?.payload).toEqual({
+		idx: 1,
+	});
+	expect(logs.find((log) => log.key === "test_log2")?.message).toBe(
+		"Second log"
+	);
+	expect(logs.find((log) => log.key === "test_log2")?.payload).toBeNull();
+	expect(logs.find((log) => log.key === "test_log3")?.message).toBe(
+		"Third log"
+	);
+	expect(logs.find((log) => log.key === "test_log3")?.payload).toEqual({
+		idx: 3,
+	});
 });