@kernl-sdk/libsql 0.1.38 → 0.1.39

package/dist/memory/__tests__/create-get.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-get.test.d.ts","sourceRoot":"","sources":["../../../src/memory/__tests__/create-get.test.ts"],"names":[],"mappings":""}

package/dist/memory/__tests__/create-get.test.js

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { create_client, create_storage, testid } from "../../__tests__/helpers.js";
+describe("LibSQLMemoryStore create/get", () => {
+    let client;
+    let storage;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        await storage.memories.list(); // init
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("creates and reads text memory", async () => {
+        const id = testid("mem");
+        const created = await storage.memories.create({
+            id,
+            scope: { namespace: "default", entityId: "user-1", agentId: "agent-1" },
+            kind: "semantic",
+            collection: "facts",
+            content: { text: "User prefers dark mode" },
+        });
+        expect(created.id).toBe(id);
+        expect(created.content).toEqual({ text: "User prefers dark mode" });
+        expect(created.kind).toBe("semantic");
+        const found = await storage.memories.get(id);
+        expect(found).not.toBeNull();
+        expect(found?.content).toEqual({ text: "User prefers dark mode" });
+        expect(found?.scope.namespace).toBe("default");
+        expect(found?.scope.entityId).toBe("user-1");
+    });
+    it("creates and reads object memory", async () => {
+        const id = testid("mem");
+        const objectContent = {
+            object: {
+                preferences: {
+                    theme: "dark",
+                    language: "en",
+                    notifications: true,
+                },
+            },
+        };
+        const created = await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: objectContent,
+        });
+        expect(created.content).toEqual(objectContent);
+        const found = await storage.memories.get(id);
+        expect(found?.content).toEqual(objectContent);
+    });
+    it("creates working memory (wmem=true)", async () => {
+        const id = testid("mem");
+        const created = await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "episodic",
+            content: { text: "Current task context" },
+            wmem: true,
+        });
+        expect(created.wmem).toBe(true);
+        const found = await storage.memories.get(id);
+        expect(found?.wmem).toBe(true);
+    });
+    it("creates short-term memory with expiration", async () => {
+        const id = testid("mem");
+        const expiresAt = Date.now() + 3600000; // 1 hour from now
+        const created = await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "episodic",
+            content: { text: "Temporary note" },
+            smem: { expiresAt },
+        });
+        expect(created.smem.expiresAt).toBe(expiresAt);
+        const found = await storage.memories.get(id);
+        expect(found?.smem.expiresAt).toBe(expiresAt);
+    });
+    it("gets by id and returns null when missing", async () => {
+        const found = await storage.memories.get("nonexistent");
+        expect(found).toBeNull();
+    });
+    it("handles null scope fields", async () => {
+        const id = testid("mem");
+        const created = await storage.memories.create({
+            id,
+            scope: {}, // All scope fields null
+            kind: "semantic",
+            content: { text: "Global memory" },
+        });
+        expect(created.scope.namespace).toBeUndefined();
+        expect(created.scope.entityId).toBeUndefined();
+        expect(created.scope.agentId).toBeUndefined();
+        const found = await storage.memories.get(id);
+        expect(found?.scope.namespace).toBeUndefined();
+    });
+    it("stores and retrieves metadata", async () => {
+        const id = testid("mem");
+        const metadata = { confidence: 0.95, source: "user_input", version: 2 };
+        const created = await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "Test" },
+            metadata,
+        });
+        expect(created.metadata).toEqual(metadata);
+        const found = await storage.memories.get(id);
+        expect(found?.metadata).toEqual(metadata);
+    });
+    it("sets timestamps on create", async () => {
+        const before = Date.now();
+        const created = await storage.memories.create({
+            id: testid("mem"),
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "Test" },
+        });
+        const after = Date.now();
+        expect(created.timestamp).toBeGreaterThanOrEqual(before);
+        expect(created.timestamp).toBeLessThanOrEqual(after);
+        expect(created.createdAt).toBeGreaterThanOrEqual(before);
+        expect(created.updatedAt).toBeGreaterThanOrEqual(before);
+    });
+});

