@ekodb/ekodb-client 0.7.0 → 0.8.0

package/dist/query-builder.test.d.ts

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

package/dist/query-builder.test.js

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * Unit tests for ekoDB TypeScript client QueryBuilder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const query_builder_1 = require("./query-builder");
+// ============================================================================
+// Basic Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder basics", () => {
+    (0, vitest_1.it)("creates empty query builder", () => {
+        const qb = new query_builder_1.QueryBuilder();
+        (0, vitest_1.expect)(qb).toBeInstanceOf(query_builder_1.QueryBuilder);
+    });
+    (0, vitest_1.it)("builds empty query", () => {
+        const query = new query_builder_1.QueryBuilder().build();
+        (0, vitest_1.expect)(query).toEqual({});
+    });
+});
+// ============================================================================
+// Equality Operators Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder equality operators", () => {
+    (0, vitest_1.it)("builds eq filter", () => {
+        const query = new query_builder_1.QueryBuilder().eq("status", "active").build();
+        (0, vitest_1.expect)(query.filter).toEqual({
+            type: "Condition",
+            content: {
+                field: "status",
+                operator: "Eq",
+                value: "active",
+            },
+        });
+    });
+    (0, vitest_1.it)("builds ne filter", () => {
+        const query = new query_builder_1.QueryBuilder().ne("status", "deleted").build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Ne");
+    });
+});
+// ============================================================================
+// Comparison Operators Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder comparison operators", () => {
+    (0, vitest_1.it)("builds gt filter", () => {
+        const query = new query_builder_1.QueryBuilder().gt("age", 18).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Gt");
+        (0, vitest_1.expect)(query.filter.content.value).toBe(18);
+    });
+    (0, vitest_1.it)("builds gte filter", () => {
+        const query = new query_builder_1.QueryBuilder().gte("score", 80).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Gte");
+    });
+    (0, vitest_1.it)("builds lt filter", () => {
+        const query = new query_builder_1.QueryBuilder().lt("price", 100.5).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Lt");
+    });
+    (0, vitest_1.it)("builds lte filter", () => {
+        const query = new query_builder_1.QueryBuilder().lte("count", 1000).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Lte");
+    });
+});
+// ============================================================================
+// Array Operators Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder array operators", () => {
+    (0, vitest_1.it)("builds in filter", () => {
+        const query = new query_builder_1.QueryBuilder()
+            .in("status", ["active", "pending"])
+            .build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("In");
+        (0, vitest_1.expect)(query.filter.content.value).toEqual(["active", "pending"]);
+    });
+    (0, vitest_1.it)("builds nin filter", () => {
+        const query = new query_builder_1.QueryBuilder()
+            .nin("role", ["blocked", "deleted"])
+            .build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("NotIn");
+    });
+});
+// ============================================================================
+// String Operators Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder string operators", () => {
+    (0, vitest_1.it)("builds contains filter", () => {
+        const query = new query_builder_1.QueryBuilder().contains("email", "@example.com").build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Contains");
+        (0, vitest_1.expect)(query.filter.content.value).toBe("@example.com");
+    });
+    (0, vitest_1.it)("builds startsWith filter", () => {
+        const query = new query_builder_1.QueryBuilder().startsWith("name", "John").build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("StartsWith");
+    });
+    (0, vitest_1.it)("builds endsWith filter", () => {
+        const query = new query_builder_1.QueryBuilder().endsWith("filename", ".pdf").build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("EndsWith");
+    });
+    (0, vitest_1.it)("builds regex filter", () => {
+        const query = new query_builder_1.QueryBuilder().regex("phone", "^\\+1").build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Regex");
+    });
+});
+// ============================================================================
+// Logical Operators Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder logical operators", () => {
+    (0, vitest_1.it)("builds and filter", () => {
+        const conditions = [
+            {
+                type: "Condition",
+                content: { field: "status", operator: "Eq", value: "active" },
+            },
+            {
+                type: "Condition",
+                content: { field: "age", operator: "Gt", value: 18 },
+            },
+        ];
+        const query = new query_builder_1.QueryBuilder().and(conditions).build();
+        (0, vitest_1.expect)(query.filter.type).toBe("Logical");
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("And");
+        (0, vitest_1.expect)(query.filter.content.expressions).toHaveLength(2);
+    });
+    (0, vitest_1.it)("builds or filter", () => {
+        const conditions = [
+            {
+                type: "Condition",
+                content: { field: "role", operator: "Eq", value: "admin" },
+            },
+            {
+                type: "Condition",
+                content: { field: "role", operator: "Eq", value: "super_admin" },
+            },
+        ];
+        const query = new query_builder_1.QueryBuilder().or(conditions).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Or");
+    });
+    (0, vitest_1.it)("builds not filter", () => {
+        const condition = {
+            type: "Condition",
+            content: { field: "deleted", operator: "Eq", value: true },
+        };
+        const query = new query_builder_1.QueryBuilder().not(condition).build();
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("Not");
+    });
+});
+// ============================================================================
+// Multiple Filters (Auto AND) Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder multiple filters", () => {
+    (0, vitest_1.it)("combines multiple filters with AND logic", () => {
+        const query = new query_builder_1.QueryBuilder()
+            .eq("status", "active")
+            .gt("age", 18)
+            .contains("email", "@company.com")
+            .build();
+        (0, vitest_1.expect)(query.filter.type).toBe("Logical");
+        (0, vitest_1.expect)(query.filter.content.operator).toBe("And");
+        (0, vitest_1.expect)(query.filter.content.expressions).toHaveLength(3);
+    });
+});
+// ============================================================================
+// Sorting Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder sorting", () => {
+    (0, vitest_1.it)("builds ascending sort", () => {
+        const query = new query_builder_1.QueryBuilder().sortAsc("name").build();
+        (0, vitest_1.expect)(query.sort).toHaveLength(1);
+        (0, vitest_1.expect)(query.sort[0].field).toBe("name");
+        (0, vitest_1.expect)(query.sort[0].ascending).toBe(true);
+    });
+    (0, vitest_1.it)("builds descending sort", () => {
+        const query = new query_builder_1.QueryBuilder().sortDesc("created_at").build();
+        (0, vitest_1.expect)(query.sort[0].ascending).toBe(false);
+    });
+    (0, vitest_1.it)("builds multiple sorts", () => {
+        const query = new query_builder_1.QueryBuilder()
+            .sortDesc("created_at")
+            .sortAsc("name")
+            .build();
+        (0, vitest_1.expect)(query.sort).toHaveLength(2);
+        (0, vitest_1.expect)(query.sort[0].field).toBe("created_at");
+        (0, vitest_1.expect)(query.sort[0].ascending).toBe(false);
+        (0, vitest_1.expect)(query.sort[1].field).toBe("name");
+        (0, vitest_1.expect)(query.sort[1].ascending).toBe(true);
+    });
+});
+// ============================================================================
+// Pagination Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder pagination", () => {
+    (0, vitest_1.it)("builds limit", () => {
+        const query = new query_builder_1.QueryBuilder().limit(10).build();
+        (0, vitest_1.expect)(query.limit).toBe(10);
+    });
+    (0, vitest_1.it)("builds skip", () => {
+        const query = new query_builder_1.QueryBuilder().skip(20).build();
+        (0, vitest_1.expect)(query.skip).toBe(20);
+    });
+    (0, vitest_1.it)("builds page (convenience method)", () => {
+        // Page 2 with 20 items per page = skip 40
+        const query = new query_builder_1.QueryBuilder().page(2, 20).build();
+        (0, vitest_1.expect)(query.limit).toBe(20);
+        (0, vitest_1.expect)(query.skip).toBe(40);
+    });
+    (0, vitest_1.it)("builds page 0", () => {
+        const query = new query_builder_1.QueryBuilder().page(0, 10).build();
+        (0, vitest_1.expect)(query.skip).toBe(0);
+        (0, vitest_1.expect)(query.limit).toBe(10);
+    });
+});
+// ============================================================================
+// Join Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder join", () => {
+    (0, vitest_1.it)("builds join configuration", () => {
+        const joinConfig = {
+            collections: ["users"],
+            local_field: "user_id",
+            foreign_field: "id",
+            as_field: "user",
+        };
+        const query = new query_builder_1.QueryBuilder().join(joinConfig).build();
+        (0, vitest_1.expect)(query.join).toEqual(joinConfig);
+    });
+});
+// ============================================================================
+// Bypass Flags Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder bypass flags", () => {
+    (0, vitest_1.it)("builds bypass_cache true", () => {
+        const query = new query_builder_1.QueryBuilder().bypassCache(true).build();
+        (0, vitest_1.expect)(query.bypass_cache).toBe(true);
+    });
+    (0, vitest_1.it)("builds bypass_cache false (not included)", () => {
+        const query = new query_builder_1.QueryBuilder().bypassCache(false).build();
+        (0, vitest_1.expect)(query.bypass_cache).toBeUndefined();
+    });
+    (0, vitest_1.it)("builds bypass_cache default (true)", () => {
+        const query = new query_builder_1.QueryBuilder().bypassCache().build();
+        (0, vitest_1.expect)(query.bypass_cache).toBe(true);
+    });
+    (0, vitest_1.it)("builds bypass_ripple", () => {
+        const query = new query_builder_1.QueryBuilder().bypassRipple(true).build();
+        (0, vitest_1.expect)(query.bypass_ripple).toBe(true);
+    });
+});
+// ============================================================================
+// Chaining Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder chaining", () => {
+    (0, vitest_1.it)("supports full method chaining", () => {
+        const query = new query_builder_1.QueryBuilder()
+            .eq("status", "active")
+            .gt("age", 18)
+            .sortDesc("created_at")
+            .sortAsc("name")
+            .limit(10)
+            .skip(20)
+            .bypassCache(true)
+            .build();
+        // Check filter exists
+        (0, vitest_1.expect)(query.filter).toBeDefined();
+        // Check sort exists
+        (0, vitest_1.expect)(query.sort).toHaveLength(2);
+        // Check pagination
+        (0, vitest_1.expect)(query.limit).toBe(10);
+        (0, vitest_1.expect)(query.skip).toBe(20);
+        // Check bypass flag
+        (0, vitest_1.expect)(query.bypass_cache).toBe(true);
+    });
+    (0, vitest_1.it)("returns this for method chaining", () => {
+        const qb = new query_builder_1.QueryBuilder();
+        (0, vitest_1.expect)(qb.eq("a", 1)).toBe(qb);
+        (0, vitest_1.expect)(qb.ne("b", 2)).toBe(qb);
+        (0, vitest_1.expect)(qb.gt("c", 3)).toBe(qb);
+        (0, vitest_1.expect)(qb.gte("d", 4)).toBe(qb);
+        (0, vitest_1.expect)(qb.lt("e", 5)).toBe(qb);
+        (0, vitest_1.expect)(qb.lte("f", 6)).toBe(qb);
+        (0, vitest_1.expect)(qb.in("g", [7])).toBe(qb);
+        (0, vitest_1.expect)(qb.nin("h", [8])).toBe(qb);
+        (0, vitest_1.expect)(qb.contains("i", "j")).toBe(qb);
+        (0, vitest_1.expect)(qb.startsWith("k", "l")).toBe(qb);
+        (0, vitest_1.expect)(qb.endsWith("m", "n")).toBe(qb);
+        (0, vitest_1.expect)(qb.regex("o", "p")).toBe(qb);
+        (0, vitest_1.expect)(qb.sortAsc("q")).toBe(qb);
+        (0, vitest_1.expect)(qb.sortDesc("r")).toBe(qb);
+        (0, vitest_1.expect)(qb.limit(1)).toBe(qb);
+        (0, vitest_1.expect)(qb.skip(0)).toBe(qb);
+        (0, vitest_1.expect)(qb.bypassCache()).toBe(qb);
+        (0, vitest_1.expect)(qb.bypassRipple()).toBe(qb);
+    });
+});
+// ============================================================================
+// Raw Filter Tests
+// ============================================================================
+(0, vitest_1.describe)("QueryBuilder rawFilter", () => {
+    (0, vitest_1.it)("adds raw filter expression", () => {
+        const rawFilter = {
+            type: "Condition",
+            content: {
+                field: "custom",
+                operator: "CustomOp",
+                value: "custom_value",
+            },
+        };
+        const query = new query_builder_1.QueryBuilder().rawFilter(rawFilter).build();
+        (0, vitest_1.expect)(query.filter).toEqual(rawFilter);
+    });
+});
+// ============================================================================
+// SortOrder Enum Tests
+// ============================================================================
+(0, vitest_1.describe)("SortOrder enum", () => {
+    (0, vitest_1.it)("has correct values", () => {
+        (0, vitest_1.expect)(query_builder_1.SortOrder.Asc).toBe("asc");
+        (0, vitest_1.expect)(query_builder_1.SortOrder.Desc).toBe("desc");
+    });
+});

