@ekodb/ekodb-client 0.5.0 → 0.6.1

package/dist/functions.d.ts

@@ -5,12 +5,12 @@ export interface Script {
     label: string;
     name: string;
     description?: string;
-    version: string;
+    version?: string;
     parameters: {
         [key: string]: ParameterDefinition;
     };
     functions: FunctionStageConfig[];
-    tags: string[];
+    tags?: string[];
     created_at?: string;
     updated_at?: string;
 }
@@ -129,6 +129,51 @@ export type FunctionStageConfig = {
     input_field: string;
     output_field: string;
     model?: string;
+} | {
+    type: "FindById";
+    collection: string;
+    record_id: string;
+} | {
+    type: "FindOne";
+    collection: string;
+    key: string;
+    value: any;
+} | {
+    type: "If";
+    condition: ScriptCondition;
+    then_functions: FunctionStageConfig[];
+    else_functions?: FunctionStageConfig[];
+} | {
+    type: "ForEach";
+    functions: FunctionStageConfig[];
+} | {
+    type: "CallFunction";
+    function_label: string;
+    params?: Record<string, any>;
+} | {
+    type: "FindOneAndUpdate";
+    collection: string;
+    record_id: string;
+    updates: Record<string, any>;
+    bypass_ripple?: boolean;
+    ttl?: number;
+} | {
+    type: "UpdateWithAction";
+    collection: string;
+    record_id: string;
+    action: string;
+    field: string;
+    value: any;
+    bypass_ripple?: boolean;
+} | {
+    type: "CreateSavepoint";
+    name: string;
+} | {
+    type: "RollbackToSavepoint";
+    name: string;
+} | {
+    type: "ReleaseSavepoint";
+    name: string;
 };
 export interface ChatMessage {
     role: string;
@@ -148,6 +193,34 @@ export interface SortFieldConfig {
     field: string;
     ascending: boolean;
 }
+export type ScriptCondition = {
+    type: "FieldEquals";
+    field: string;
+    value: any;
+} | {
+    type: "FieldExists";
+    field: string;
+} | {
+    type: "HasRecords";
+} | {
+    type: "CountEquals";
+    count: number;
+} | {
+    type: "CountGreaterThan";
+    count: number;
+} | {
+    type: "CountLessThan";
+    count: number;
+} | {
+    type: "And";
+    conditions: ScriptCondition[];
+} | {
+    type: "Or";
+    conditions: ScriptCondition[];
+} | {
+    type: "Not";
+    condition: ScriptCondition;
+};
 export interface FunctionResult {
     records: Record<string, any>[];
     stats: FunctionStats;
@@ -192,4 +265,14 @@ export declare const Stage: {
     hybridSearch: (collection: string, query_text: string, query_vector?: number[], limit?: number) => FunctionStageConfig;
     chat: (messages: ChatMessage[], model?: string, temperature?: number, max_tokens?: number) => FunctionStageConfig;
     embed: (input_field: string, output_field: string, model?: string) => FunctionStageConfig;
+    findById: (collection: string, record_id: string) => FunctionStageConfig;
+    findOne: (collection: string, key: string, value: any) => FunctionStageConfig;
+    if: (condition: ScriptCondition, thenFunctions: FunctionStageConfig[], elseFunctions?: FunctionStageConfig[]) => FunctionStageConfig;
+    forEach: (functions: FunctionStageConfig[]) => FunctionStageConfig;
+    callFunction: (function_label: string, params?: Record<string, any>) => FunctionStageConfig;
+    findOneAndUpdate: (collection: string, record_id: string, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    updateWithAction: (collection: string, record_id: string, action: string, field: string, value: any, bypassRipple?: boolean) => FunctionStageConfig;
+    createSavepoint: (name: string) => FunctionStageConfig;
+    rollbackToSavepoint: (name: string) => FunctionStageConfig;
+    releaseSavepoint: (name: string) => FunctionStageConfig;
 };

package/dist/functions.js

@@ -151,4 +151,59 @@ exports.Stage = {
         output_field,
         model,
     }),
+    findById: (collection, record_id) => ({
+        type: "FindById",
+        collection,
+        record_id,
+    }),
+    findOne: (collection, key, value) => ({
+        type: "FindOne",
+        collection,
+        key,
+        value,
+    }),
+    if: (condition, thenFunctions, elseFunctions) => ({
+        type: "If",
+        condition,
+        then_functions: thenFunctions,
+        else_functions: elseFunctions,
+    }),
+    forEach: (functions) => ({
+        type: "ForEach",
+        functions,
+    }),
+    callFunction: (function_label, params) => ({
+        type: "CallFunction",
+        function_label,
+        params,
+    }),
+    findOneAndUpdate: (collection, record_id, updates, bypassRipple = false, ttl) => ({
+        type: "FindOneAndUpdate",
+        collection,
+        record_id,
+        updates,
+        bypass_ripple: bypassRipple,
+        ttl,
+    }),
+    updateWithAction: (collection, record_id, action, field, value, bypassRipple = false) => ({
+        type: "UpdateWithAction",
+        collection,
+        record_id,
+        action,
+        field,
+        value,
+        bypass_ripple: bypassRipple,
+    }),
+    createSavepoint: (name) => ({
+        type: "CreateSavepoint",
+        name,
+    }),
+    rollbackToSavepoint: (name) => ({
+        type: "RollbackToSavepoint",
+        name,
+    }),
+    releaseSavepoint: (name) => ({
+        type: "ReleaseSavepoint",
+        name,
+    }),
 };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ 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 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.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,17 @@ 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; } });