package/dist/memory/__tests__/delete.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=delete.test.d.ts.map

package/dist/memory/__tests__/delete.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.test.d.ts","sourceRoot":"","sources":["../../../src/memory/__tests__/delete.test.ts"],"names":[],"mappings":""}

package/dist/memory/__tests__/delete.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { create_client, create_storage, testid } from "../../__tests__/helpers.js";
+describe("LibSQLMemoryStore delete", () => {
+    let client;
+    let storage;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        await storage.memories.list(); // init
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("deletes by id", async () => {
+        const id = testid("mem");
+        await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "To be deleted" },
+        });
+        // Verify exists
+        const before = await storage.memories.get(id);
+        expect(before).not.toBeNull();
+        // Delete
+        await storage.memories.delete(id);
+        // Verify gone
+        const after = await storage.memories.get(id);
+        expect(after).toBeNull();
+    });
+    it("delete is idempotent (no error for missing)", async () => {
+        // Should not throw
+        await storage.memories.delete("nonexistent");
+    });
+    it("mdelete removes multiple ids", async () => {
+        const ids = [testid("m1"), testid("m2"), testid("m3")];
+        // Create memories
+        for (const id of ids) {
+            await storage.memories.create({
+                id,
+                scope: { namespace: "default" },
+                kind: "semantic",
+                content: { text: `Memory ${id}` },
+            });
+        }
+        // Verify all exist
+        for (const id of ids) {
+            expect(await storage.memories.get(id)).not.toBeNull();
+        }
+        // Delete all
+        await storage.memories.mdelete(ids);
+        // Verify all gone
+        for (const id of ids) {
+            expect(await storage.memories.get(id)).toBeNull();
+        }
+    });
+    it("mdelete handles partial matches", async () => {
+        const existing = testid("existing");
+        await storage.memories.create({
+            id: existing,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "Exists" },
+        });
+        // Delete mix of existing and non-existing
+        await storage.memories.mdelete([existing, "nonexistent-1", "nonexistent-2"]);
+        // Existing should be deleted
+        expect(await storage.memories.get(existing)).toBeNull();
+    });
+    it("mdelete handles empty array", async () => {
+        // Create a memory to ensure it's not affected
+        const id = testid("mem");
+        await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "Should remain" },
+        });
+        // Should not throw and not affect anything
+        await storage.memories.mdelete([]);
+        // Memory should still exist
+        const found = await storage.memories.get(id);
+        expect(found).not.toBeNull();
+    });
+    it("mdelete with single id", async () => {
+        const id = testid("mem");
+        await storage.memories.create({
+            id,
+            scope: { namespace: "default" },
+            kind: "semantic",
+            content: { text: "Single" },
+        });
+        await storage.memories.mdelete([id]);
+        expect(await storage.memories.get(id)).toBeNull();
+    });
+});

package/dist/memory/__tests__/list.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=list.test.d.ts.map

package/dist/memory/__tests__/list.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.test.d.ts","sourceRoot":"","sources":["../../../src/memory/__tests__/list.test.ts"],"names":[],"mappings":""}

