@ekodb/ekodb-client 0.6.0 → 0.6.1

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.6.0",
+  "version": "0.6.1",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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;
+}