flowquery 1.0.32 → 1.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowquery",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "A declarative query language for data processing pipelines.",
   "main": "dist/index.node.js",
   "types": "dist/index.node.d.ts",

package/src/compute/flowquery.ts

@@ -0,0 +1,46 @@
+import Function from "../parsing/functions/function";
+import { FunctionMetadata } from "../parsing/functions/function_metadata";
+import Runner from "./runner";
+
+/**
+ * FlowQuery is the public API surface for the FlowQuery library.
+ *
+ * It extends {@link Runner} with extensibility features such as function
+ * listing and plugin registration, keeping the Runner focused on execution.
+ *
+ * The static members are assigned dynamically in
+ * {@link ../index.browser.ts | index.browser.ts} and
+ * {@link ../index.node.ts | index.node.ts}.
+ *
+ * @example
+ * ```typescript
+ * const fq = new FlowQuery("WITH 1 as x RETURN x");
+ * await fq.run();
+ * console.log(fq.results); // [{ x: 1 }]
+ *
+ * // List all registered functions
+ * const functions = FlowQuery.listFunctions();
+ * ```
+ */
+class FlowQuery extends Runner {
+    /**
+     * List all registered functions with their metadata.
+     */
+    static listFunctions: (options?: {
+        category?: string;
+        asyncOnly?: boolean;
+        syncOnly?: boolean;
+    }) => FunctionMetadata[];
+
+    /**
+     * Get metadata for a specific function.
+     */
+    static getFunctionMetadata: (name: string) => FunctionMetadata | undefined;
+
+    /**
+     * Base Function class for creating custom plugin functions.
+     */
+    static Function: typeof Function;
+}
+
+export default FlowQuery;

package/src/compute/runner.ts

@@ -1,6 +1,4 @@
 import ASTNode from "../parsing/ast_node";
-import Function from "../parsing/functions/function";
-import { FunctionMetadata } from "../parsing/functions/function_metadata";
 import Operation from "../parsing/operations/operation";
 import Parser from "../parsing/parser";
 