package/dist/memory/__tests__/list.test.js

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { create_client, create_storage } from "../../__tests__/helpers.js";
+describe("LibSQLMemoryStore list", () => {
+    let client;
+    let storage;
+    beforeEach(async () => {
+        client = create_client();
+        storage = create_storage(client);
+        await storage.memories.list(); // init
+        // Seed test data
+        const now = Date.now();
+        await storage.memories.create({
+            id: "m1",
+            scope: { namespace: "ns1", entityId: "user-1", agentId: "agent-1" },
+            kind: "semantic",
+            collection: "facts",
+            content: { text: "Fact 1" },
+            wmem: true,
+            timestamp: now,
+        });
+        await storage.memories.create({
+            id: "m2",
+            scope: { namespace: "ns1", entityId: "user-1", agentId: "agent-1" },
+            kind: "semantic",
+            collection: "preferences",
+            content: { text: "Preference 1" },
+            wmem: false,
+            smem: { expiresAt: now + 3600000 },
+            timestamp: now + 100,
+        });
+        await storage.memories.create({
+            id: "m3",
+            scope: { namespace: "ns1", entityId: "user-2", agentId: "agent-1" },
+            kind: "episodic",
+            collection: "facts",
+            content: { text: "Fact 2" },
+            wmem: true,
+            timestamp: now + 200,
+        });
+        await storage.memories.create({
+            id: "m4",
+            scope: { namespace: "ns2", entityId: "user-1", agentId: "agent-2" },
+            kind: "semantic",
+            collection: "facts",
+            content: { text: "Fact 3" },
+            timestamp: now + 300,
+        });
+    });
+    afterEach(() => {
+        client.close();
+    });
+    it("lists all memories without filter", async () => {
+        const memories = await storage.memories.list();
+        expect(memories.length).toBe(4);
+    });
+    it("filters by namespace", async () => {
+        const memories = await storage.memories.list({
+            filter: { scope: { namespace: "ns1" } },
+        });
+        expect(memories.length).toBe(3);
+        expect(memories.every((m) => m.scope.namespace === "ns1")).toBe(true);
+    });
+    it("filters by entityId", async () => {
+        const memories = await storage.memories.list({
+            filter: { scope: { entityId: "user-1" } },
+        });
+        expect(memories.length).toBe(3);
+        expect(memories.every((m) => m.scope.entityId === "user-1")).toBe(true);
+    });
+    it("filters by agentId", async () => {
+        const memories = await storage.memories.list({
+            filter: { scope: { agentId: "agent-1" } },
+        });
+        expect(memories.length).toBe(3);
+    });
+    it("filters by multiple scope fields", async () => {
+        const memories = await storage.memories.list({
+            filter: {
+                scope: { namespace: "ns1", entityId: "user-1" },
+            },
+        });
+        expect(memories.length).toBe(2);
+    });
+    it("filters by collection", async () => {
+        const memories = await storage.memories.list({
+            filter: { collections: ["facts"] },
+        });
+        expect(memories.length).toBe(3);
+        expect(memories.every((m) => m.collection === "facts")).toBe(true);
+    });
+    it("filters by multiple collections", async () => {
+        const memories = await storage.memories.list({
+            filter: { collections: ["facts", "preferences"] },
+        });
+        expect(memories.length).toBe(4);
+    });
+    it("filters by wmem", async () => {
+        const wmemTrue = await storage.memories.list({
+            filter: { wmem: true },
+        });
+        expect(wmemTrue.length).toBe(2);
+        expect(wmemTrue.every((m) => m.wmem === true)).toBe(true);
+        const wmemFalse = await storage.memories.list({
+            filter: { wmem: false },
+        });
+        expect(wmemFalse.length).toBe(2);
+    });
+    it("filters by smem (has expiration)", async () => {
+        const hasSmem = await storage.memories.list({
+            filter: { smem: true },
+        });
+        expect(hasSmem.length).toBe(1);
+        expect(hasSmem[0].id).toBe("m2");
+        const noSmem = await storage.memories.list({
+            filter: { smem: false },
+        });
+        expect(noSmem.length).toBe(3);
+    });
+    it("filters by timestamp range", async () => {
+        const now = Date.now();
+        const m1 = await storage.memories.get("m1");
+        const m2 = await storage.memories.get("m2");
+        const memories = await storage.memories.list({
+            filter: {
+                after: m1.timestamp - 1,
+                before: m2.timestamp + 1,
+            },
+        });
+        expect(memories.length).toBe(2);
+        expect(memories.map((m) => m.id).sort()).toEqual(["m1", "m2"]);
+    });
+    it("orders by timestamp desc (default)", async () => {
+        const memories = await storage.memories.list();
+        // Should be in desc order by default
+        for (let i = 1; i < memories.length; i++) {
+            expect(memories[i - 1].timestamp).toBeGreaterThanOrEqual(memories[i].timestamp);
+        }
+    });
+    it("orders by timestamp asc", async () => {
+        const memories = await storage.memories.list({ order: "asc" });
+        for (let i = 1; i < memories.length; i++) {
+            expect(memories[i - 1].timestamp).toBeLessThanOrEqual(memories[i].timestamp);
+        }
+    });
+    it("applies limit", async () => {
+        const memories = await storage.memories.list({ limit: 2 });
+        expect(memories.length).toBe(2);
+    });
+    it("applies offset", async () => {
+        const all = await storage.memories.list({ order: "asc" });
+        const offset = await storage.memories.list({ order: "asc", offset: 2 });
+        expect(offset.length).toBe(2);
+        expect(offset[0].id).toBe(all[2].id);
+    });
+    it("combines filters, order, limit, and offset", async () => {
+        const memories = await storage.memories.list({
+            filter: {
+                scope: { namespace: "ns1" },
+                collections: ["facts"],
+            },
+            order: "asc",
+            limit: 1,
+            offset: 1,
+        });
+        expect(memories.length).toBe(1);
+        expect(memories[0].id).toBe("m3");
+    });
+});

