@ekodb/ekodb-client 0.6.0 → 0.7.0

package/dist/client.d.ts

@@ -206,6 +206,9 @@ export declare class EkoDBClient {
     private makeRequest;
     /**
      * 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
      */
     insert(collection: string, record: Record, ttl?: string): Promise<Record>;
     /**
@@ -260,9 +263,12 @@ export declare class EkoDBClient {
      */
     batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<BatchOperationResult>;
     /**
-     * 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
      */
-    kvSet(key: string, value: any): Promise<void>;
+    kvSet(key: string, value: any, ttl?: number): Promise<void>;
     /**
      * Get a value by key
      */
@@ -271,6 +277,53 @@ export declare class EkoDBClient {
      * Delete a key
      */
     kvDelete(key: string): Promise<void>;
+    /**
+     * Check if a key exists
+     * @param key - The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    kvExists(key: string): Promise<boolean>;
+    /**
+     * Query/find KV entries with pattern matching
+     * @param options - Query options including pattern and include_expired
+     * @returns Array of matching records
+     */
+    kvFind(options?: {
+        pattern?: string;
+        include_expired?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Alias for kvFind - query KV store with pattern
+     */
+    kvQuery(options?: {
+        pattern?: string;
+        include_expired?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Begin a new transaction
+     * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
+     * @returns Transaction ID
+     */
+    beginTransaction(isolationLevel?: string): Promise<string>;
+    /**
+     * Get transaction status
+     * @param transactionId - The transaction ID
+     * @returns Transaction status object
+     */
+    getTransactionStatus(transactionId: string): Promise<{
+        state: string;
+        operations_count: number;
+    }>;
+    /**
+     * Commit a transaction
+     * @param transactionId - The transaction ID to commit
+     */
+    commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * Rollback a transaction
+     * @param transactionId - The transaction ID to rollback
+     */
+    rollbackTransaction(transactionId: string): Promise<void>;
     /**
      * List all collections
      */

package/dist/client.js

@@ -263,11 +263,14 @@ 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, record, ttl) {
         const data = { ...record };
         if (ttl) {
-            data.ttl_duration = ttl;
+            data.ttl = ttl;
         }
         return this.makeRequest("POST", `/api/insert/${collection}`, data);
     }
@@ -347,10 +350,17 @@ class EkoDBClient {
         return this.makeRequest("DELETE", `/api/batch/delete/${collection}`, { deletes });
     }
     /**
-     * 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, value) {
-        await this.makeRequest("POST", `/api/kv/set/${encodeURIComponent(key)}`, { value }, 0, true);
+    async kvSet(key, value, ttl) {
+        const body = { value };
+        if (ttl !== undefined) {
+            body.ttl = ttl;
+        }
+        await this.makeRequest("POST", `/api/kv/set/${encodeURIComponent(key)}`, body, 0, true);
     }
     /**
      * Get a value by key
@@ -365,6 +375,69 @@ class EkoDBClient {
     async kvDelete(key) {
         await this.makeRequest("DELETE", `/api/kv/delete/${encodeURIComponent(key)}`, undefined, 0, true);
     }
+    /**
+     * Check if a key exists
+     * @param key - The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    async kvExists(key) {
+        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) {
+        const result = await this.makeRequest("POST", "/api/kv/find", options || {}, 0, true);
+        return result;
+    }
+    /**
+     * Alias for kvFind - query KV store with pattern
+     */
+    async kvQuery(options) {
+        return this.kvFind(options);
+    }
+    // ============================================================================
+    // Transaction Operations
+    // ============================================================================
+    /**
+     * Begin a new transaction
+     * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
+     * @returns Transaction ID
+     */
+    async beginTransaction(isolationLevel = "ReadCommitted") {
+        const result = await this.makeRequest("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) {
+        return this.makeRequest("GET", `/api/transactions/${encodeURIComponent(transactionId)}`, undefined, 0, true);
+    }
+    /**
+     * Commit a transaction
+     * @param transactionId - The transaction ID to commit
+     */
+    async commitTransaction(transactionId) {
+        await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/commit`, undefined, 0, true);
+    }
+    /**
+     * Rollback a transaction
+     * @param transactionId - The transaction ID to rollback
+     */
+    async rollbackTransaction(transactionId) {
+        await this.makeRequest("POST", `/api/transactions/${encodeURIComponent(transactionId)}/rollback`, undefined, 0, true);
+    }
     /**
      * List all collections
      */

package/dist/functions.d.ts

@@ -174,6 +174,26 @@ 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 {
     role: string;
@@ -275,4 +295,9 @@ export declare const Stage: {
     createSavepoint: (name: string) => FunctionStageConfig;
     rollbackToSavepoint: (name: string) => FunctionStageConfig;
     releaseSavepoint: (name: string) => FunctionStageConfig;
+    kvGet: (key: string, output_field?: string) => FunctionStageConfig;
+    kvSet: (key: string, value: any, ttl?: number) => FunctionStageConfig;
+    kvDelete: (key: string) => FunctionStageConfig;
+    kvExists: (key: string, output_field?: string) => FunctionStageConfig;
+    kvQuery: (pattern?: string, include_expired?: boolean) => FunctionStageConfig;
 };

package/dist/functions.js

@@ -206,4 +206,30 @@ exports.Stage = {
         type: "ReleaseSavepoint",
         name,
     }),
+    // KV Store operations - faster than collection lookups for simple key-value data
+    kvGet: (key, output_field) => ({
+        type: "KvGet",
+        key,
+        output_field,
+    }),
+    kvSet: (key, value, ttl) => ({
+        type: "KvSet",
+        key,
+        value,
+        ttl,
+    }),
+    kvDelete: (key) => ({
+        type: "KvDelete",
+        key,
+    }),
+    kvExists: (key, output_field) => ({
+        type: "KvExists",
+        key,
+        output_field,
+    }),
+    kvQuery: (pattern, include_expired) => ({
+        type: "KvQuery",
+        pattern,
+        include_expired,
+    }),
 };

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } 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, FieldTypeSchema, IndexConfig, CollectionMetadata, } from "./schema";
 export type { JoinConfig } from "./join";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -22,3 +22,18 @@ Object.defineProperty(exports, "JoinBuilder", { enumerable: true, get: function
 var functions_1 = require("./functions");
 Object.defineProperty(exports, "Stage", { enumerable: true, get: function () { return functions_1.Stage; } });
 Object.defineProperty(exports, "ChatMessage", { enumerable: true, get: function () { return functions_1.ChatMessage; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "getValue", { enumerable: true, get: function () { return utils_1.getValue; } });
+Object.defineProperty(exports, "getValues", { enumerable: true, get: function () { return utils_1.getValues; } });
+Object.defineProperty(exports, "extractRecord", { enumerable: true, get: function () { return utils_1.extractRecord; } });
+Object.defineProperty(exports, "getDateTimeValue", { enumerable: true, get: function () { return utils_1.getDateTimeValue; } });
+Object.defineProperty(exports, "getUUIDValue", { enumerable: true, get: function () { return utils_1.getUUIDValue; } });
+Object.defineProperty(exports, "getDecimalValue", { enumerable: true, get: function () { return utils_1.getDecimalValue; } });
+Object.defineProperty(exports, "getDurationValue", { enumerable: true, get: function () { return utils_1.getDurationValue; } });
+Object.defineProperty(exports, "getBytesValue", { enumerable: true, get: function () { return utils_1.getBytesValue; } });
+Object.defineProperty(exports, "getBinaryValue", { enumerable: true, get: function () { return utils_1.getBinaryValue; } });
+Object.defineProperty(exports, "getArrayValue", { enumerable: true, get: function () { return utils_1.getArrayValue; } });
+Object.defineProperty(exports, "getSetValue", { enumerable: true, get: function () { return utils_1.getSetValue; } });
+Object.defineProperty(exports, "getVectorValue", { enumerable: true, get: function () { return utils_1.getVectorValue; } });
+Object.defineProperty(exports, "getObjectValue", { enumerable: true, get: function () { return utils_1.getObjectValue; } });
+Object.defineProperty(exports, "Field", { enumerable: true, get: function () { return utils_1.Field; } });

package/dist/utils.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Utility functions for working with ekoDB records
+ */
+/**
+ * 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 }
+ * ```
+ */
+export declare function getValue<T = any>(field: any): T;
+/**
+ * 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']);
+ * ```
+ */
+export declare function getValues<T extends Record<string, any>>(record: any, fields: (keyof T)[]): Partial<T>;
+/**
+ * Extract a Date value from an ekoDB DateTime field
+ */
+export declare function getDateTimeValue(field: any): Date | null;
+/**
+ * Extract a UUID string from an ekoDB UUID field
+ */
+export declare function getUUIDValue(field: any): string | null;
+/**
+ * Extract a number from an ekoDB Decimal field
+ */
+export declare function getDecimalValue(field: any): number | null;
+/**
+ * Extract a number (milliseconds) from an ekoDB Duration field
+ */
+export declare function getDurationValue(field: any): number | null;
+/**
+ * Extract a Uint8Array from an ekoDB Bytes field
+ */
+export declare function getBytesValue(field: any): Uint8Array | null;
+/**
+ * Extract a Uint8Array from an ekoDB Binary field
+ */
+export declare function getBinaryValue(field: any): Uint8Array | null;
+/**
+ * Extract an array from an ekoDB Array field
+ */
+export declare function getArrayValue<T = any>(field: any): T[] | null;
+/**
+ * Extract an array from an ekoDB Set field
+ */
+export declare function getSetValue<T = any>(field: any): T[] | null;
+/**
+ * Extract an array from an ekoDB Vector field
+ */
+export declare function getVectorValue(field: any): number[] | null;
+/**
+ * Extract an object from an ekoDB Object field
+ */
+export declare function getObjectValue<T = any>(field: any): T | 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', ... }
+ * ```
+ */
+export declare function extractRecord<T extends Record<string, any>>(record: any): T;
+export interface WrappedFieldValue {
+    type: string;
+    value: unknown;
+}
+/**
+ * Field builders for creating wrapped type values to send to ekoDB.
+ * These are the inverse of the getValue* extraction functions.
+ */
+export declare const Field: {
+    /**
+     * Create a UUID field value
+     * @param value - UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+     */
+    uuid: (value: string) => WrappedFieldValue;
+    /**
+     * Create a Decimal field value for precise numeric values
+     * @param value - Decimal as string (e.g., "99.99") to preserve precision
+     */
+    decimal: (value: string) => WrappedFieldValue;
+    /**
+     * Create a DateTime field value
+     * @param value - Date object or RFC3339 string
+     */
+    dateTime: (value: Date | string) => WrappedFieldValue;
+    /**
+     * Create a Duration field value
+     * @param milliseconds - Duration in milliseconds
+     */
+    duration: (milliseconds: number) => WrappedFieldValue;
+    /**
+     * Create a Number field value (flexible numeric type)
+     * @param value - Integer or float
+     */
+    number: (value: number) => WrappedFieldValue;
+    /**
+     * Create a Set field value (unique elements)
+     * @param values - Array of values (duplicates will be removed by server)
+     */
+    set: <T>(values: T[]) => WrappedFieldValue;
+    /**
+     * Create a Vector field value (for embeddings/similarity search)
+     * @param values - Array of numbers representing the vector
+     */
+    vector: (values: number[]) => WrappedFieldValue;
+    /**
+     * Create a Binary field value
+     * @param value - Base64 encoded string or Uint8Array
+     */
+    binary: (value: string | Uint8Array) => WrappedFieldValue;
+    /**
+     * Create a Bytes field value
+     * @param value - Base64 encoded string or Uint8Array
+     */
+    bytes: (value: string | Uint8Array) => WrappedFieldValue;
+    /**
+     * Create an Array field value
+     * @param values - Array of values
+     */
+    array: <T>(values: T[]) => WrappedFieldValue;
+    /**
+     * Create an Object field value
+     * @param value - Object/map of key-value pairs
+     */
+    object: (value: Record<string, unknown>) => WrappedFieldValue;
+    /**
+     * Create a String field value (explicit wrapping)
+     * @param value - String value
+     */
+    string: (value: string) => WrappedFieldValue;
+    /**
+     * Create an Integer field value (explicit wrapping)
+     * @param value - Integer value
+     */
+    integer: (value: number) => WrappedFieldValue;
+    /**
+     * Create a Float field value (explicit wrapping)
+     * @param value - Float value
+     */
+    float: (value: number) => WrappedFieldValue;
+    /**
+     * Create a Boolean field value (explicit wrapping)
+     * @param value - Boolean value
+     */
+    boolean: (value: boolean) => WrappedFieldValue;
+};