@@ -21,28 +19,6 @@ class Runner {
     private first: Operation;
     private last: Operation;
 
-    /**
-     * List all registered functions with their metadata.
-     * Added dynamically in index.browser.ts / index.node.ts
-     */
-    static listFunctions: (options?: {
-        category?: string;
-        asyncOnly?: boolean;
-        syncOnly?: boolean;
-    }) => FunctionMetadata[];
-
-    /**
-     * Get metadata for a specific function.
-     * Added dynamically in index.browser.ts / index.node.ts
-     */
-    static getFunctionMetadata: (name: string) => FunctionMetadata | undefined;
-
-    /**
-     * Base Function class for creating custom plugin functions.
-     * Added dynamically in index.browser.ts / index.node.ts
-     */
-    static Function: typeof Function;
-
     /**
      * Creates a new Runner instance and parses the FlowQuery statement.
      *

package/src/index.browser.ts

@@ -1,37 +1,40 @@
 /**
  * FlowQuery - A declarative query language for data processing pipelines.
- * 
+ *
  * This is the main entry point for the FlowQuery in-browser usage.
- * 
+ *
  * @packageDocumentation
  */
-
-import {default as FlowQuery} from "./compute/runner";
+import { default as FlowQuery } from "./compute/flowquery";
+import Function from "./parsing/functions/function";
 import FunctionFactory from "./parsing/functions/function_factory";
-import { 
-    FunctionMetadata, 
-    ParameterSchema, 
-    OutputSchema
+import {
+    FunctionMetadata,
+    OutputSchema,
+    ParameterSchema,
 } from "./parsing/functions/function_metadata";
-import Function from "./parsing/functions/function";
 
 /**
  * List all registered functions with their metadata.
- * 
+ *
  * @param options - Optional filter options
  * @returns Array of function metadata
  */
-FlowQuery.listFunctions = function(options?: { category?: string; asyncOnly?: boolean; syncOnly?: boolean }): FunctionMetadata[] {
+FlowQuery.listFunctions = function (options?: {
+    category?: string;
+    asyncOnly?: boolean;
+    syncOnly?: boolean;
+}): FunctionMetadata[] {
     return FunctionFactory.listFunctions(options);
 };
 
 /**
  * Get metadata for a specific function.
- * 
+ *
  * @param name - The function name
  * @returns Function metadata or undefined
  */
-FlowQuery.getFunctionMetadata = function(name: string): FunctionMetadata | undefined {
+FlowQuery.getFunctionMetadata = function (name: string): FunctionMetadata | undefined {
     return FunctionFactory.getMetadata(name);
 };
 
@@ -40,4 +43,4 @@ FlowQuery.getFunctionMetadata = function(name: string): FunctionMetadata | undef
  */
 FlowQuery.Function = Function;
 
-export default FlowQuery;
+export default FlowQuery;

package/src/index.node.ts

@@ -1,37 +1,40 @@
 /**
  * FlowQuery - A declarative query language for data processing pipelines.
- * 
+ *
  * This is the main entry point for the FlowQuery Node.js library usage.
- * 
+ *
  * @packageDocumentation
  */
-
-import {default as FlowQuery} from "./compute/runner";
+import { default as FlowQuery } from "./compute/flowquery";
+import Function from "./parsing/functions/function";
 import FunctionFactory, { AsyncDataProvider } from "./parsing/functions/function_factory";
-import { 
-    FunctionMetadata, 
-    ParameterSchema, 
-    OutputSchema
+import {
+    FunctionMetadata,
+    OutputSchema,
+    ParameterSchema,
 } from "./parsing/functions/function_metadata";
-import Function from "./parsing/functions/function";
 
 /**
  * List all registered functions with their metadata.
- * 
+ *
  * @param options - Optional filter options
  * @returns Array of function metadata
  */
-FlowQuery.listFunctions = function(options?: { category?: string; asyncOnly?: boolean; syncOnly?: boolean }): FunctionMetadata[] {
+FlowQuery.listFunctions = function (options?: {
+    category?: string;
+    asyncOnly?: boolean;
+    syncOnly?: boolean;
+}): FunctionMetadata[] {
     return FunctionFactory.listFunctions(options);
 };
 
 /**
  * Get metadata for a specific function.
- * 
+ *
  * @param name - The function name
  * @returns Function metadata or undefined
  */
-FlowQuery.getFunctionMetadata = function(name: string): FunctionMetadata | undefined {
+FlowQuery.getFunctionMetadata = function (name: string): FunctionMetadata | undefined {
     return FunctionFactory.getMetadata(name);
 };
 
@@ -41,12 +44,12 @@ FlowQuery.getFunctionMetadata = function(name: string): FunctionMetadata | undef
 FlowQuery.Function = Function;
 
 export default FlowQuery;
-export { 
-    FlowQuery, 
-    Function, 
-    FunctionFactory, 
+export {
+    FlowQuery,
+    Function,
+    FunctionFactory,
     AsyncDataProvider,
     FunctionMetadata,
     ParameterSchema,
-    OutputSchema
+    OutputSchema,
 };

package/src/parsing/context.ts

@@ -43,6 +43,12 @@ class Context {
     public containsType(type: new (...args: any[]) => ASTNode): boolean {
         return this.nodes.some((v) => v instanceof type);
     }
+
+    public clone(): Context {
+        const newContext = new Context();
+        newContext.nodes = [...this.nodes];
+        return newContext;
+    }
 }
 
 export default Context;

package/src/parsing/expressions/operator.ts

@@ -43,7 +43,7 @@ abstract class Operator extends ASTNode {
     public get leftAssociative(): boolean {
         return this._leftAssociative;
     }
-    public abstract value(): number;
+    public abstract value(): any;
     public get lhs(): ASTNode {
         return this.getChildren()[0];
     }
@@ -56,8 +56,13 @@ class Add extends Operator {
     constructor() {
         super(1, true);
     }
-    public value(): number {
-        return this.lhs.value() + this.rhs.value();
+    public value(): any {
+        const l = this.lhs.value();
+        const r = this.rhs.value();
+        if (Array.isArray(l) && Array.isArray(r)) {
+            return [...l, ...r];
+        }
+        return l + r;
     }
 }
 

package/src/parsing/functions/function_factory.ts

@@ -27,6 +27,8 @@ import "./stringify";
 // Import built-in functions to ensure their @FunctionDef decorators run
 import "./sum";
 import "./to_json";
+import "./to_lower";
+import "./to_string";
 import "./type";
 
 // Re-export AsyncDataProvider for backwards compatibility

package/src/parsing/functions/to_lower.ts

@@ -0,0 +1,25 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Converts a string to lowercase",
+    category: "scalar",
+    parameters: [{ name: "text", description: "String to convert to lowercase", type: "string" }],
+    output: { description: "Lowercase string", type: "string", example: "hello world" },
+    examples: ["WITH 'Hello World' AS s RETURN toLower(s)", "WITH 'FOO' AS s RETURN toLower(s)"],
+})
+class ToLower extends Function {
+    constructor() {
+        super("tolower");
+        this._expectedParameterCount = 1;
+    }
+    public value(): any {
+        const val = this.getChildren()[0].value();
+        if (typeof val !== "string") {
+            throw new Error("Invalid argument for toLower function: expected a string");
+        }
+        return val.toLowerCase();
+    }
+}
+
+export default ToLower;

package/src/parsing/functions/to_string.ts

@@ -0,0 +1,32 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Converts a value to its string representation",
+    category: "scalar",
+    parameters: [{ name: "value", description: "Value to convert to a string", type: "any" }],
+    output: { description: "String representation of the value", type: "string", example: "42" },
+    examples: [
+        "WITH 42 AS n RETURN toString(n)",
+        "WITH true AS b RETURN toString(b)",
+        "WITH [1, 2, 3] AS arr RETURN toString(arr)",
+    ],
+})
+class ToString extends Function {
+    constructor() {
+        super("tostring");
+        this._expectedParameterCount = 1;
+    }
+    public value(): any {
+        const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return String(val);
+        }
+        if (typeof val === "object") {
+            return JSON.stringify(val);
+        }
+        return String(val);
+    }
+}
+
+export default ToString;

package/src/parsing/operations/match.ts

@@ -1,30 +1,53 @@
+import Node from "../../graph/node";
 import Pattern from "../../graph/pattern";
 import Patterns from "../../graph/patterns";
 import Operation from "./operation";
 
 class Match extends Operation {
     private _patterns: Patterns | null = null;
+    private _optional: boolean = false;
 
-    constructor(patterns: Pattern[] = []) {
+    constructor(patterns: Pattern[] = [], optional: boolean = false) {
         super();
         this._patterns = new Patterns(patterns);
+        this._optional = optional;
     }
     public get patterns(): Pattern[] {
         return this._patterns ? this._patterns.patterns : [];
     }
+    public get optional(): boolean {
+        return this._optional;
+    }
+    protected toString(): string {
+        return this._optional ? "OptionalMatch" : "Match";
+    }
     /**
      * Executes the match operation by chaining the patterns together.
      * After each pattern match, it continues to the next operation in the chain.
+     * If optional and no match is found, continues with null values.
      * @return Promise<void>
      */
     public async run(): Promise<void> {
         await this._patterns!.initialize();
+        let matched = false;
         this._patterns!.toDoNext = async () => {
+            matched = true;
             // Continue to the next operation after all patterns are matched
             await this.next?.run();
         };
         // Kick off the graph pattern traversal
         await this._patterns!.traverse();
+        // For OPTIONAL MATCH: if nothing matched, continue with null values
+        if (!matched && this._optional) {
+            for (const pattern of this._patterns!.patterns) {
+                for (const element of pattern.chain) {
+                    if (element instanceof Node) {
+                        element.setValue(null!);
+                    }
+                }
+            }
+            await this.next?.run();
+        }
     }
 }
 

package/src/parsing/operations/union.ts

@@ -0,0 +1,114 @@
+import Operation from "./operation";
+
+/**
+ * Represents a UNION operation that combines results from two sub-queries.
+ *
+ * UNION merges the results of a left and right query pipeline, removing
+ * duplicate rows. Both sides must return the same column names.
+ *
+ * @example
+ * ```
+ * WITH 1 AS x RETURN x
+ * UNION
+ * WITH 2 AS x RETURN x
+ * // Results: [{x: 1}, {x: 2}]
+ * ```
+ */
+class Union extends Operation {
+    protected _left: Operation | null = null;
+    protected _right: Operation | null = null;
+    protected _results: Record<string, any>[] = [];
+
+    public set left(operation: Operation) {
+        this._left = operation;
+    }
+    public get left(): Operation {
+        if (!this._left) {
+            throw new Error("Left operation is not set");
+        }
+        return this._left;
+    }
+    public set right(operation: Operation) {
+        this._right = operation;
+    }
+    public get right(): Operation {
+        if (!this._right) {
+            throw new Error("Right operation is not set");
+        }
+        return this._right;
+    }
+
+    private lastInChain(operation: Operation): Operation {
+        let current = operation;
+        while (current.next) {
+            current = current.next;
+        }
+        return current;
+    }
+
+    public async initialize(): Promise<void> {
+        this._results = [];
+        await this.next?.initialize();
+    }
+
+    public async run(): Promise<void> {
+        // Execute left pipeline
+        await this._left!.initialize();
+        await this._left!.run();
+        await this._left!.finish();
+        const leftLast = this.lastInChain(this._left!);
+        const leftResults: Record<string, any>[] = leftLast.results;
+
+        // Execute right pipeline
+        await this._right!.initialize();
+        await this._right!.run();
+        await this._right!.finish();
+        const rightLast = this.lastInChain(this._right!);
+        const rightResults: Record<string, any>[] = rightLast.results;
+
+        // Validate column names match
+        if (leftResults.length > 0 && rightResults.length > 0) {
+            const leftKeys = Object.keys(leftResults[0]).sort().join(",");
+            const rightKeys = Object.keys(rightResults[0]).sort().join(",");
+            if (leftKeys !== rightKeys) {
+                throw new Error(
+                    "All sub queries in a UNION must have the same return column names"
+                );
+            }
+        }
+
+        // Combine results
+        this._results = this.combine(leftResults, rightResults);
+    }
+
+    /**
+     * Combines results from left and right pipelines.
+     * UNION removes duplicates; subclass UnionAll overrides to keep all rows.
+     */
+    protected combine(
+        left: Record<string, any>[],
+        right: Record<string, any>[]
+    ): Record<string, any>[] {
+        const combined = [...left];
+        for (const row of right) {
+            const serialized = JSON.stringify(row);
+            const isDuplicate = combined.some(
+                (existing) => JSON.stringify(existing) === serialized
+            );
+            if (!isDuplicate) {
+                combined.push(row);
+            }
+        }
+        return combined;
+    }
+
+    public async finish(): Promise<void> {
+        await this.next?.finish();
+    }
+
+    public get results(): Record<string, any>[] {
+        return this._results;
+    }
+}
+
+export default Union;

package/src/parsing/operations/union_all.ts

@@ -0,0 +1,16 @@
+import Union from "./union";
+
+/**
+ * Represents a UNION ALL operation that concatenates results from two sub-queries
+ * without removing duplicates.
+ */
+class UnionAll extends Union {
+    protected combine(
+        left: Record<string, any>[],
+        right: Record<string, any>[]
+    ): Record<string, any>[] {
+        return [...left, ...right];
+    }
+}
+
+export default UnionAll;