@ekodb/ekodb-client 0.6.0 → 0.7.0

package/dist/utils.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * Utility functions for working with ekoDB records
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Field = void 0;
+exports.getValue = getValue;
+exports.getValues = getValues;
+exports.getDateTimeValue = getDateTimeValue;
+exports.getUUIDValue = getUUIDValue;
+exports.getDecimalValue = getDecimalValue;
+exports.getDurationValue = getDurationValue;
+exports.getBytesValue = getBytesValue;
+exports.getBinaryValue = getBinaryValue;
+exports.getArrayValue = getArrayValue;
+exports.getSetValue = getSetValue;
+exports.getVectorValue = getVectorValue;
+exports.getObjectValue = getObjectValue;
+exports.extractRecord = extractRecord;
+/**
+ * Extract the value from an ekoDB field object.
+ * ekoDB returns fields as { type: string, value: any } objects.
+ * This helper safely extracts the value or returns the input if it's not a field object.
+ *
+ * @param field - The field value from ekoDB (may be { type, value } or a plain value)
+ * @returns The extracted value
+ *
+ * @example
+ * ```typescript
+ * const user = await client.findByID('users', userId);
+ * const email = getValue(user.email); // Extracts string from { type: 'String', value: 'user@example.com' }
+ * const age = getValue(user.age);     // Extracts number from { type: 'Integer', value: 25 }
+ * ```
+ */
+function getValue(field) {
+    if (field && typeof field === "object" && "value" in field) {
+        return field.value;
+    }
+    return field;
+}
+/**
+ * Extract values from multiple fields in a record.
+ * Useful for processing entire records returned from ekoDB.
+ *
+ * @param record - The record object from ekoDB
+ * @param fields - Array of field names to extract values from
+ * @returns Object with extracted values
+ *
+ * @example
+ * ```typescript
+ * const user = await client.findByID('users', userId);
+ * const { email, first_name, status } = getValues(user, ['email', 'first_name', 'status']);
+ * ```
+ */
+function getValues(record, fields) {
+    const result = {};
+    for (const field of fields) {
+        result[field] = getValue(record[field]);
+    }
+    return result;
+}
+/**
+ * Extract a Date value from an ekoDB DateTime field
+ */
+function getDateTimeValue(field) {
+    const val = getValue(field);
+    if (val instanceof Date)
+        return val;
+    if (typeof val === "string") {
+        const date = new Date(val);
+        return isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}
+/**
+ * Extract a UUID string from an ekoDB UUID field
+ */
+function getUUIDValue(field) {
+    const val = getValue(field);
+    return typeof val === "string" ? val : null;
+}
+/**
+ * Extract a number from an ekoDB Decimal field
+ */
+function getDecimalValue(field) {
+    const val = getValue(field);
+    if (typeof val === "number")
+        return val;
+    if (typeof val === "string") {
+        const num = parseFloat(val);
+        return isNaN(num) ? null : num;
+    }
+    return null;
+}
+/**
+ * Extract a number (milliseconds) from an ekoDB Duration field
+ */
+function getDurationValue(field) {
+    const val = getValue(field);
+    if (typeof val === "number")
+        return val;
+    if (typeof val === "object" && val.secs !== undefined) {
+        return val.secs * 1000 + val.nanos / 1000000;
+    }
+    return null;
+}
+/**
+ * Extract a Uint8Array from an ekoDB Bytes field
+ */
+function getBytesValue(field) {
+    const val = getValue(field);
+    if (val instanceof Uint8Array)
+        return val;
+    if (Array.isArray(val))
+        return new Uint8Array(val);
+    if (typeof val === "string") {
+        // Assume base64 encoded
+        try {
+            const binary = atob(val);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i);
+            }
+            return bytes;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Extract a Uint8Array from an ekoDB Binary field
+ */
+function getBinaryValue(field) {
+    return getBytesValue(field);
+}
+/**
+ * Extract an array from an ekoDB Array field
+ */
+function getArrayValue(field) {
+    const val = getValue(field);
+    return Array.isArray(val) ? val : null;
+}
+/**
+ * Extract an array from an ekoDB Set field
+ */
+function getSetValue(field) {
+    const val = getValue(field);
+    return Array.isArray(val) ? val : null;
+}
+/**
+ * Extract an array from an ekoDB Vector field
+ */
+function getVectorValue(field) {
+    const val = getValue(field);
+    if (Array.isArray(val)) {
+        return val
+            .map((v) => (typeof v === "number" ? v : parseFloat(v)))
+            .filter((v) => !isNaN(v));
+    }
+    return null;
+}
+/**
+ * Extract an object from an ekoDB Object field
+ */
+function getObjectValue(field) {
+    const val = getValue(field);
+    return val && typeof val === "object" && !Array.isArray(val) ? val : null;
+}
+/**
+ * Transform an entire record by extracting all field values.
+ * Preserves the 'id' field and extracts values from all other fields.
+ *
+ * @param record - The record object from ekoDB
+ * @returns Object with all field values extracted
+ *
+ * @example
+ * ```typescript
+ * const user = await client.findByID('users', userId);
+ * const plainUser = extractRecord(user);
+ * // { id: '123', email: 'user@example.com', first_name: 'John', ... }
+ * ```
+ */
+function extractRecord(record) {
+    if (!record || typeof record !== "object") {
+        return record;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === "id") {
+            result[key] = value;
+        }
+        else {
+            result[key] = getValue(value);
+        }
+    }
+    return result;
+}
+/**
+ * Field builders for creating wrapped type values to send to ekoDB.
+ * These are the inverse of the getValue* extraction functions.
+ */
+exports.Field = {
+    /**
+     * Create a UUID field value
+     * @param value - UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+     */
+    uuid: (value) => ({
+        type: "UUID",
+        value,
+    }),
+    /**
+     * Create a Decimal field value for precise numeric values
+     * @param value - Decimal as string (e.g., "99.99") to preserve precision
+     */
+    decimal: (value) => ({
+        type: "Decimal",
+        value,
+    }),
+    /**
+     * Create a DateTime field value
+     * @param value - Date object or RFC3339 string
+     */
+    dateTime: (value) => ({
+        type: "DateTime",
+        value: value instanceof Date ? value.toISOString() : value,
+    }),
+    /**
+     * Create a Duration field value
+     * @param milliseconds - Duration in milliseconds
+     */
+    duration: (milliseconds) => ({
+        type: "Duration",
+        value: milliseconds,
+    }),
+    /**
+     * Create a Number field value (flexible numeric type)
+     * @param value - Integer or float
+     */
+    number: (value) => ({
+        type: "Number",
+        value,
+    }),
+    /**
+     * Create a Set field value (unique elements)
+     * @param values - Array of values (duplicates will be removed by server)
+     */
+    set: (values) => ({
+        type: "Set",
+        value: values,
+    }),
+    /**
+     * Create a Vector field value (for embeddings/similarity search)
+     * @param values - Array of numbers representing the vector
+     */
+    vector: (values) => ({
+        type: "Vector",
+        value: values,
+    }),
+    /**
+     * Create a Binary field value
+     * @param value - Base64 encoded string or Uint8Array
+     */
+    binary: (value) => ({
+        type: "Binary",
+        value: value instanceof Uint8Array ? btoa(String.fromCharCode(...value)) : value,
+    }),
+    /**
+     * Create a Bytes field value
+     * @param value - Base64 encoded string or Uint8Array
+     */
+    bytes: (value) => ({
+        type: "Bytes",
+        value: value instanceof Uint8Array ? btoa(String.fromCharCode(...value)) : value,
+    }),
+    /**
+     * Create an Array field value
+     * @param values - Array of values
+     */
+    array: (values) => ({
+        type: "Array",
+        value: values,
+    }),
+    /**
+     * Create an Object field value
+     * @param value - Object/map of key-value pairs
+     */
+    object: (value) => ({
+        type: "Object",
+        value,
+    }),
+    /**
+     * Create a String field value (explicit wrapping)
+     * @param value - String value
+     */
+    string: (value) => ({
+        type: "String",
+        value,
+    }),
+    /**
+     * Create an Integer field value (explicit wrapping)
+     * @param value - Integer value
+     */
+    integer: (value) => ({
+        type: "Integer",
+        value: Math.floor(value),
+    }),
+    /**
+     * Create a Float field value (explicit wrapping)
+     * @param value - Float value
+     */
+    float: (value) => ({
+        type: "Float",
+        value,
+    }),
+    /**
+     * Create a Boolean field value (explicit wrapping)
+     * @param value - Boolean value
+     */
+    boolean: (value) => ({
+        type: "Boolean",
+        value,
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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);
   }
@@ -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

@@ -15,6 +15,23 @@ export {
 } from "./schema";
 export { JoinBuilder } from "./join";
 export { Stage, ChatMessage } from "./functions";
+export {
+  getValue,
+  getValues,
+  extractRecord,
+  getDateTimeValue,
+  getUUIDValue,
+  getDecimalValue,
+  getDurationValue,
+  getBytesValue,
+  getBinaryValue,
+  getArrayValue,
+  getSetValue,
+  getVectorValue,
+  getObjectValue,
+  Field,
+} from "./utils";
+export type { WrappedFieldValue } from "./utils";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type {
   Schema,