@ekodb/ekodb-client 0.1.0

package/dist/join.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Join support for multi-collection queries
+ *
+ * This module provides support for joining data across multiple collections,
+ * similar to SQL joins but with document-oriented semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JoinBuilder = void 0;
+/**
+ * Builder for constructing join configurations
+ *
+ * @example
+ * ```typescript
+ * // Single collection join
+ * const join = JoinBuilder.single("users", "user_id", "id", "user");
+ *
+ * // Multi-collection join
+ * const join = JoinBuilder.multi(
+ *   ["users", "profiles", "settings"],
+ *   "user_id",
+ *   "id",
+ *   "user_info"
+ * );
+ *
+ * // Use in query
+ * const query = new QueryBuilder()
+ *   .eq("status", "active")
+ *   .join(join)
+ *   .build();
+ * ```
+ */
+class JoinBuilder {
+    constructor(collections, localField, foreignField, asField) {
+        this.config = {
+            collections,
+            local_field: localField,
+            foreign_field: foreignField,
+            as_field: asField,
+        };
+    }
+    /**
+     * Create a join with a single collection
+     *
+     * @param collection - Target collection name
+     * @param localField - Field in the current collection
+     * @param foreignField - Field in the target collection
+     * @param asField - Name of the field to store joined data
+     */
+    static single(collection, localField, foreignField, asField) {
+        return new JoinBuilder([collection], localField, foreignField, asField).build();
+    }
+    /**
+     * Create a join with multiple collections
+     *
+     * @param collections - Array of target collection names
+     * @param localField - Field in the current collection
+     * @param foreignField - Field in the target collections
+     * @param asField - Name of the field to store joined data
+     */
+    static multi(collections, localField, foreignField, asField) {
+        return new JoinBuilder(collections, localField, foreignField, asField).build();
+    }
+    /**
+     * Build the final JoinConfig
+     */
+    build() {
+        return this.config;
+    }
+}
+exports.JoinBuilder = JoinBuilder;

package/dist/query-builder.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Query Builder for constructing complex queries with fluent API
+ */
+export declare enum SortOrder {
+    Asc = "asc",
+    Desc = "desc"
+}
+export interface Query {
+    filter?: any;
+    sort?: Array<{
+        field: string;
+        ascending: boolean;
+    }>;
+    limit?: number;
+    skip?: number;
+    join?: any;
+    bypass_cache?: boolean;
+    bypass_ripple?: boolean;
+}
+/**
+ * Fluent API for building complex database queries
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ *   .eq("status", "active")
+ *   .gt("age", 18)
+ *   .sortDesc("created_at")
+ *   .limit(10)
+ *   .build();
+ * ```
+ */
+export declare class QueryBuilder {
+    private filters;
+    private sortFields;
+    private _limit?;
+    private _skip?;
+    private _join?;
+    private _bypassCache;
+    private _bypassRipple;
+    /**
+     * Add an equality filter ($eq)
+     */
+    eq(field: string, value: any): this;
+    /**
+     * Add a not-equal filter ($ne)
+     */
+    ne(field: string, value: any): this;
+    /**
+     * Add a greater-than filter ($gt)
+     */
+    gt(field: string, value: any): this;
+    /**
+     * Add a greater-than-or-equal filter ($gte)
+     */
+    gte(field: string, value: any): this;
+    /**
+     * Add a less-than filter ($lt)
+     */
+    lt(field: string, value: any): this;
+    /**
+     * Add a less-than-or-equal filter ($lte)
+     */
+    lte(field: string, value: any): this;
+    /**
+     * Add an in-array filter ($in)
+     */
+    in(field: string, values: any[]): this;
+    /**
+     * Add a not-in-array filter ($nin)
+     */
+    nin(field: string, values: any[]): this;
+    /**
+     * Add a contains filter (substring match)
+     */
+    contains(field: string, substring: string): this;
+    /**
+     * Add a starts-with filter
+     */
+    startsWith(field: string, prefix: string): this;
+    /**
+     * Add an ends-with filter
+     */
+    endsWith(field: string, suffix: string): this;
+    /**
+     * Add a regex filter
+     */
+    regex(field: string, pattern: string): this;
+    /**
+     * Combine filters with AND logic
+     */
+    and(conditions: any[]): this;
+    /**
+     * Combine filters with OR logic
+     */
+    or(conditions: any[]): this;
+    /**
+     * Negate a filter
+     */
+    not(condition: any): this;
+    /**
+     * Add a raw filter expression
+     */
+    rawFilter(filter: any): this;
+    /**
+     * Add a sort field in ascending order
+     */
+    sortAsc(field: string): this;
+    /**
+     * Add a sort field in descending order
+     */
+    sortDesc(field: string): this;
+    /**
+     * Set the maximum number of results
+     */
+    limit(limit: number): this;
+    /**
+     * Set the number of results to skip (for pagination)
+     */
+    skip(skip: number): this;
+    /**
+     * Set page number and page size (convenience method)
+     */
+    page(page: number, pageSize: number): this;
+    /**
+     * Add a join configuration
+     */
+    join(joinConfig: any): this;
+    /**
+     * Bypass cache for this query
+     */
+    bypassCache(bypass?: boolean): this;
+    /**
+     * Bypass ripple for this query
+     */
+    bypassRipple(bypass?: boolean): this;
+    /**
+     * Build the final Query object
+     */
+    build(): Query;
+}

package/dist/query-builder.js