package/dist/utils.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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;

package/dist/utils.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Utility functions for working with ekoDB records
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+}

package/package.json

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

package/src/functions.ts

@@ -6,10 +6,10 @@ export interface Script {
   label: string;
   name: string;
   description?: string;
-  version: string;
+  version?: string;
   parameters: { [key: string]: ParameterDefinition };
   functions: FunctionStageConfig[];
-  tags: string[];
+  tags?: string[];
   created_at?: string;
   updated_at?: string;
 }
@@ -132,6 +132,61 @@ export type FunctionStageConfig =
       input_field: string;
       output_field: string;
       model?: string;
+    }
+  | {
+      type: "FindById";
+      collection: string;
+      record_id: string;
+    }
+  | {
+      type: "FindOne";
+      collection: string;
+      key: string;
+      value: any;
+    }
+  | {
+      type: "If";
+      condition: ScriptCondition;
+      then_functions: FunctionStageConfig[];
+      else_functions?: FunctionStageConfig[];
+    }
+  | {
+      type: "ForEach";
+      functions: FunctionStageConfig[];
+    }
+  | {
+      type: "CallFunction";
+      function_label: string;
+      params?: Record<string, any>;
+    }
+  | {
+      type: "FindOneAndUpdate";
+      collection: string;
+      record_id: string;
+      updates: Record<string, any>;
+      bypass_ripple?: boolean;
+      ttl?: number;
+    }
+  | {
+      type: "UpdateWithAction";
+      collection: string;
+      record_id: string;
+      action: string;
+      field: string;
+      value: any;
+      bypass_ripple?: boolean;
+    }
+  | {
+      type: "CreateSavepoint";
+      name: string;
+    }
+  | {
+      type: "RollbackToSavepoint";
+      name: string;
+    }
+  | {
+      type: "ReleaseSavepoint";
+      name: string;
     };
 
 export interface ChatMessage {
@@ -173,6 +228,17 @@ export interface SortFieldConfig {
   ascending: boolean;
 }
 
+export type ScriptCondition =
+  | { type: "FieldEquals"; field: string; value: any }
+  | { type: "FieldExists"; field: string }
+  | { type: "HasRecords" }
+  | { type: "CountEquals"; count: number }
+  | { type: "CountGreaterThan"; count: number }
+  | { type: "CountLessThan"; count: number }
+  | { type: "And"; conditions: ScriptCondition[] }
+  | { type: "Or"; conditions: ScriptCondition[] }
+  | { type: "Not"; condition: ScriptCondition };
+
 export interface FunctionResult {
   records: Record<string, any>[];
   stats: FunctionStats;
@@ -417,4 +483,93 @@ export const Stage = {
     output_field,
     model,
   }),
+
+  findById: (collection: string, record_id: string): FunctionStageConfig => ({
+    type: "FindById",
+    collection,
+    record_id,
+  }),
+
+  findOne: (
+    collection: string,
+    key: string,
+    value: any,
+  ): FunctionStageConfig => ({
+    type: "FindOne",
+    collection,
+    key,
+    value,
+  }),
+
+  if: (
+    condition: ScriptCondition,
+    thenFunctions: FunctionStageConfig[],
+    elseFunctions?: FunctionStageConfig[],
+  ): FunctionStageConfig => ({
+    type: "If",
+    condition,
+    then_functions: thenFunctions,
+    else_functions: elseFunctions,
+  }),
+
+  forEach: (functions: FunctionStageConfig[]): FunctionStageConfig => ({
+    type: "ForEach",
+    functions,
+  }),
+
+  callFunction: (
+    function_label: string,
+    params?: Record<string, any>,
+  ): FunctionStageConfig => ({
+    type: "CallFunction",
+    function_label,
+    params,
+  }),
+
+  findOneAndUpdate: (
+    collection: string,
+    record_id: string,
+    updates: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "FindOneAndUpdate",
+    collection,
+    record_id,
+    updates,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  updateWithAction: (
+    collection: string,
+    record_id: string,
+    action: string,
+    field: string,
+    value: any,
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "UpdateWithAction",
+    collection,
+    record_id,
+    action,
+    field,
+    value,
+    bypass_ripple: bypassRipple,
+  }),
+
+  createSavepoint: (name: string): FunctionStageConfig => ({
+    type: "CreateSavepoint",
+    name,
+  }),
+
+  rollbackToSavepoint: (name: string): FunctionStageConfig => ({
+    type: "RollbackToSavepoint",
+    name,
+  }),
+
+  releaseSavepoint: (name: string): FunctionStageConfig => ({
+    type: "ReleaseSavepoint",
+    name,
+  }),
 };

