@ekodb/ekodb-client 0.6.1 → 0.7.1

package/dist/utils.test.js

@@ -0,0 +1,411 @@
+"use strict";
+/**
+ * Unit tests for ekoDB TypeScript client utility functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const utils_1 = require("./utils");
+// ============================================================================
+// getValue Tests
+// ============================================================================
+(0, vitest_1.describe)("getValue", () => {
+    (0, vitest_1.it)("extracts value from wrapped string field", () => {
+        const field = { type: "String", value: "hello world" };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBe("hello world");
+    });
+    (0, vitest_1.it)("extracts value from wrapped integer field", () => {
+        const field = { type: "Integer", value: 42 };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBe(42);
+    });
+    (0, vitest_1.it)("extracts value from wrapped float field", () => {
+        const field = { type: "Float", value: 3.14 };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBe(3.14);
+    });
+    (0, vitest_1.it)("extracts value from wrapped boolean field", () => {
+        const field = { type: "Boolean", value: true };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBe(true);
+    });
+    (0, vitest_1.it)("extracts value from wrapped null field", () => {
+        const field = { type: "Null", value: null };
+        (0, vitest_1.expect)((0, utils_1.getValue)(field)).toBeNull();
+    });
+    (0, vitest_1.it)("returns plain string as-is", () => {
+        (0, vitest_1.expect)((0, utils_1.getValue)("plain string")).toBe("plain string");
+    });
+    (0, vitest_1.it)("returns plain number as-is", () => {
+        (0, vitest_1.expect)((0, utils_1.getValue)(123)).toBe(123);
+    });
+    (0, vitest_1.it)("returns plain boolean as-is", () => {
+        (0, vitest_1.expect)((0, utils_1.getValue)(true)).toBe(true);
+        (0, vitest_1.expect)((0, utils_1.getValue)(false)).toBe(false);
+    });
+    (0, vitest_1.it)("returns null as-is", () => {
+        (0, vitest_1.expect)((0, utils_1.getValue)(null)).toBeNull();
+    });
+    (0, vitest_1.it)("returns undefined as-is", () => {
+        (0, vitest_1.expect)((0, utils_1.getValue)(undefined)).toBeUndefined();
+    });
+    (0, vitest_1.it)("returns plain array as-is", () => {
+        const arr = [1, 2, 3];
+        (0, vitest_1.expect)((0, utils_1.getValue)(arr)).toEqual([1, 2, 3]);
+    });
+    (0, vitest_1.it)("returns object without value key as-is", () => {
+        const obj = { name: "test", count: 5 };
+        (0, vitest_1.expect)((0, utils_1.getValue)(obj)).toEqual({ name: "test", count: 5 });
+    });
+    (0, vitest_1.it)("supports generic type parameter", () => {
+        const field = { type: "String", value: "typed" };
+        const result = (0, utils_1.getValue)(field);
+        (0, vitest_1.expect)(result).toBe("typed");
+    });
+});
+// ============================================================================
+// getValues Tests
+// ============================================================================
+(0, vitest_1.describe)("getValues", () => {
+    (0, vitest_1.it)("extracts multiple field values from record", () => {
+        const record = {
+            name: { type: "String", value: "John" },
+            age: { type: "Integer", value: 30 },
+            active: { type: "Boolean", value: true },
+        };
+        const result = (0, utils_1.getValues)(record, ["name", "age", "active"]);
+        (0, vitest_1.expect)(result).toEqual({ name: "John", age: 30, active: true });
+    });
+    (0, vitest_1.it)("extracts only requested fields", () => {
+        const record = {
+            name: { type: "String", value: "John" },
+            age: { type: "Integer", value: 30 },
+            email: { type: "String", value: "john@example.com" },
+        };
+        const result = (0, utils_1.getValues)(record, ["name", "email"]);
+        (0, vitest_1.expect)(result).toEqual({ name: "John", email: "john@example.com" });
+        (0, vitest_1.expect)(result).not.toHaveProperty("age");
+    });
+    (0, vitest_1.it)("handles missing fields gracefully", () => {
+        const record = {
+            name: { type: "String", value: "John" },
+        };
+        const result = (0, utils_1.getValues)(record, ["name", "missing"]);
+        (0, vitest_1.expect)(result.name).toBe("John");
+        (0, vitest_1.expect)(result.missing).toBeUndefined();
+    });
+    (0, vitest_1.it)("handles empty record", () => {
+        const result = (0, utils_1.getValues)({}, ["name", "age"]);
+        (0, vitest_1.expect)(result.name).toBeUndefined();
+        (0, vitest_1.expect)(result.age).toBeUndefined();
+    });
+    (0, vitest_1.it)("handles empty fields list", () => {
+        const record = { name: { type: "String", value: "John" } };
+        const result = (0, utils_1.getValues)(record, []);
+        (0, vitest_1.expect)(result).toEqual({});
+    });
+    (0, vitest_1.it)("handles mixed wrapped and plain values", () => {
+        const record = {
+            wrapped: { type: "String", value: "wrapped_value" },
+            plain: "plain_value",
+        };
+        const result = (0, utils_1.getValues)(record, ["wrapped", "plain"]);
+        (0, vitest_1.expect)(result).toEqual({ wrapped: "wrapped_value", plain: "plain_value" });
+    });
+});
+// ============================================================================
+// Specialized Value Extractors Tests
+// ============================================================================
+(0, vitest_1.describe)("getDateTimeValue", () => {
+    (0, vitest_1.it)("parses ISO format datetime string", () => {
+        const field = { type: "DateTime", value: "2024-01-15T10:30:00Z" };
+        const result = (0, utils_1.getDateTimeValue)(field);
+        (0, vitest_1.expect)(result).toBeInstanceOf(Date);
+        (0, vitest_1.expect)(result?.getFullYear()).toBe(2024);
+        (0, vitest_1.expect)(result?.getMonth()).toBe(0); // January is 0
+        (0, vitest_1.expect)(result?.getDate()).toBe(15);
+    });
+    (0, vitest_1.it)("parses ISO format with timezone offset", () => {
+        const field = { type: "DateTime", value: "2024-01-15T10:30:00+00:00" };
+        const result = (0, utils_1.getDateTimeValue)(field);
+        (0, vitest_1.expect)(result).toBeInstanceOf(Date);
+        (0, vitest_1.expect)(result?.getFullYear()).toBe(2024);
+    });
+    (0, vitest_1.it)("returns Date object as-is", () => {
+        const dt = new Date(2024, 0, 15, 10, 30, 0);
+        const field = { type: "DateTime", value: dt };
+        const result = (0, utils_1.getDateTimeValue)(field);
+        (0, vitest_1.expect)(result).toBe(dt);
+    });
+    (0, vitest_1.it)("returns null for invalid datetime string", () => {
+        const field = { type: "DateTime", value: "not-a-datetime" };
+        const result = (0, utils_1.getDateTimeValue)(field);
+        (0, vitest_1.expect)(result).toBeNull();
+    });
+    (0, vitest_1.it)("returns null for null value", () => {
+        (0, vitest_1.expect)((0, utils_1.getDateTimeValue)(null)).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getUUIDValue", () => {
+    (0, vitest_1.it)("extracts UUID from wrapped field", () => {
+        const field = {
+            type: "UUID",
+            value: "550e8400-e29b-41d4-a716-446655440000",
+        };
+        (0, vitest_1.expect)((0, utils_1.getUUIDValue)(field)).toBe("550e8400-e29b-41d4-a716-446655440000");
+    });
+    (0, vitest_1.it)("extracts UUID from plain string", () => {
+        (0, vitest_1.expect)((0, utils_1.getUUIDValue)("550e8400-e29b-41d4-a716-446655440000")).toBe("550e8400-e29b-41d4-a716-446655440000");
+    });
+    (0, vitest_1.it)("returns null for non-string", () => {
+        (0, vitest_1.expect)((0, utils_1.getUUIDValue)(12345)).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getDecimalValue", () => {
+    (0, vitest_1.it)("extracts decimal from integer", () => {
+        const field = { type: "Decimal", value: 42 };
+        (0, vitest_1.expect)((0, utils_1.getDecimalValue)(field)).toBe(42);
+    });
+    (0, vitest_1.it)("extracts decimal from float", () => {
+        const field = { type: "Decimal", value: 3.14159 };
+        (0, vitest_1.expect)((0, utils_1.getDecimalValue)(field)).toBeCloseTo(3.14159);
+    });
+    (0, vitest_1.it)("extracts decimal from string representation", () => {
+        const field = { type: "Decimal", value: "123.456" };
+        (0, vitest_1.expect)((0, utils_1.getDecimalValue)(field)).toBeCloseTo(123.456);
+    });
+    (0, vitest_1.it)("returns null for invalid decimal string", () => {
+        const field = { type: "Decimal", value: "not-a-number" };
+        (0, vitest_1.expect)((0, utils_1.getDecimalValue)(field)).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getDurationValue", () => {
+    (0, vitest_1.it)("extracts duration from number (milliseconds)", () => {
+        const field = { type: "Duration", value: 3600000 };
+        (0, vitest_1.expect)((0, utils_1.getDurationValue)(field)).toBe(3600000);
+    });
+    (0, vitest_1.it)("extracts duration from secs/nanos object", () => {
+        const field = { type: "Duration", value: { secs: 10, nanos: 500000000 } };
+        (0, vitest_1.expect)((0, utils_1.getDurationValue)(field)).toBeCloseTo(10500); // 10.5 seconds in ms
+    });
+    (0, vitest_1.it)("extracts duration from plain number", () => {
+        (0, vitest_1.expect)((0, utils_1.getDurationValue)(10500)).toBe(10500);
+    });
+});
+(0, vitest_1.describe)("getBytesValue", () => {
+    (0, vitest_1.it)("extracts bytes from Uint8Array", () => {
+        const bytes = new Uint8Array([104, 101, 108, 108, 111]);
+        const field = { type: "Bytes", value: bytes };
+        const result = (0, utils_1.getBytesValue)(field);
+        (0, vitest_1.expect)(result).toEqual(bytes);
+    });
+    (0, vitest_1.it)("extracts bytes from array of integers", () => {
+        const field = { type: "Bytes", value: [104, 101, 108, 108, 111] };
+        const result = (0, utils_1.getBytesValue)(field);
+        (0, vitest_1.expect)(result).toBeInstanceOf(Uint8Array);
+        (0, vitest_1.expect)(Array.from(result)).toEqual([104, 101, 108, 108, 111]);
+    });
+    (0, vitest_1.it)("extracts bytes from base64 string", () => {
+        const field = { type: "Bytes", value: btoa("hello") };
+        const result = (0, utils_1.getBytesValue)(field);
+        (0, vitest_1.expect)(result).toBeInstanceOf(Uint8Array);
+        (0, vitest_1.expect)(new TextDecoder().decode(result)).toBe("hello");
+    });
+    (0, vitest_1.it)("returns null for invalid bytes", () => {
+        (0, vitest_1.expect)((0, utils_1.getBytesValue)(12345)).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getBinaryValue", () => {
+    (0, vitest_1.it)("extracts binary from Uint8Array (alias for getBytesValue)", () => {
+        const bytes = new Uint8Array([1, 2, 3, 4]);
+        const field = { type: "Binary", value: bytes };
+        (0, vitest_1.expect)((0, utils_1.getBinaryValue)(field)).toEqual(bytes);
+    });
+});
+(0, vitest_1.describe)("getArrayValue", () => {
+    (0, vitest_1.it)("extracts array from wrapped field", () => {
+        const field = { type: "Array", value: [1, 2, 3, 4, 5] };
+        (0, vitest_1.expect)((0, utils_1.getArrayValue)(field)).toEqual([1, 2, 3, 4, 5]);
+    });
+    (0, vitest_1.it)("extracts array from plain array", () => {
+        (0, vitest_1.expect)((0, utils_1.getArrayValue)([1, 2, 3])).toEqual([1, 2, 3]);
+    });
+    (0, vitest_1.it)("returns null for non-array", () => {
+        (0, vitest_1.expect)((0, utils_1.getArrayValue)("not an array")).toBeNull();
+    });
+});
+(0, vitest_1.describe)("getSetValue", () => {
+    (0, vitest_1.it)("extracts set from wrapped field", () => {
+        const field = { type: "Set", value: ["a", "b", "c"] };
+        (0, vitest_1.expect)((0, utils_1.getSetValue)(field)).toEqual(["a", "b", "c"]);
+    });
+});
+(0, vitest_1.describe)("getVectorValue", () => {
+    (0, vitest_1.it)("extracts vector from array of floats", () => {
+        const field = { type: "Vector", value: [0.1, 0.2, 0.3, 0.4] };
+        (0, vitest_1.expect)((0, utils_1.getVectorValue)(field)).toEqual([0.1, 0.2, 0.3, 0.4]);
+    });
+    (0, vitest_1.it)("converts integers to floats", () => {
+        const field = { type: "Vector", value: [1, 2, 3] };
+        (0, vitest_1.expect)((0, utils_1.getVectorValue)(field)).toEqual([1, 2, 3]);
+    });
+    (0, vitest_1.it)("filters out invalid values", () => {
+        const field = { type: "Vector", value: [1, "invalid", 3] };
+        const result = (0, utils_1.getVectorValue)(field);
+        (0, vitest_1.expect)(result).toEqual([1, 3]);
+    });
+});
+(0, vitest_1.describe)("getObjectValue", () => {
+    (0, vitest_1.it)("extracts object from wrapped field", () => {
+        const field = { type: "Object", value: { key: "value", count: 5 } };
+        (0, vitest_1.expect)((0, utils_1.getObjectValue)(field)).toEqual({ key: "value", count: 5 });
+    });
+    (0, vitest_1.it)("returns null for non-object", () => {
+        (0, vitest_1.expect)((0, utils_1.getObjectValue)([1, 2, 3])).toBeNull();
+    });
+    (0, vitest_1.it)("returns null for array (not a plain object)", () => {
+        const field = { type: "Object", value: [1, 2, 3] };
+        (0, vitest_1.expect)((0, utils_1.getObjectValue)(field)).toBeNull();
+    });
+});
+// ============================================================================
+// Field Builder Tests
+// ============================================================================
+(0, vitest_1.describe)("Field builders", () => {
+    (0, vitest_1.it)("builds string field", () => {
+        (0, vitest_1.expect)(utils_1.Field.string("hello")).toEqual({ type: "String", value: "hello" });
+    });
+    (0, vitest_1.it)("builds integer field", () => {
+        (0, vitest_1.expect)(utils_1.Field.integer(42)).toEqual({ type: "Integer", value: 42 });
+    });
+    (0, vitest_1.it)("builds integer field (floors float)", () => {
+        (0, vitest_1.expect)(utils_1.Field.integer(42.9)).toEqual({ type: "Integer", value: 42 });
+    });
+    (0, vitest_1.it)("builds float field", () => {
+        (0, vitest_1.expect)(utils_1.Field.float(3.14)).toEqual({ type: "Float", value: 3.14 });
+    });
+    (0, vitest_1.it)("builds boolean field", () => {
+        (0, vitest_1.expect)(utils_1.Field.boolean(true)).toEqual({ type: "Boolean", value: true });
+        (0, vitest_1.expect)(utils_1.Field.boolean(false)).toEqual({ type: "Boolean", value: false });
+    });
+    (0, vitest_1.it)("builds UUID field", () => {
+        const uuid = "550e8400-e29b-41d4-a716-446655440000";
+        (0, vitest_1.expect)(utils_1.Field.uuid(uuid)).toEqual({ type: "UUID", value: uuid });
+    });
+    (0, vitest_1.it)("builds decimal field", () => {
+        (0, vitest_1.expect)(utils_1.Field.decimal("123.456")).toEqual({
+            type: "Decimal",
+            value: "123.456",
+        });
+    });
+    (0, vitest_1.it)("builds dateTime field from Date", () => {
+        const dt = new Date("2024-01-15T10:30:00Z");
+        const result = utils_1.Field.dateTime(dt);
+        (0, vitest_1.expect)(result.type).toBe("DateTime");
+        (0, vitest_1.expect)(result.value).toBe(dt.toISOString());
+    });
+    (0, vitest_1.it)("builds dateTime field from string", () => {
+        const result = utils_1.Field.dateTime("2024-01-15T10:30:00Z");
+        (0, vitest_1.expect)(result).toEqual({ type: "DateTime", value: "2024-01-15T10:30:00Z" });
+    });
+    (0, vitest_1.it)("builds duration field", () => {
+        (0, vitest_1.expect)(utils_1.Field.duration(3600000)).toEqual({
+            type: "Duration",
+            value: 3600000,
+        });
+    });
+    (0, vitest_1.it)("builds number field", () => {
+        (0, vitest_1.expect)(utils_1.Field.number(42)).toEqual({ type: "Number", value: 42 });
+        (0, vitest_1.expect)(utils_1.Field.number(3.14)).toEqual({ type: "Number", value: 3.14 });
+    });
+    (0, vitest_1.it)("builds array field", () => {
+        (0, vitest_1.expect)(utils_1.Field.array([1, 2, 3])).toEqual({ type: "Array", value: [1, 2, 3] });
+    });
+    (0, vitest_1.it)("builds set field", () => {
+        (0, vitest_1.expect)(utils_1.Field.set(["a", "b", "c"])).toEqual({
+            type: "Set",
+            value: ["a", "b", "c"],
+        });
+    });
+    (0, vitest_1.it)("builds vector field", () => {
+        (0, vitest_1.expect)(utils_1.Field.vector([0.1, 0.2, 0.3])).toEqual({
+            type: "Vector",
+            value: [0.1, 0.2, 0.3],
+        });
+    });
+    (0, vitest_1.it)("builds object field", () => {
+        (0, vitest_1.expect)(utils_1.Field.object({ key: "value" })).toEqual({
+            type: "Object",
+            value: { key: "value" },
+        });
+    });
+    (0, vitest_1.it)("builds bytes field from Uint8Array", () => {
+        const bytes = new Uint8Array([104, 101, 108, 108, 111]);
+        const result = utils_1.Field.bytes(bytes);
+        (0, vitest_1.expect)(result.type).toBe("Bytes");
+        (0, vitest_1.expect)(typeof result.value).toBe("string"); // Base64 encoded
+    });
+    (0, vitest_1.it)("builds bytes field from base64 string", () => {
+        const result = utils_1.Field.bytes("aGVsbG8=");
+        (0, vitest_1.expect)(result).toEqual({ type: "Bytes", value: "aGVsbG8=" });
+    });
+    (0, vitest_1.it)("builds binary field from Uint8Array", () => {
+        const bytes = new Uint8Array([1, 2, 3, 4]);
+        const result = utils_1.Field.binary(bytes);
+        (0, vitest_1.expect)(result.type).toBe("Binary");
+        (0, vitest_1.expect)(typeof result.value).toBe("string"); // Base64 encoded
+    });
+});
+// ============================================================================
+// extractRecord Tests
+// ============================================================================
+(0, vitest_1.describe)("extractRecord", () => {
+    (0, vitest_1.it)("extracts all fields from a record", () => {
+        const record = {
+            id: "user_123",
+            name: { type: "String", value: "John Doe" },
+            age: { type: "Integer", value: 30 },
+            active: { type: "Boolean", value: true },
+        };
+        const result = (0, utils_1.extractRecord)(record);
+        (0, vitest_1.expect)(result).toEqual({
+            id: "user_123",
+            name: "John Doe",
+            age: 30,
+            active: true,
+        });
+    });
+    (0, vitest_1.it)("preserves id field as-is", () => {
+        const record = {
+            id: "user_123",
+            name: { type: "String", value: "John" },
+        };
+        const result = (0, utils_1.extractRecord)(record);
+        (0, vitest_1.expect)(result.id).toBe("user_123");
+    });
+    (0, vitest_1.it)("handles nested objects", () => {
+        const record = {
+            user: { type: "Object", value: { name: "John", role: "admin" } },
+            tags: { type: "Array", value: ["python", "rust"] },
+        };
+        const result = (0, utils_1.extractRecord)(record);
+        (0, vitest_1.expect)(result.user).toEqual({ name: "John", role: "admin" });
+        (0, vitest_1.expect)(result.tags).toEqual(["python", "rust"]);
+    });
+    (0, vitest_1.it)("handles empty record", () => {
+        (0, vitest_1.expect)((0, utils_1.extractRecord)({})).toEqual({});
+    });
+    (0, vitest_1.it)("handles null/undefined input", () => {
+        (0, vitest_1.expect)((0, utils_1.extractRecord)(null)).toBeNull();
+        (0, vitest_1.expect)((0, utils_1.extractRecord)(undefined)).toBeUndefined();
+    });
+    (0, vitest_1.it)("handles non-object input", () => {
+        (0, vitest_1.expect)((0, utils_1.extractRecord)("string")).toBe("string");
+        (0, vitest_1.expect)((0, utils_1.extractRecord)(123)).toBe(123);
+    });
+    (0, vitest_1.it)("handles null field values", () => {
+        const record = {
+            name: { type: "String", value: "John" },
+            optional: { type: "Null", value: null },
+        };
+        const result = (0, utils_1.extractRecord)(record);
+        (0, vitest_1.expect)(result.name).toBe("John");
+        (0, vitest_1.expect)(result.optional).toBeNull();
+    });
+});

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "ekodb",
@@ -17,9 +19,10 @@
   "author": "ekoDB",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.0.3",
     "@types/ws": "^8.5.10",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^3.2.0"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.0.0",

package/src/client.ts

@@ -441,6 +441,9 @@ export class EkoDBClient {
 
   /**
    * Insert a document into a collection
+   * @param collection - Collection name
+   * @param record - Document to insert
+   * @param ttl - Optional TTL: duration string ("1h", "30m"), seconds ("3600"), or ISO8601 timestamp
    */
   async insert(
     collection: string,
@@ -449,7 +452,7 @@ export class EkoDBClient {
   ): Promise<Record> {
     const data = { ...record };
     if (ttl) {
-      data.ttl_duration = ttl;
+      data.ttl = ttl;
     }
     return this.makeRequest<Record>("POST", `/api/insert/${collection}`, data);
   }
@@ -491,7 +494,7 @@ export class EkoDBClient {
   /**
    * Find a document by ID
    */
-  async findByID(collection: string, id: string): Promise<Record> {
+  async findById(collection: string, id: string): Promise<Record> {
     return this.makeRequest<Record>("GET", `/api/find/${collection}/${id}`);
   }
 
@@ -575,13 +578,20 @@ export class EkoDBClient {
   }
 
   /**
-   * Set a key-value pair
+   * Set a key-value pair with optional TTL
+   * @param key - The key to set
+   * @param value - The value to store
+   * @param ttl - Optional TTL in seconds
    */
-  async kvSet(key: string, value: any): Promise<void> {
+  async kvSet(key: string, value: any, ttl?: number): Promise<void> {
+    const body: any = { value };
+    if (ttl !== undefined) {
+      body.ttl = ttl;
+    }
     await this.makeRequest<void>(
       "POST",
       `/api/kv/set/${encodeURIComponent(key)}`,
-      { value },
+      body,
       0,
       true, // Force JSON for KV operations
     );
@@ -614,6 +624,116 @@ export class EkoDBClient {
     );
   }
 
+  /**
+   * Check if a key exists
+   * @param key - The key to check
+   * @returns true if the key exists, false otherwise
+   */
+  async kvExists(key: string): Promise<boolean> {
+    try {
+      const result = await this.kvGet(key);
+      return result !== null && result !== undefined;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Query/find KV entries with pattern matching
+   * @param options - Query options including pattern and include_expired
+   * @returns Array of matching records
+   */
+  async kvFind(options?: {
+    pattern?: string;
+    include_expired?: boolean;
+  }): Promise<any[]> {
+    const result = await this.makeRequest<any[]>(
+      "POST",
+      "/api/kv/find",
+      options || {},
+      0,
+      true, // Force JSON for KV operations
+    );
+    return result;
+  }
+
+  /**
+   * Alias for kvFind - query KV store with pattern
+   */
+  async kvQuery(options?: {
+    pattern?: string;
+    include_expired?: boolean;
+  }): Promise<any[]> {
+    return this.kvFind(options);
+  }
+
+  // ============================================================================
+  // Transaction Operations
+  // ============================================================================
+
+  /**
+   * Begin a new transaction
+   * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
+   * @returns Transaction ID
+   */
+  async beginTransaction(
+    isolationLevel: string = "ReadCommitted",
+  ): Promise<string> {
+    const result = await this.makeRequest<{ transaction_id: string }>(
+      "POST",
+      "/api/transactions",
+      { isolation_level: isolationLevel },
+      0,
+      true,
+    );
+    return result.transaction_id;
+  }
+
+  /**
+   * Get transaction status
+   * @param transactionId - The transaction ID
+   * @returns Transaction status object
+   */
+  async getTransactionStatus(
+    transactionId: string,
+  ): Promise<{ state: string; operations_count: number }> {
+    return this.makeRequest<{ state: string; operations_count: number }>(
+      "GET",
+      `/api/transactions/${encodeURIComponent(transactionId)}`,
+      undefined,
+      0,
+      true,
+    );
+  }
+
+  /**
+   * Commit a transaction
+   * @param transactionId - The transaction ID to commit
+   */
+  async commitTransaction(transactionId: string): Promise<void> {
+    await this.makeRequest<void>(
+      "POST",
+      `/api/transactions/${encodeURIComponent(transactionId)}/commit`,
+      undefined,
+      0,
+      true,
+    );
+  }
+
+  /**
+   * Rollback a transaction
+   * @param transactionId - The transaction ID to rollback
+   */
+  async rollbackTransaction(transactionId: string): Promise<void> {
+    await this.makeRequest<void>(
+      "POST",
+      `/api/transactions/${encodeURIComponent(transactionId)}/rollback`,
+      undefined,
+      0,
+      true,
+    );
+  }
+
   /**
    * List all collections
    */

package/src/functions.ts

@@ -187,6 +187,31 @@ export type FunctionStageConfig =
   | {
       type: "ReleaseSavepoint";
       name: string;
+    }
+  | {
+      type: "KvGet";
+      key: string;
+      output_field?: string;
+    }
+  | {
+      type: "KvSet";
+      key: string;
+      value: any;
+      ttl?: number;
+    }
+  | {
+      type: "KvDelete";
+      key: string;
+    }
+  | {
+      type: "KvExists";
+      key: string;
+      output_field?: string;
+    }
+  | {
+      type: "KvQuery";
+      pattern?: string;
+      include_expired?: boolean;
     };
 
 export interface ChatMessage {
@@ -572,4 +597,38 @@ export const Stage = {
     type: "ReleaseSavepoint",
     name,
   }),
+
+  // KV Store operations - faster than collection lookups for simple key-value data
+  kvGet: (key: string, output_field?: string): FunctionStageConfig => ({
+    type: "KvGet",
+    key,
+    output_field,
+  }),
+
+  kvSet: (key: string, value: any, ttl?: number): FunctionStageConfig => ({
+    type: "KvSet",
+    key,
+    value,
+    ttl,
+  }),
+
+  kvDelete: (key: string): FunctionStageConfig => ({
+    type: "KvDelete",
+    key,
+  }),
+
+  kvExists: (key: string, output_field?: string): FunctionStageConfig => ({
+    type: "KvExists",
+    key,
+    output_field,
+  }),
+
+  kvQuery: (
+    pattern?: string,
+    include_expired?: boolean,
+  ): FunctionStageConfig => ({
+    type: "KvQuery",
+    pattern,
+    include_expired,
+  }),
 };

package/src/index.ts

@@ -29,7 +29,9 @@ export {
   getSetValue,
   getVectorValue,
   getObjectValue,
+  Field,
 } from "./utils";
+export type { WrappedFieldValue } from "./utils";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type {
   Schema,