@@ -0,0 +1,370 @@
+"use strict";
+/**
+ * Query Builder for constructing complex queries with fluent API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = exports.SortOrder = void 0;
+var SortOrder;
+(function (SortOrder) {
+    SortOrder["Asc"] = "asc";
+    SortOrder["Desc"] = "desc";
+})(SortOrder || (exports.SortOrder = SortOrder = {}));
+/**
+ * Fluent API for building complex database queries
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ *   .eq("status", "active")
+ *   .gt("age", 18)
+ *   .sortDesc("created_at")
+ *   .limit(10)
+ *   .build();
+ * ```
+ */
+class QueryBuilder {
+    constructor() {
+        this.filters = [];
+        this.sortFields = [];
+        this._bypassCache = false;
+        this._bypassRipple = false;
+    }
+    // ========================================================================
+    // Comparison Operators
+    // ========================================================================
+    /**
+     * Add an equality filter ($eq)
+     */
+    eq(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Eq",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a not-equal filter ($ne)
+     */
+    ne(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Ne",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a greater-than filter ($gt)
+     */
+    gt(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Gt",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a greater-than-or-equal filter ($gte)
+     */
+    gte(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Gte",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a less-than filter ($lt)
+     */
+    lt(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Lt",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a less-than-or-equal filter ($lte)
+     */
+    lte(field, value) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Lte",
+                value,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add an in-array filter ($in)
+     */
+    in(field, values) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "In",
+                value: values,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a not-in-array filter ($nin)
+     */
+    nin(field, values) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "NotIn",
+                value: values,
+            },
+        });
+        return this;
+    }
+    // ========================================================================
+    // String Operators
+    // ========================================================================
+    /**
+     * Add a contains filter (substring match)
+     */
+    contains(field, substring) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Contains",
+                value: substring,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a starts-with filter
+     */
+    startsWith(field, prefix) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "StartsWith",
+                value: prefix,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add an ends-with filter
+     */
+    endsWith(field, suffix) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "EndsWith",
+                value: suffix,
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a regex filter
+     */
+    regex(field, pattern) {
+        this.filters.push({
+            type: "Condition",
+            content: {
+                field,
+                operator: "Regex",
+                value: pattern,
+            },
+        });
+        return this;
+    }
+    // ========================================================================
+    // Logical Operators
+    // ========================================================================
+    /**
+     * Combine filters with AND logic
+     */
+    and(conditions) {
+        this.filters.push({
+            type: "Logical",
+            content: {
+                operator: "And",
+                expressions: conditions,
+            },
+        });
+        return this;
+    }
+    /**
+     * Combine filters with OR logic
+     */
+    or(conditions) {
+        this.filters.push({
+            type: "Logical",
+            content: {
+                operator: "Or",
+                expressions: conditions,
+            },
+        });
+        return this;
+    }
+    /**
+     * Negate a filter
+     */
+    not(condition) {
+        this.filters.push({
+            type: "Logical",
+            content: {
+                operator: "Not",
+                expressions: [condition],
+            },
+        });
+        return this;
+    }
+    /**
+     * Add a raw filter expression
+     */
+    rawFilter(filter) {
+        this.filters.push(filter);
+        return this;
+    }
+    // ========================================================================
+    // Sorting
+    // ========================================================================
+    /**
+     * Add a sort field in ascending order
+     */
+    sortAsc(field) {
+        this.sortFields.push({ field, order: SortOrder.Asc });
+        return this;
+    }
+    /**
+     * Add a sort field in descending order
+     */
+    sortDesc(field) {
+        this.sortFields.push({ field, order: SortOrder.Desc });
+        return this;
+    }
+    // ========================================================================
+    // Pagination
+    // ========================================================================
+    /**
+     * Set the maximum number of results
+     */
+    limit(limit) {
+        this._limit = limit;
+        return this;
+    }
+    /**
+     * Set the number of results to skip (for pagination)
+     */
+    skip(skip) {
+        this._skip = skip;
+        return this;
+    }
+    /**
+     * Set page number and page size (convenience method)
+     */
+    page(page, pageSize) {
+        this._skip = page * pageSize;
+        this._limit = pageSize;
+        return this;
+    }
+    // ========================================================================
+    // Joins
+    // ========================================================================
+    /**
+     * Add a join configuration
+     */
+    join(joinConfig) {
+        this._join = joinConfig;
+        return this;
+    }
+    // ========================================================================
+    // Performance Flags
+    // ========================================================================
+    /**
+     * Bypass cache for this query
+     */
+    bypassCache(bypass = true) {
+        this._bypassCache = bypass;
+        return this;
+    }
+    /**
+     * Bypass ripple for this query
+     */
+    bypassRipple(bypass = true) {
+        this._bypassRipple = bypass;
+        return this;
+    }
+    // ========================================================================
+    // Build
+    // ========================================================================
+    /**
+     * Build the final Query object
+     */
+    build() {
+        const query = {};
+        // Combine all filters with AND logic if multiple filters exist
+        if (this.filters.length > 0) {
+            query.filter =
+                this.filters.length === 1
+                    ? this.filters[0]
+                    : {
+                        type: "Logical",
+                        content: {
+                            operator: "And",
+                            expressions: this.filters,
+                        },
+                    };
+        }
+        // Build sort expression
+        if (this.sortFields.length > 0) {
+            query.sort = this.sortFields.map(({ field, order }) => ({
+                field,
+                ascending: order === SortOrder.Asc,
+            }));
+        }
+        if (this._limit !== undefined) {
+            query.limit = this._limit;
+        }
+        if (this._skip !== undefined) {
+            query.skip = this._skip;
+        }
+        if (this._join !== undefined) {
+            query.join = this._join;
+        }
+        if (this._bypassCache) {
+            query.bypass_cache = true;
+        }
+        if (this._bypassRipple) {
+            query.bypass_ripple = true;
+        }
+        return query;
+    }
+}
+exports.QueryBuilder = QueryBuilder;