package/src/index.ts

@@ -15,6 +15,21 @@ 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,
+} from "./utils";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type {
   Schema,

package/src/utils.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 function getValue<T = any>(field: any): T {
+  if (field && typeof field === "object" && "value" in field) {
+    return field.value as T;
+  }
+  return field as 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 function getValues<T extends Record<string, any>>(
+  record: any,
+  fields: (keyof T)[],
+): Partial<T> {
+  const result: any = {};
+  for (const field of fields) {
+    result[field] = getValue(record[field]);
+  }
+  return result;
+}
+
+/**
+ * Extract a Date value from an ekoDB DateTime field
+ */
+export function getDateTimeValue(field: any): Date | null {
+  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
+ */
+export function getUUIDValue(field: any): string | null {
+  const val = getValue(field);
+  return typeof val === "string" ? val : null;
+}
+
+/**
+ * Extract a number from an ekoDB Decimal field
+ */
+export function getDecimalValue(field: any): number | null {
+  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
+ */
+export function getDurationValue(field: any): number | null {
+  const val = getValue(field);
+  if (typeof val === "number") return val;
+  if (typeof val === "object" && val.secs !== undefined) {
+    return val.secs * 1000 + val.nanos / 1_000_000;
+  }
+  return null;
+}
+
+/**
+ * Extract a Uint8Array from an ekoDB Bytes field
+ */
+export function getBytesValue(field: any): Uint8Array | null {
+  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
+ */
+export function getBinaryValue(field: any): Uint8Array | null {
+  return getBytesValue(field);
+}
+
+/**
+ * Extract an array from an ekoDB Array field
+ */
+export function getArrayValue<T = any>(field: any): T[] | null {
+  const val = getValue(field);
+  return Array.isArray(val) ? val : null;
+}
+
+/**
+ * Extract an array from an ekoDB Set field
+ */
+export function getSetValue<T = any>(field: any): T[] | null {
+  const val = getValue(field);
+  return Array.isArray(val) ? val : null;
+}
+
+/**
+ * Extract an array from an ekoDB Vector field
+ */
+export function getVectorValue(field: any): number[] | null {
+  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
+ */
+export function getObjectValue<T = any>(field: any): T | null {
+  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', ... }
+ * ```
+ */
+export function extractRecord<T extends Record<string, any>>(record: any): T {
+  if (!record || typeof record !== "object") {
+    return record;
+  }
+
+  const result: any = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "id") {
+      result[key] = value;
+    } else {
+      result[key] = getValue(value);
+    }
+  }
+  return result as T;
+}