package/dist/memory/__tests__/sql.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sql.test.d.ts.map

package/dist/memory/__tests__/sql.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.test.d.ts","sourceRoot":"","sources":["../../../src/memory/__tests__/sql.test.ts"],"names":[],"mappings":""}

package/dist/memory/__tests__/sql.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from "vitest";
+import { SQL_WHERE, ORDER, SQL_UPDATE } from "../sql.js";
+describe("LibSQL memory SQL codecs", () => {
+    describe("SQL_WHERE", () => {
+        it("returns empty clause when no filters", () => {
+            const result = SQL_WHERE.encode({ filter: undefined });
+            expect(result.sql).toBe("");
+            expect(result.params).toEqual([]);
+        });
+        it("encodes scope namespace filter", () => {
+            const result = SQL_WHERE.encode({
+                filter: { scope: { namespace: "default" } },
+            });
+            expect(result.sql).toBe("namespace = ?");
+            expect(result.params).toEqual(["default"]);
+        });
+        it("encodes scope entityId filter", () => {
+            const result = SQL_WHERE.encode({
+                filter: { scope: { entityId: "user-1" } },
+            });
+            expect(result.sql).toBe("entity_id = ?");
+            expect(result.params).toEqual(["user-1"]);
+        });
+        it("encodes scope agentId filter", () => {
+            const result = SQL_WHERE.encode({
+                filter: { scope: { agentId: "agent-1" } },
+            });
+            expect(result.sql).toBe("agent_id = ?");
+            expect(result.params).toEqual(["agent-1"]);
+        });
+        it("encodes full scope filter", () => {
+            const result = SQL_WHERE.encode({
+                filter: {
+                    scope: {
+                        namespace: "default",
+                        entityId: "user-1",
+                        agentId: "agent-1",
+                    },
+                },
+            });
+            expect(result.sql).toBe("namespace = ? AND entity_id = ? AND agent_id = ?");
+            expect(result.params).toEqual(["default", "user-1", "agent-1"]);
+        });
+        it("encodes collections filter with IN clause", () => {
+            const result = SQL_WHERE.encode({
+                filter: { collections: ["facts", "preferences"] },
+            });
+            expect(result.sql).toBe("collection IN (?, ?)");
+            expect(result.params).toEqual(["facts", "preferences"]);
+        });
+        it("encodes wmem filter", () => {
+            const result = SQL_WHERE.encode({ filter: { wmem: true } });
+            expect(result.sql).toBe("wmem = ?");
+            expect(result.params).toEqual([1]); // SQLite boolean
+        });
+        it("encodes smem filter (has valid expiration)", () => {
+            const before = Date.now();
+            const result = SQL_WHERE.encode({ filter: { smem: true } });
+            const after = Date.now();
+            // smem=true means has expiration AND not expired
+            expect(result.sql).toBe("(smem_expires_at IS NOT NULL AND smem_expires_at > ?)");
+            expect(result.params.length).toBe(1);
+            expect(result.params[0]).toBeGreaterThanOrEqual(before);
+            expect(result.params[0]).toBeLessThanOrEqual(after);
+        });
+        it("encodes smem=false filter (no expiration or expired)", () => {
+            const before = Date.now();
+            const result = SQL_WHERE.encode({ filter: { smem: false } });
+            const after = Date.now();
+            // smem=false means no expiration OR already expired
+            expect(result.sql).toBe("(smem_expires_at IS NULL OR smem_expires_at <= ?)");
+            expect(result.params.length).toBe(1);
+            expect(result.params[0]).toBeGreaterThanOrEqual(before);
+            expect(result.params[0]).toBeLessThanOrEqual(after);
+        });
+        it("encodes timestamp range filters", () => {
+            const result = SQL_WHERE.encode({
+                filter: { after: 1700000000000, before: 1700100000000 },
+            });
+            expect(result.sql).toBe("timestamp > ? AND timestamp < ?");
+            expect(result.params).toEqual([1700000000000, 1700100000000]);
+        });
+        it("combines multiple filters with AND", () => {
+            const result = SQL_WHERE.encode({
+                filter: {
+                    scope: { namespace: "default" },
+                    wmem: true,
+                    collections: ["facts"],
+                },
+            });
+            expect(result.sql).toContain("namespace = ?");
+            expect(result.sql).toContain("wmem = ?");
+            expect(result.sql).toContain("collection IN (?)");
+            expect(result.sql.match(/AND/g)?.length).toBe(2);
+        });
+    });
+    describe("ORDER", () => {
+        it("returns default ordering (desc)", () => {
+            const result = ORDER.encode({ order: undefined });
+            expect(result).toBe("timestamp DESC");
+        });
+        it("encodes asc order", () => {
+            const result = ORDER.encode({ order: "asc" });
+            expect(result).toBe("timestamp ASC");
+        });
+        it("encodes desc order", () => {
+            const result = ORDER.encode({ order: "desc" });
+            expect(result).toBe("timestamp DESC");
+        });
+    });
+    describe("SQL_UPDATE", () => {
+        it("encodes content update with JSON stringify", () => {
+            const content = { text: "Updated content" };
+            const result = SQL_UPDATE.encode({ patch: { id: "m1", content } });
+            expect(result.sql).toContain("content = ?");
+            expect(result.params).toContain(JSON.stringify(content));
+        });
+        it("encodes wmem flag update", () => {
+            const result = SQL_UPDATE.encode({ patch: { id: "m1", wmem: true } });
+            expect(result.sql).toContain("wmem = ?");
+            expect(result.params).toContain(1); // SQLite boolean
+        });
+        it("encodes smem expiration update", () => {
+            const result = SQL_UPDATE.encode({
+                patch: { id: "m1", smem: { expiresAt: 1700100000000 } },
+            });
+            expect(result.sql).toContain("smem_expires_at = ?");
+            expect(result.params).toContain(1700100000000);
+        });
+        it("encodes metadata update", () => {
+            const metadata = { confidence: 0.95 };
+            const result = SQL_UPDATE.encode({ patch: { id: "m1", metadata } });
+            expect(result.sql).toContain("metadata = ?");
+            expect(result.params).toContain(JSON.stringify(metadata));
+        });
+        it("always includes updated_at", () => {
+            const before = Date.now();
+            const result = SQL_UPDATE.encode({ patch: { id: "m1", wmem: false } });
+            const after = Date.now();
+            expect(result.sql).toContain("updated_at = ?");
+            const updatedAt = result.params.find((p) => typeof p === "number" && p >= before && p <= after);
+            expect(updatedAt).toBeDefined();
+        });
+        it("combines multiple updates", () => {
+            const result = SQL_UPDATE.encode({
+                patch: {
+                    id: "m1",
+                    content: { text: "New" },
+                    wmem: true,
+                    metadata: { edited: true },
+                },
+            });
+            expect(result.sql).toContain("content = ?");
+            expect(result.sql).toContain("wmem = ?");
+            expect(result.sql).toContain("metadata = ?");
+            expect(result.sql).toContain("updated_at = ?");
+        });
+    });
+});

package/dist/memory/__tests__/update.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=update.test.d.ts.map

package/dist/memory/__tests__/update.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.test.d.ts","sourceRoot":"","sources":["../../../src/memory/__tests__/update.test.ts"],"names":[],"mappings":""}