@ekodb/ekodb-client 0.6.1 → 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,7 +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, } from "./utils";
+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.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;
+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; } });
@@ -36,3 +36,4 @@ Object.defineProperty(exports, "getArrayValue", { enumerable: true, get: functio
 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

@@ -87,3 +87,88 @@ export declare function getObjectValue<T = any>(field: any): T | null;
  * ```
  */
 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;
+};

package/dist/utils.js

@@ -3,6 +3,7 @@
  * 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;
@@ -196,3 +197,129 @@ function extractRecord(record) {
     }
     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.1",
+  "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

@@ -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,

package/src/utils.ts

@@ -191,3 +191,165 @@ export function extractRecord<T extends Record<string, any>>(record: any): T {
   }
   return result as T;
 }
+
+// ============================================================================
+// Wrapped Type Builders
+// ============================================================================
+// These functions create wrapped type objects for sending to ekoDB.
+// Use these when inserting/updating records with special field types.
+//
+// Example:
+//   await client.insert("orders", {
+//     id: Field.uuid("550e8400-e29b-41d4-a716-446655440000"),
+//     total: Field.decimal("99.99"),
+//     created_at: Field.dateTime(new Date()),
+//     tags: Field.set(["sale", "featured"]),
+//   });
+
+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 const Field = {
+  /**
+   * Create a UUID field value
+   * @param value - UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+   */
+  uuid: (value: string): WrappedFieldValue => ({
+    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: string): WrappedFieldValue => ({
+    type: "Decimal",
+    value,
+  }),
+
+  /**
+   * Create a DateTime field value
+   * @param value - Date object or RFC3339 string
+   */
+  dateTime: (value: Date | string): WrappedFieldValue => ({
+    type: "DateTime",
+    value: value instanceof Date ? value.toISOString() : value,
+  }),
+
+  /**
+   * Create a Duration field value
+   * @param milliseconds - Duration in milliseconds
+   */
+  duration: (milliseconds: number): WrappedFieldValue => ({
+    type: "Duration",
+    value: milliseconds,
+  }),
+
+  /**
+   * Create a Number field value (flexible numeric type)
+   * @param value - Integer or float
+   */
+  number: (value: number): WrappedFieldValue => ({
+    type: "Number",
+    value,
+  }),
+
+  /**
+   * Create a Set field value (unique elements)
+   * @param values - Array of values (duplicates will be removed by server)
+   */
+  set: <T>(values: T[]): WrappedFieldValue => ({
+    type: "Set",
+    value: values,
+  }),
+
+  /**
+   * Create a Vector field value (for embeddings/similarity search)
+   * @param values - Array of numbers representing the vector
+   */
+  vector: (values: number[]): WrappedFieldValue => ({
+    type: "Vector",
+    value: values,
+  }),
+
+  /**
+   * Create a Binary field value
+   * @param value - Base64 encoded string or Uint8Array
+   */
+  binary: (value: string | Uint8Array): WrappedFieldValue => ({
+    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: string | Uint8Array): WrappedFieldValue => ({
+    type: "Bytes",
+    value:
+      value instanceof Uint8Array ? btoa(String.fromCharCode(...value)) : value,
+  }),
+
+  /**
+   * Create an Array field value
+   * @param values - Array of values
+   */
+  array: <T>(values: T[]): WrappedFieldValue => ({
+    type: "Array",
+    value: values,
+  }),
+
+  /**
+   * Create an Object field value
+   * @param value - Object/map of key-value pairs
+   */
+  object: (value: Record<string, unknown>): WrappedFieldValue => ({
+    type: "Object",
+    value,
+  }),
+
+  /**
+   * Create a String field value (explicit wrapping)
+   * @param value - String value
+   */
+  string: (value: string): WrappedFieldValue => ({
+    type: "String",
+    value,
+  }),
+
+  /**
+   * Create an Integer field value (explicit wrapping)
+   * @param value - Integer value
+   */
+  integer: (value: number): WrappedFieldValue => ({
+    type: "Integer",
+    value: Math.floor(value),
+  }),
+
+  /**
+   * Create a Float field value (explicit wrapping)
+   * @param value - Float value
+   */
+  float: (value: number): WrappedFieldValue => ({
+    type: "Float",
+    value,
+  }),
+
+  /**
+   * Create a Boolean field value (explicit wrapping)
+   * @param value - Boolean value
+   */
+  boolean: (value: boolean): WrappedFieldValue => ({
+    type: "Boolean",
+    value,
+  }),
+};