package/dist/search.d.ts

@@ -48,6 +48,10 @@ export interface SearchQuery {
     text_weight?: number;
     /** Weight for vector search (0.0-1.0) */
     vector_weight?: number;
+    /** Only return these fields (plus 'id') */
+    select_fields?: string[];
+    /** Exclude these fields from results */
+    exclude_fields?: string[];
 }
 /**
  * Search result with score and matched fields
@@ -165,6 +169,14 @@ export declare class SearchQueryBuilder {
      * Set maximum number of results to return
      */
     limit(limit: number): this;
+    /**
+     * Select specific fields to return
+     */
+    selectFields(fields: string[]): this;
+    /**
+     * Exclude specific fields from results
+     */
+    excludeFields(fields: string[]): this;
     /**
      * Build the final SearchQuery object
      */

package/dist/search.js

@@ -162,6 +162,20 @@ class SearchQueryBuilder {
         this.query.limit = limit;
         return this;
     }
+    /**
+     * Select specific fields to return
+     */
+    selectFields(fields) {
+        this.query.select_fields = fields;
+        return this;
+    }
+    /**
+     * Exclude specific fields from results
+     */
+    excludeFields(fields) {
+        this.query.exclude_fields = fields;
+        return this;
+    }
     /**
      * Build the final SearchQuery object
      */

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,7 +81,7 @@ 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', ... }
  * ```

package/dist/utils.js

@@ -27,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 }
  * ```
@@ -48,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']);
  * ```
  */
@@ -177,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', ... }
  * ```

package/dist/utils.test.d.ts

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