flowquery 1.0.13 → 1.0.15

package/misc/apps/RAG/src/plugins/loaders/MockData.ts

@@ -6,7 +6,7 @@
  *   RETURN user.name, user.email
  */
 
-import { FunctionDef } from 'flowquery/extensibility';
+import { FunctionDef, AsyncFunction } from 'flowquery/extensibility';
 
 /**
  * MockUsers class - generates mock user data for testing.
@@ -39,7 +39,7 @@ import { FunctionDef } from 'flowquery/extensibility';
         "LOAD JSON FROM mockUsers(20) AS user RETURN user WHERE user.active = true"
     ]
 })
-export class MockUsers {
+export class MockUsers extends AsyncFunction {
     private readonly firstNames: string[];
     private readonly lastNames: string[];
     private readonly domains: string[];
@@ -49,6 +49,7 @@ export class MockUsers {
         lastNames: string[] = ['Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis', 'Rodriguez', 'Martinez'],
         domains: string[] = ['example.com', 'test.org', 'demo.net']
     ) {
+        super();
         this.firstNames = firstNames;
         this.lastNames = lastNames;
         this.domains = domains;
@@ -59,7 +60,7 @@ export class MockUsers {
      * 
      * @param count - Number of mock users to generate
      */
-    async *fetch(count: number = 5): AsyncGenerator<any, void, unknown> {
+    async *generate(count: number = 5): AsyncGenerator<any, void, unknown> {
         for (let i = 0; i < count; i++) {
             const firstName = this.firstNames[Math.floor(Math.random() * this.firstNames.length)];
             const lastName = this.lastNames[Math.floor(Math.random() * this.lastNames.length)];
@@ -108,7 +109,7 @@ export class MockUsers {
         "LOAD JSON FROM mockProducts(50) AS p RETURN p WHERE p.category = 'Electronics'"
     ]
 })
-export class MockProducts {
+export class MockProducts extends AsyncFunction {
     private readonly categories: string[];
     private readonly adjectives: string[];
     private readonly nouns: string[];
@@ -118,6 +119,7 @@ export class MockProducts {
         adjectives: string[] = ['Premium', 'Basic', 'Pro', 'Ultra', 'Classic'],
         nouns: string[] = ['Widget', 'Gadget', 'Item', 'Product', 'Thing']
     ) {
+        super();
         this.categories = categories;
         this.adjectives = adjectives;
         this.nouns = nouns;
@@ -128,7 +130,7 @@ export class MockProducts {
      * 
      * @param count - Number of mock products to generate
      */
-    async *fetch(count: number = 5): AsyncGenerator<any, void, unknown> {
+    async *generate(count: number = 5): AsyncGenerator<any, void, unknown> {
         for (let i = 0; i < count; i++) {
             const adj = this.adjectives[Math.floor(Math.random() * this.adjectives.length)];
             const noun = this.nouns[Math.floor(Math.random() * this.nouns.length)];

package/misc/apps/RAG/src/plugins/loaders/Table.ts

@@ -14,7 +14,7 @@
  * Note: Async providers cannot be nested as function arguments.
  */
 
-import { FunctionDef } from 'flowquery/extensibility';
+import { FunctionDef, AsyncFunction } from 'flowquery/extensibility';
 
 /**
  * Interface for Adaptive Card structure
@@ -90,7 +90,7 @@ interface TableRow {
         "LOAD JSON FROM mockProducts(10) AS p WITH collect(p) AS products LOAD JSON FROM table(products, 'Products', ['name', 'price', 'category']) AS card RETURN card"
     ]
 })
-export class Table {
+export class Table extends AsyncFunction {
     /**
      * Transforms data into an Adaptive Card with table layout.
      * 
@@ -99,7 +99,7 @@ export class Table {
      * @param columns - Optional column names to include
      * @param maxRows - Maximum rows to include
      */
-    async *fetch(
+    async *generate(
         data: any[] | AsyncIterable<any>,
         title: string = 'Data Table',
         columns?: string[],

package/misc/apps/RAG/src/plugins/loaders/Weather.ts

@@ -6,7 +6,7 @@
  *   RETURN forecast
  */
 
-import { FunctionDef } from 'flowquery/extensibility';
+import { FunctionDef, AsyncFunction } from 'flowquery/extensibility';
 
 const GEOCODING_API = 'https://geocoding-api.open-meteo.com/v1/search';
 const WEATHER_API = 'https://api.met.no/weatherapi/locationforecast/2.0/compact';
@@ -48,11 +48,12 @@ const WEATHER_API = 'https://api.met.no/weatherapi/locationforecast/2.0/compact'
         "LOAD JSON FROM weather('London') AS forecast RETURN forecast[0]"
     ]
 })
-export class Weather {
+export class Weather extends AsyncFunction {
     private readonly geocodingApiUrl: string;
     private readonly weatherApiUrl: string;
 
     constructor(geocodingApiUrl: string = GEOCODING_API, weatherApiUrl: string = WEATHER_API) {
+        super();
         this.geocodingApiUrl = geocodingApiUrl;
         this.weatherApiUrl = weatherApiUrl;
     }
@@ -62,7 +63,7 @@ export class Weather {
      * 
      * @param location - The name of the location to get weather for
      */
-    async *fetch(location: string): AsyncGenerator<any, void, unknown> {
+    async *generate(location: string): AsyncGenerator<any, void, unknown> {
         // Step 1: Geocode the location name to get lat/lon
         const geocodeUrl = `${this.geocodingApiUrl}?name=${encodeURIComponent(location)}`;
         const geocodeResponse = await fetch(geocodeUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowquery",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "A declarative query language for data processing pipelines.",
   "main": "dist/index.node.js",
   "types": "dist/index.node.d.ts",
@@ -31,16 +31,26 @@
     "build:node": "tsc",
     "build:browser": "webpack",
     "main": "tsc & node dist/index.js",
-    "docs": "typedoc --out docs/api src/index.node.ts"
+    "docs": "typedoc --out docs/api src/index.node.ts",
+    "prepare": "husky",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+  },
+  "lint-staged": {
+    "*.{ts,js}": "prettier --write",
+    "*.{json,md}": "prettier --write"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
     "@types/jest": "^29.5.14",
     "@types/node": "^25.0.3",
     "copyfiles": "^2.4.1",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
+    "lint-staged": "^15.2.11",
+    "prettier": "^3.4.2",
     "ts-jest": "^29.2.5",
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",

package/src/parsing/expressions/expression_map.ts

@@ -0,0 +1,19 @@
+import Expression from "./expression";
+
+class ExpressionMap {
+    private _map: Map<string, Expression> = new Map();
+    public get(alias: string): Expression | undefined {
+        return this._map.get(alias);
+    }
+    public set map(expressions: Expression[]) {
+        this._map.clear();
+        for (const expr of expressions) {
+            if (expr.alias == undefined) {
+                continue;
+            }
+            this._map.set(expr.alias, expr);
+        }
+    }
+}
+
+export default ExpressionMap;

package/src/parsing/functions/async_function.ts

@@ -29,20 +29,34 @@ class AsyncFunction extends Function {
 
     /**
      * Evaluates all parameters and returns their values.
+     * Used by the framework to pass arguments to generate().
      * 
      * @returns Array of parameter values
      */
-    private getArguments(): any[] {
+    public getArguments(): any[] {
         return this.children.map(child => child.value());
     }
 
     /**
      * Generates the async data provider function results.
      * 
+     * Subclasses override this method with their own typed parameters.
+     * The framework automatically evaluates the AST children and spreads
+     * them as arguments when calling this method.
+     * 
+     * @param args - Arguments passed from the query (e.g., myFunc(arg1, arg2))
      * @yields Data items from the async provider
      * @throws {Error} If the function is not registered as an async provider
+     * 
+     * @example
+     * ```typescript
+     * // Subclass with typed parameters:
+     * async *generate(count: number = 1, filter?: string): AsyncGenerator<any> {
+     *     // Implementation
+     * }
+     * ```
      */
-    public async *generate(): AsyncGenerator<any, void, unknown> {
+    public async *generate(...args: any[]): AsyncGenerator<any, void, unknown> {
         throw new Error("Not implemented: generate method must be overridden in subclasses.");
     }
 }

package/src/parsing/operations/call.ts

@@ -0,0 +1,67 @@
+import Expression from "../expressions/expression";
+import ExpressionMap from "../expressions/expression_map";
+import AsyncFunction from "../functions/async_function";
+import Projection from "./projection";
+
+const DEFAULT_VARIABLE_NAME: string = "value";
+
+class Call extends Projection {
+    protected _function: AsyncFunction | null = null;
+    private _map: ExpressionMap = new ExpressionMap();
+    protected _results: Record<string, any>[] = [];
+    constructor() {
+        super([]);
+    }
+    public set function(asyncFunction: AsyncFunction) {
+        this._function = asyncFunction;
+    }
+    public get function(): AsyncFunction | null {
+        return this._function;
+    }
+    public set yielded(expressions: Expression[]) {
+        this.children = expressions;
+        this._map.map = expressions;
+    }
+    public get hasYield(): boolean {
+        return this.children.length > 0;
+    }
+    public async run(): Promise<void> {
+        if (this._function === null) {
+            throw new Error("No function set for Call operation.");
+        }
+        const args = this._function.getArguments();
+        for await (const item of this._function.generate(...args)) {
+            if (!this.isLast) {
+                if (typeof item == "object" && !Array.isArray(item)) {
+                    for (const [key, value] of Object.entries(item)) {
+                        const expression = this._map.get(key);
+                        if (expression) {
+                            expression.overridden = value;
+                        }
+                    }
+                } else {
+                    const expression = this._map.get(DEFAULT_VARIABLE_NAME);
+                    if (expression) {
+                        expression.overridden = item;
+                    }
+                }
+                await this.next?.run();
+            } else {
+                const record: Map<string, any> = new Map();
+                if (typeof item == "object" && !Array.isArray(item)) {
+                    for (const [key, value] of Object.entries(item)) {
+                        record.set(key, value);
+                    }
+                } else {
+                    record.set(DEFAULT_VARIABLE_NAME, item);
+                }
+                this._results.push(Object.fromEntries(record));
+            }
+        }
+    }
+    public get results(): Record<string, any>[] {
+        return this._results;
+    }
+}
+
+export default Call;

package/src/parsing/operations/load.ts

@@ -1,141 +1,146 @@
-import Operation from "./operation";
 import CSV from "../components/csv";
-import {default as _JSON} from "../components/json";
-import Text from "../components/text";
-import Function from "../functions/function";
-import AsyncFunction from "../functions/async_function";
-import AssociativeArray from "../data_structures/associative_array";
-import Reference from "../expressions/reference";
-import Expression from "../expressions/expression";
+import From from "../components/from";
 import Headers from "../components/headers";
+import { default as _JSON } from "../components/json";
 import Post from "../components/post";
+import Text from "../components/text";
+import AssociativeArray from "../data_structures/associative_array";
 import Lookup from "../data_structures/lookup";
-import From from "../components/from";
+import Expression from "../expressions/expression";
+import Reference from "../expressions/reference";
+import AsyncFunction from "../functions/async_function";
+import Function from "../functions/function";
+import Operation from "./operation";
 
 class Load extends Operation {
-  private _value: any = null;
-  constructor() {
-    super()
-  }
-  public get type(): _JSON | CSV | Text {
-    return this.children[0] as _JSON | CSV | Text;
-  }
+    private _value: any = null;
+
+    constructor() {
+        super();
+    }
+    public get type(): _JSON | CSV | Text {
+        return this.children[0] as _JSON | CSV | Text;
+    }
 
-  /**
-   * Gets the From component which contains either a URL expression or an AsyncFunction.
-   */
-  public get fromComponent(): From {
-    return this.children[1] as From;
-  }
+    /**
+     * Gets the From component which contains either a URL expression or an AsyncFunction.
+     */
+    public get fromComponent(): From {
+        return this.children[1] as From;
+    }
 
-  /**
-   * Checks if the data source is an async function.
-   */
-  public get isAsyncFunction(): boolean {
-    return this.fromComponent.firstChild() instanceof AsyncFunction;
-  }
+    /**
+     * Checks if the data source is an async function.
+     */
+    public get isAsyncFunction(): boolean {
+        return this.fromComponent.firstChild() instanceof AsyncFunction;
+    }
 
-  /**
-   * Gets the async function if the source is a function, otherwise null.
-   */
-  public get asyncFunction(): AsyncFunction | null {
-    const child = this.fromComponent.firstChild();
-    return child instanceof AsyncFunction ? child : null;
-  }
+    /**
+     * Gets the async function if the source is a function, otherwise null.
+     */
+    public get asyncFunction(): AsyncFunction | null {
+        const child = this.fromComponent.firstChild();
+        return child instanceof AsyncFunction ? child : null;
+    }
 
-  public get from(): string {
-    return this.children[1].value() as string;
-  }
-  public get headers(): { [key: string]: string } {
-    if(this.childCount() > 2 && this.children[2] instanceof Headers) {
-      return this.children[2].value() as { [key: string]: string } || {};
+    public get from(): string {
+        return this.children[1].value() as string;
     }
-    return {};
-  }
-  public get payload(): Function | Reference | Expression | AssociativeArray | Lookup | null {
-    let post: Post | null = null;
-    if(this.childCount() > 2 && this.children[2] instanceof Post) {
-      post = this.children[2] as Post;
-    } else if(this.childCount() > 3 && this.children[3] instanceof Post) {
-      post = this.children[3] as Post;
+    public get headers(): { [key: string]: string } {
+        if (this.childCount() > 2 && this.children[2] instanceof Headers) {
+            return (this.children[2].value() as { [key: string]: string }) || {};
+        }
+        return {};
     }
-    return post !== null ? post.firstChild() as Function | Reference | Expression | AssociativeArray | Lookup : null;
-  }
-  private method(): "GET" | "POST" {
-    if(this.payload === null) {
-      return "GET";
-    } else {
-      return "POST";
+    public get payload(): Function | Reference | Expression | AssociativeArray | Lookup | null {
+        let post: Post | null = null;
+        if (this.childCount() > 2 && this.children[2] instanceof Post) {
+            post = this.children[2] as Post;
+        } else if (this.childCount() > 3 && this.children[3] instanceof Post) {
+            post = this.children[3] as Post;
+        }
+        return post !== null
+            ? (post.firstChild() as Function | Reference | Expression | AssociativeArray | Lookup)
+            : null;
     }
-  }
-  private options(): object {
-    const headers = this.headers as { [key: string]: string };
-    const payload = this.payload;
-    const data = payload?.value();
-    if(data !== null && typeof data === "object" && !(headers.hasOwnProperty("Content-Type"))) {
-      headers["Content-Type"] = "application/json";
+    private method(): "GET" | "POST" {
+        if (this.payload === null) {
+            return "GET";
+        } else {
+            return "POST";
+        }
     }
-    return {
-      "method": this.method(),
-      "headers": headers,
-      ...(payload !== null ? {"body": JSON.stringify(payload.value())} : {})
-    };
-  }
-
-  /**
-   * Loads data from an async function source.
-   */
-  private async loadFromFunction(): Promise<void> {
-    const asyncFunc = this.asyncFunction!;
-    for await (const item of asyncFunc.generate()) {
-      this._value = item;
-      await this.next?.run();
+    private options(): object {
+        const headers = this.headers as { [key: string]: string };
+        const payload = this.payload;
+        const data = payload?.value();
+        if (data !== null && typeof data === "object" && !headers.hasOwnProperty("Content-Type")) {
+            headers["Content-Type"] = "application/json";
+        }
+        return {
+            method: this.method(),
+            headers: headers,
+            ...(payload !== null ? { body: JSON.stringify(payload.value()) } : {}),
+        };
     }
-  }
 
-  /**
-   * Loads data from a URL source (original behavior).
-   */
-  private async loadFromUrl(): Promise<void> {
-    const result = await fetch(this.from, this.options());
-    let data: any = null;
-    if(this.type instanceof _JSON) {
-      data = await result.json();
-    } else if(this.type instanceof Text) {
-      data = await result.text();
+    /**
+     * Loads data from an async function source.
+     * Arguments from the query (e.g., myFunc(arg1, arg2)) are passed to generate().
+     */
+    private async loadFromFunction(): Promise<void> {
+        const asyncFunc = this.asyncFunction!;
+        const args = asyncFunc.getArguments();
+        for await (const item of asyncFunc.generate(...args)) {
+            this._value = item;
+            await this.next?.run();
+        }
     }
-    if(Array.isArray(data)) {
-      for(const item of data) {
-        this._value = item;
-        await this.next?.run();
-      }
-    } else if(typeof data === "object" && data !== null) {
-      this._value = data;
-      await this.next?.run();
-    } else if(typeof data === "string") {
-      this._value = data;
-      await this.next?.run();
+
+    /**
+     * Loads data from a URL source (original behavior).
+     */
+    private async loadFromUrl(): Promise<void> {
+        const result = await fetch(this.from, this.options());
+        let data: any = null;
+        if (this.type instanceof _JSON) {
+            data = await result.json();
+        } else if (this.type instanceof Text) {
+            data = await result.text();
+        }
+        if (Array.isArray(data)) {
+            for (const item of data) {
+                this._value = item;
+                await this.next?.run();
+            }
+        } else if (typeof data === "object" && data !== null) {
+            this._value = data;
+            await this.next?.run();
+        } else if (typeof data === "string") {
+            this._value = data;
+            await this.next?.run();
+        }
     }
-  }
 
-  public async load(): Promise<any> {
-    if (this.isAsyncFunction) {
-      await this.loadFromFunction();
-    } else {
-      await this.loadFromUrl();
+    public async load(): Promise<any> {
+        if (this.isAsyncFunction) {
+            await this.loadFromFunction();
+        } else {
+            await this.loadFromUrl();
+        }
+    }
+    public async run(): Promise<void> {
+        try {
+            await this.load();
+        } catch (e) {
+            const source = this.isAsyncFunction ? this.asyncFunction?.name : this.from;
+            throw new Error(`Failed to load data from ${source}. Error: ${e}`);
+        }
     }
-  }
-  public async run(): Promise<void> {
-    try {
-      await this.load();
-    } catch(e) {
-      const source = this.isAsyncFunction ? this.asyncFunction?.name : this.from;
-      throw new Error(`Failed to load data from ${source}. Error: ${e}`);
+    public value(): any {
+        return this._value;
     }
-  }
-  public value(): any {
-    return this._value;
-  }
 }
 
-export default Load;
+export default Load;

package/src/parsing/operations/operation.ts

@@ -2,16 +2,16 @@ import ASTNode from "../ast_node";
 
 /**
  * Base class for all FlowQuery operations.
- * 
+ *
  * Operations represent the main statements in FlowQuery (WITH, UNWIND, RETURN, LOAD, WHERE).
  * They form a linked list structure and can be executed sequentially.
- * 
+ *
  * @abstract
  */
 abstract class Operation extends ASTNode {
     private _previous: Operation | null = null;
     private _next: Operation | null = null;
-    
+
     /**
      * Creates a new Operation instance.
      */
@@ -35,31 +35,32 @@ abstract class Operation extends ASTNode {
         operation.previous = this;
         this.next = operation;
     }
-    
+    public get isLast(): boolean {
+        return this._next === null;
+    }
+
     /**
      * Executes this operation. Must be implemented by subclasses.
-     * 
+     *
      * @returns A promise that resolves when the operation completes
      * @throws {Error} If not implemented by subclass
      */
     public async run(): Promise<void> {
-        throw new Error('Not implemented');
+        throw new Error("Not implemented");
     }
-    
+
     /**
      * Finishes execution by calling finish on the next operation in the chain.
-     * 
+     *
      * @returns A promise that resolves when all operations finish
      */
     public async finish(): Promise<void> {
         await this.next?.finish();
     }
-    public reset(): void {
-        ;
-    }
+    public reset(): void {}
     public get results(): Record<string, any>[] {
-        throw new Error('Not implemented');
+        throw new Error("Not implemented");
     }
 }
 
-export default Operation;
+export default Operation;

package/src/parsing/operations/projection.ts

@@ -1,5 +1,5 @@
-import Operation from "./operation";
 import Expression from "../expressions/expression";
+import Operation from "./operation";
 
 class Projection extends Operation {
     constructor(expressions: Expression[]) {
@@ -7,7 +7,7 @@ class Projection extends Operation {
         this.children = expressions;
     }
     protected *expressions(): Generator<[Expression, string]> {
-        for(let i = 0; i < this.children.length; i++) {
+        for (let i = 0; i < this.children.length; i++) {
             const expression: Expression = this.children[i] as Expression;
             const alias = expression.alias || `expr${i}`;
             yield [expression, alias];
@@ -15,4 +15,4 @@ class Projection extends Operation {
     }
 }
 
-export default Projection;
+export default Projection;