@ekodb/ekodb-client 0.6.1 → 0.7.1

package/dist/utils.d.ts

@@ -11,7 +11,7 @@
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * 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 }
  * ```
@@ -27,7 +27,7 @@ export declare function getValue<T = any>(field: any): T;
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * const user = await client.findById('users', userId);
  * const { email, first_name, status } = getValues(user, ['email', 'first_name', 'status']);
  * ```
  */
@@ -81,9 +81,94 @@ export declare function getObjectValue<T = any>(field: any): T | null;
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * 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;
+};

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;
@@ -26,7 +27,7 @@ exports.extractRecord = extractRecord;
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * 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 }
  * ```
@@ -47,7 +48,7 @@ function getValue(field) {
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * const user = await client.findById('users', userId);
  * const { email, first_name, status } = getValues(user, ['email', 'first_name', 'status']);
  * ```
  */
@@ -176,7 +177,7 @@ function getObjectValue(field) {
  *
  * @example
  * ```typescript
- * const user = await client.findByID('users', userId);
+ * const user = await client.findById('users', userId);
  * const plainUser = extractRecord(user);
  * // { id: '123', email: 'user@example.com', first_name: 'John', ... }
  * ```
@@ -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/dist/utils.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unit tests for ekoDB TypeScript client utility functions
+ */
+export {};