@wowsql/sdk 3.5.0 → 3.6.0

package/README.md

@@ -312,6 +312,138 @@ console.log(result.affected_rows); // Number of rows deleted
 
 // Is null
 .filter({ column: 'deleted_at', operator: 'is', value: null })
+
+// IN operator (value must be an array)
+.filter('category', 'in', ['electronics', 'books', 'clothing'])
+
+// NOT IN operator
+.filter('status', 'not_in', ['deleted', 'archived'])
+
+// BETWEEN operator (value must be an array of 2 values)
+.filter('price', 'between', [10, 100])
+
+// NOT BETWEEN operator
+.filter('age', 'not_between', [18, 65])
+
+// OR logical operator
+.filter('category', 'eq', 'electronics', 'AND')
+.filter('price', 'gt', 1000, 'OR')  // OR condition
+```
+
+## Advanced Query Features
+
+### GROUP BY and Aggregates
+
+GROUP BY supports both simple column names and SQL expressions with functions. All expressions are validated for security.
+
+#### Basic GROUP BY
+
+```typescript
+// Group by single column
+const result = await client.table("products")
+  .select("category", "COUNT(*) as count", "AVG(price) as avg_price")
+  .groupBy("category")
+  .get();
+
+// Group by multiple columns
+const result = await client.table("sales")
+  .select("region", "category", "SUM(amount) as total")
+  .groupBy(["region", "category"])
+  .get();
+```
+
+#### GROUP BY with Date/Time Functions
+
+```typescript
+// Group by date
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "COUNT(*) as orders", "SUM(total) as revenue")
+  .groupBy("DATE(created_at)")
+  .orderBy("date", "desc")
+  .get();
+
+// Group by year and month
+const result = await client.table("orders")
+  .select("YEAR(created_at) as year", "MONTH(created_at) as month", "SUM(total) as revenue")
+  .groupBy(["YEAR(created_at)", "MONTH(created_at)"])
+  .get();
+
+// Group by week
+const result = await client.table("orders")
+  .select("WEEK(created_at) as week", "COUNT(*) as orders")
+  .groupBy("WEEK(created_at)")
+  .get();
+```
+
+#### Supported Functions in GROUP BY
+
+**Date/Time:** `DATE()`, `YEAR()`, `MONTH()`, `DAY()`, `WEEK()`, `QUARTER()`, `HOUR()`, `MINUTE()`, `SECOND()`, `DATE_FORMAT()`, `DATE_ADD()`, `DATE_SUB()`, `DATEDIFF()`, `NOW()`, `CURRENT_TIMESTAMP()`, etc.
+
+**String:** `CONCAT()`, `SUBSTRING()`, `LEFT()`, `RIGHT()`, `UPPER()`, `LOWER()`, `LENGTH()`, `TRIM()`, etc.
+
+**Mathematical:** `ROUND()`, `CEIL()`, `FLOOR()`, `ABS()`, `POW()`, `SQRT()`, `MOD()`, etc.
+
+### HAVING Clause
+
+HAVING filters aggregated results after GROUP BY. Supports aggregate functions and comparison operators.
+
+```typescript
+// Filter aggregated results
+const result = await client.table("products")
+  .select("category", "COUNT(*) as count")
+  .groupBy("category")
+  .having("COUNT(*)", "gt", 10)
+  .get();
+
+// Multiple HAVING conditions
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "SUM(total) as revenue")
+  .groupBy("DATE(created_at)")
+  .having("SUM(total)", "gt", 1000)
+  .having("COUNT(*)", "gte", 5)
+  .get();
+
+// HAVING with different aggregate functions
+const result = await client.table("products")
+  .select("category", "AVG(price) as avg_price", "COUNT(*) as count")
+  .groupBy("category")
+  .having("AVG(price)", "gt", 100)
+  .having("COUNT(*)", "gte", 5)
+  .get();
+```
+
+**Supported HAVING Operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
+
+**Supported Aggregate Functions:** `COUNT(*)`, `SUM()`, `AVG()`, `MAX()`, `MIN()`, `GROUP_CONCAT()`, `STDDEV()`, `VARIANCE()`
+
+### Multiple ORDER BY
+
+```typescript
+// Order by multiple columns
+const result = await client.table("products")
+  .select("*")
+  .orderByMultiple([
+    { column: "category", direction: "asc" },
+    { column: "price", direction: "desc" },
+    { column: "created_at", direction: "desc" }
+  ])
+  .get();
+```
+
+### Date/Time Functions
+
+```typescript
+// Filter by date range using functions
+const result = await client.table("orders")
+  .select("*")
+  .filter("created_at", "gte", "DATE_SUB(NOW(), INTERVAL 7 DAY)")
+  .get();
+
+// Group by date
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "COUNT(*) as count")
+  .groupBy("DATE(created_at)")
+  .get();
 ```
 
 ### Complex Queries

package/dist/index.d.ts

@@ -20,13 +20,17 @@ export interface WowSQLConfig {
     timeout?: number;
 }
 export interface QueryOptions {
-    /** Columns to select (comma-separated or array) */
+    /** Columns to select (comma-separated or array) - can include expressions like "COUNT(*)", "DATE(created_at) as date" */
     select?: string | string[];
     /** Filter expressions */
     filter?: FilterExpression | FilterExpression[];
-    /** Column to sort by */
-    order?: string;
-    /** Sort direction */
+    /** Columns to group by */
+    group_by?: string | string[];
+    /** HAVING clause filters for aggregated results */
+    having?: HavingFilter | HavingFilter[];
+    /** Column(s) to sort by - can be string or array of OrderByItem */
+    order?: string | OrderByItem[];
+    /** Sort direction (used only if order is a string) */
     orderDirection?: 'asc' | 'desc';
     /** Maximum records to return */
     limit?: number;
@@ -35,9 +39,19 @@ export interface QueryOptions {
 }
 export interface FilterExpression {
     column: string;
-    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is';
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is' | 'in' | 'not_in' | 'between' | 'not_between' | 'is_not';
+    value: string | number | boolean | null | any[] | [any, any];
+    logical_op?: 'AND' | 'OR';
+}
+export interface HavingFilter {
+    column: string;
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
     value: string | number | boolean | null;
 }
+export interface OrderByItem {
+    column: string;
+    direction: 'asc' | 'desc';
+}
 export interface QueryResponse<T = any> {
     data: T[];
     count: number;
@@ -117,7 +131,7 @@ export declare class Table<T = any> {
     /**
      * Query with filter
      */
-    filter(filter: FilterExpression): QueryBuilder<T>;
+    filter(column: string, operator: FilterExpression['operator'], value: any, logical_op?: 'AND' | 'OR'): QueryBuilder<T>;
     /**
      * Get all records (with optional limit)
      */
@@ -145,15 +159,39 @@ export declare class QueryBuilder<T = any> {
     private options;
     constructor(client: AxiosInstance, tableName: string);
     /**
-     * Select specific columns
+     * Select specific columns or expressions
+     * @example query.select('id', 'name')
+     * @example query.select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
      */
-    select(columns: string | string[]): this;
+    select(...columns: (string | string[])[]): this;
     /**
      * Add filter condition
+     * @example query.filter('age', 'gt', 18)
+     * @example query.filter('category', 'in', ['electronics', 'books'])
+     * @example query.filter('price', 'between', [10, 100])
+     */
+    filter(column: string, operator: FilterExpression['operator'], value: any, logical_op?: 'AND' | 'OR'): this;
+    /**
+     * Group results by column(s)
+     * @example query.groupBy('category')
+     * @example query.groupBy(['category', 'status'])
+     * @example query.groupBy('DATE(created_at)')
+     */
+    groupBy(columns: string | string[]): this;
+    /**
+     * Add HAVING clause filter (for filtering aggregated results)
+     * @example query.having('COUNT(*)', 'gt', 10)
+     * @example query.having('AVG(price)', 'gte', 50)
+     */
+    having(column: string, operator: HavingFilter['operator'], value: any): this;
+    /**
+     * Order by column(s)
+     * @example query.orderBy('created_at', 'desc')
+     * @example query.orderBy([{column: 'category', direction: 'asc'}, {column: 'price', direction: 'desc'}])
      */
-    filter(filter: FilterExpression): this;
+    orderBy(column: string | OrderByItem[], direction?: 'asc' | 'desc'): this;
     /**
-     * Order by column
+     * Order by a single column (alias for orderBy for backward compatibility)
      */
     order(column: string, direction?: 'asc' | 'desc'): this;
     /**
@@ -165,7 +203,7 @@ export declare class QueryBuilder<T = any> {
      */
     offset(offset: number): this;
     /**
-     * Execute query
+     * Execute query - uses POST /{table}/query for advanced features, GET for simple queries
      */
     get(additionalOptions?: QueryOptions): Promise<QueryResponse<T>>;
     /**

package/dist/index.js

@@ -125,8 +125,8 @@ class Table {
     /**
      * Query with filter
      */
-    filter(filter) {
-        return new QueryBuilder(this.client, this.tableName).filter(filter);
+    filter(column, operator, value, logical_op = 'AND') {
+        return new QueryBuilder(this.client, this.tableName).filter(column, operator, value, logical_op);
     }
     /**
      * Get all records (with optional limit)
@@ -172,19 +172,33 @@ class QueryBuilder {
         this.options = {};
     }
     /**
-     * Select specific columns
+     * Select specific columns or expressions
+     * @example query.select('id', 'name')
+     * @example query.select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
      */
-    select(columns) {
-        this.options.select = Array.isArray(columns) ? columns.join(',') : columns;
+    select(...columns) {
+        if (columns.length === 1 && Array.isArray(columns[0])) {
+            this.options.select = columns[0];
+        }
+        else if (columns.length === 1 && typeof columns[0] === 'string') {
+            this.options.select = columns[0];
+        }
+        else {
+            this.options.select = columns;
+        }
         return this;
     }
     /**
      * Add filter condition
+     * @example query.filter('age', 'gt', 18)
+     * @example query.filter('category', 'in', ['electronics', 'books'])
+     * @example query.filter('price', 'between', [10, 100])
      */
-    filter(filter) {
+    filter(column, operator, value, logical_op = 'AND') {
         if (!this.options.filter) {
             this.options.filter = [];
         }
+        const filter = { column, operator, value, logical_op };
         if (Array.isArray(this.options.filter)) {
             this.options.filter.push(filter);
         }
@@ -194,13 +208,56 @@ class QueryBuilder {
         return this;
     }
     /**
-     * Order by column
+     * Group results by column(s)
+     * @example query.groupBy('category')
+     * @example query.groupBy(['category', 'status'])
+     * @example query.groupBy('DATE(created_at)')
      */
-    order(column, direction = 'asc') {
-        this.options.order = column;
-        this.options.orderDirection = direction;
+    groupBy(columns) {
+        this.options.group_by = columns;
+        return this;
+    }
+    /**
+     * Add HAVING clause filter (for filtering aggregated results)
+     * @example query.having('COUNT(*)', 'gt', 10)
+     * @example query.having('AVG(price)', 'gte', 50)
+     */
+    having(column, operator, value) {
+        if (!this.options.having) {
+            this.options.having = [];
+        }
+        const havingFilter = { column, operator, value };
+        if (Array.isArray(this.options.having)) {
+            this.options.having.push(havingFilter);
+        }
+        else {
+            this.options.having = [this.options.having, havingFilter];
+        }
+        return this;
+    }
+    /**
+     * Order by column(s)
+     * @example query.orderBy('created_at', 'desc')
+     * @example query.orderBy([{column: 'category', direction: 'asc'}, {column: 'price', direction: 'desc'}])
+     */
+    orderBy(column, direction) {
+        if (typeof column === 'string') {
+            this.options.order = column;
+            if (direction) {
+                this.options.orderDirection = direction;
+            }
+        }
+        else {
+            this.options.order = column;
+        }
         return this;
     }
+    /**
+     * Order by a single column (alias for orderBy for backward compatibility)
+     */
+    order(column, direction = 'asc') {
+        return this.orderBy(column, direction);
+    }
     /**
      * Limit number of results
      */
@@ -216,35 +273,98 @@ class QueryBuilder {
         return this;
     }
     /**
-     * Execute query
+     * Execute query - uses POST /{table}/query for advanced features, GET for simple queries
      */
     async get(additionalOptions) {
         const finalOptions = { ...this.options, ...additionalOptions };
-        // Build query parameters
-        const params = {};
+        // Build query request body for POST endpoint
+        const body = {};
+        // Select
         if (finalOptions.select) {
-            params.select = finalOptions.select;
+            body.select = Array.isArray(finalOptions.select)
+                ? finalOptions.select
+                : typeof finalOptions.select === 'string'
+                    ? finalOptions.select.split(',').map(s => s.trim())
+                    : [finalOptions.select];
         }
+        // Filters
         if (finalOptions.filter) {
-            const filters = Array.isArray(finalOptions.filter)
+            body.filters = Array.isArray(finalOptions.filter)
                 ? finalOptions.filter
                 : [finalOptions.filter];
-            params.filter = filters
-                .map((f) => `${f.column}.${f.operator}.${f.value}`)
-                .join(',');
         }
+        // Group by
+        if (finalOptions.group_by) {
+            body.group_by = Array.isArray(finalOptions.group_by)
+                ? finalOptions.group_by
+                : typeof finalOptions.group_by === 'string'
+                    ? finalOptions.group_by.split(',').map(s => s.trim())
+                    : [finalOptions.group_by];
+        }
+        // Having
+        if (finalOptions.having) {
+            body.having = Array.isArray(finalOptions.having)
+                ? finalOptions.having
+                : [finalOptions.having];
+        }
+        // Order by
         if (finalOptions.order) {
-            params.order = finalOptions.order;
-            params.order_direction = finalOptions.orderDirection || 'asc';
+            if (typeof finalOptions.order === 'string') {
+                body.order_by = finalOptions.order;
+                body.order_direction = finalOptions.orderDirection || 'asc';
+            }
+            else {
+                body.order_by = finalOptions.order;
+            }
         }
+        // Limit and offset
         if (finalOptions.limit !== undefined) {
-            params.limit = finalOptions.limit;
+            body.limit = finalOptions.limit;
         }
         if (finalOptions.offset !== undefined) {
-            params.offset = finalOptions.offset;
+            body.offset = finalOptions.offset;
+        }
+        // Check if we need POST endpoint (advanced features)
+        const hasAdvancedFeatures = body.group_by ||
+            body.having ||
+            Array.isArray(body.order_by) ||
+            (body.filters && body.filters.some((f) => ['in', 'not_in', 'between', 'not_between'].includes(f.operator)));
+        if (hasAdvancedFeatures) {
+            // Use POST endpoint for advanced queries
+            const response = await this.client.post(`/${this.tableName}/query`, body);
+            return response.data;
+        }
+        else {
+            // Use GET endpoint for simple queries (backward compatibility)
+            const params = {};
+            if (body.select) {
+                params.select = Array.isArray(body.select) ? body.select.join(',') : body.select;
+            }
+            if (body.filters && body.filters.length > 0) {
+                // Check if any filter uses array values (can't use GET)
+                const hasArrayValues = body.filters.some((f) => Array.isArray(f.value));
+                if (hasArrayValues) {
+                    // Must use POST
+                    const response = await this.client.post(`/${this.tableName}/query`, body);
+                    return response.data;
+                }
+                params.filter = body.filters
+                    .map((f) => `${f.column}.${f.operator}.${f.value}`)
+                    .join(',');
+            }
+            if (body.order_by && typeof body.order_by === 'string') {
+                params.order = body.order_by;
+                params.order_direction = body.order_direction || 'asc';
+            }
+            if (body.limit !== undefined) {
+                params.limit = body.limit;
+            }
+            if (body.offset !== undefined) {
+                params.offset = body.offset;
+            }
+            const response = await this.client.get(`/${this.tableName}`, { params });
+            return response.data;
         }
-        const response = await this.client.get(`/${this.tableName}`, { params });
-        return response.data;
     }
     /**
      * Get first record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowsql/sdk",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Official TypeScript/JavaScript SDK for WowSQL - MySQL Backend-as-a-Service with S3 Storage, type-safe queries and fluent API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",