flowquery 1.0.0

package/src/parsing/data_structures/lookup.ts

@@ -0,0 +1,40 @@
+import ASTNode from "../ast_node";
+
+/**
+ * Represents a lookup operation (array/object indexing) in the AST.
+ * 
+ * Lookups access elements from arrays or properties from objects using an index or key.
+ * 
+ * @example
+ * ```typescript
+ * // For array[0] or obj.property or obj["key"]
+ * const lookup = new Lookup();
+ * lookup.variable = arrayOrObjNode;
+ * lookup.index = indexNode;
+ * ```
+ */
+class Lookup extends ASTNode {
+    constructor() {
+        super();
+    }
+    public set index(index: ASTNode) {
+        this.addChild(index);
+    }
+    public get index(): ASTNode {
+        return this.children[0];
+    }
+    public set variable(variable: ASTNode) {
+        this.addChild(variable);
+    }
+    public get variable(): ASTNode {
+        return this.children[1];
+    }
+    public isOperand(): boolean {
+        return true;
+    }
+    public value(): any {
+        return this.variable.value()[this.index.value()];
+    }
+}
+
+export default Lookup;

package/src/parsing/data_structures/range_lookup.ts

@@ -0,0 +1,36 @@
+import ASTNode from "../ast_node";
+
+class RangeLookup extends ASTNode {
+    constructor() {
+        super();
+    }
+    public set from(from: ASTNode) {
+        this.addChild(from);
+    }
+    public get from(): ASTNode {
+        return this.children[0];
+    }
+    public set to(to: ASTNode) {
+        this.addChild(to);
+    }
+    public get to(): ASTNode {
+        return this.children[1];
+    }
+    public set variable(variable: ASTNode) {
+        this.addChild(variable);
+    }
+    public get variable(): ASTNode {
+        return this.children[2];
+    }
+    public isOperand(): boolean {
+        return true;
+    }
+    public value(): any {
+        const array: any[] = this.variable.value();
+        const from = this.from.value() || 0;
+        const to = this.to.value() || array.length;
+        return this.variable.value().slice(from, to);
+    }
+}
+
+export default RangeLookup;

package/src/parsing/expressions/expression.ts

@@ -0,0 +1,142 @@
+import ASTNode from "../ast_node";
+import AggregateFunction from "../functions/aggregate_function";
+import Reference from "./reference";
+
+/**
+ * Represents an expression in the FlowQuery AST.
+ * 
+ * Expressions are built using the Shunting Yard algorithm to handle operator
+ * precedence and associativity. They can contain operands (numbers, strings, identifiers)
+ * and operators (arithmetic, logical, comparison).
+ * 
+ * @example
+ * ```typescript
+ * const expr = new Expression();
+ * expr.addNode(numberNode);
+ * expr.addNode(plusOperator);
+ * expr.addNode(anotherNumberNode);
+ * expr.finish();
+ * ```
+ */
+class Expression extends ASTNode {
+    private operators: ASTNode[] = <ASTNode[]>[];
+    private output: ASTNode[] = <ASTNode[]>[];
+    private _alias: string | null = null;
+    private _overridden: any | null = null;
+    private _reducers: AggregateFunction[] | null = null;
+
+    /**
+     * Adds a node (operand or operator) to the expression.
+     * 
+     * Uses the Shunting Yard algorithm to maintain correct operator precedence.
+     * 
+     * @param node - The AST node to add (operand or operator)
+     */
+    public addNode(node: ASTNode): void {
+        /* Implements the Shunting Yard algorithm */
+        if(node.isOperand()) {
+            this.output.push(node);
+        } else if(node.isOperator()) {
+            const operator1: ASTNode = node;
+            while(this.operators.length > 0) {
+                let operator2 = this.operators[this.operators.length - 1];
+                if(
+                    operator2.precedence > operator1.precedence ||
+                    (operator2.precedence === operator1.precedence && operator1.leftAssociative)
+                ) {
+                    this.output.push(operator2);
+                    this.operators.pop();
+                } else {
+                    break;
+                }
+            }
+            this.operators.push(operator1);
+        }
+    }
+
+    /**
+     * Finalizes the expression by converting it to a tree structure.
+     * 
+     * Should be called after all nodes have been added.
+     */
+    public finish(): void {
+        let last: ASTNode | undefined;
+        while(last = this.operators.pop()) {
+            this.output.push(last);
+        };
+        this.addChild(this.toTree());
+    }
+
+    private toTree(): ASTNode {
+        const node = this.output.pop() || new ASTNode();
+        if(node.isOperator()) {
+            const rhs = this.toTree();
+            const lhs = this.toTree();
+            node.addChild(lhs);
+            node.addChild(rhs);
+        } 
+        return node;
+    }
+
+    public nodesAdded(): boolean {
+        return this.operators.length > 0 || this.output.length > 0;
+    }
+
+    public value(): any {
+        if(this._overridden !== null) {
+            return this._overridden;
+        }
+        if(this.childCount() !== 1) {
+            throw new Error('Expected one child');
+        }
+        return this.children[0].value();
+    }
+
+    public setAlias(alias: string): void {
+        this._alias = alias;
+    }
+
+    public set alias(alias: string) {
+        this._alias = alias;
+    }
+
+    public get alias(): string | null {
+        if(this.firstChild() instanceof Reference && this._alias === null) {
+            return (<Reference>this.firstChild()).identifier;
+        }
+        return this._alias;
+    }
+
+    public toString(): string {
+        if(this._alias !== null) {
+            return `Expression (${this._alias})`;
+        } else {
+            return 'Expression';
+        }
+    }
+    public reducers(): AggregateFunction[] {
+        if(this._reducers === null) {
+            this._reducers = [...this._extract_reducers()];
+        }
+        return this._reducers;
+    }
+    private *_extract_reducers(node: ASTNode = this): Generator<AggregateFunction> {
+        if(node instanceof AggregateFunction) {
+            yield node;
+        }
+        for(const child of node.getChildren()) {
+            yield* this._extract_reducers(child);
+        }
+    }
+    public mappable(): boolean {
+        return this.reducers().length === 0;
+    }
+    public has_reducers(): boolean {
+        return this.reducers().length > 0;
+    }
+    public set overridden(value: any) {
+        this._overridden = value;
+    }
+}
+
+export default Expression;

package/src/parsing/expressions/f_string.ts

@@ -0,0 +1,26 @@
+import ASTNode from "../ast_node";
+import Expression from "./expression";
+
+/**
+ * Represents a formatted string (f-string) in the AST.
+ * 
+ * F-strings allow embedding expressions within string literals.
+ * Child nodes represent the parts of the f-string (literal strings and expressions).
+ * 
+ * @example
+ * ```typescript
+ * // For f"Hello {name}!"
+ * const fstr = new FString();
+ * fstr.addChild(new String("Hello "));
+ * fstr.addChild(nameExpression);
+ * fstr.addChild(new String("!"));
+ * ```
+ */
+class FString extends ASTNode {
+    public value(): string {
+        const parts: Expression[] = this.getChildren() as Array<Expression>;
+        return parts.map((part) => part.value()).join("");
+    }
+}
+
+export default FString;

package/src/parsing/expressions/identifier.ts

@@ -0,0 +1,22 @@
+import String from "./string";
+
+/**
+ * Represents an identifier in the AST.
+ * 
+ * Identifiers are used for variable names, property names, and similar constructs.
+ * 
+ * @example
+ * ```typescript
+ * const id = new Identifier("myVariable");
+ * ```
+ */
+class Identifier extends String {
+    public toString(): string {
+        return `Identifier (${this._value})`;
+    }
+    public value(): any {
+        return super.value();
+    }
+}
+
+export default Identifier;

package/src/parsing/expressions/number.ts

@@ -0,0 +1,40 @@
+import ASTNode from "../ast_node";
+
+/**
+ * Represents a numeric literal in the AST.
+ * 
+ * Parses string representations of numbers into integer or float values.
+ * 
+ * @example
+ * ```typescript
+ * const num = new Number("42");
+ * console.log(num.value()); // 42
+ * ```
+ */
+class Number extends ASTNode {
+    private _value: number;
+
+    /**
+     * Creates a new Number node by parsing the string value.
+     * 
+     * @param value - The string representation of the number
+     */
+    constructor(value: string) {
+        super();
+        if(value.indexOf('.') !== -1) {
+            this._value = parseFloat(value);
+        } else {
+            this._value = parseInt(value);
+        }
+    }
+
+    public value(): number {
+        return this._value;
+    }
+
+    protected toString(): string {
+        return `${this.constructor.name} (${this._value})`;
+    }
+}
+
+export default Number;

package/src/parsing/expressions/operator.ts

@@ -0,0 +1,179 @@
+import ASTNode from "../ast_node";
+
+abstract class Operator extends ASTNode {
+    private _precedence: number = 0;
+    private _leftAssociative: boolean = true;
+
+    constructor(precedence: number, leftAssociative: boolean) {
+        super();
+        this._precedence = precedence;
+        this._leftAssociative = leftAssociative;
+    }
+
+    public isOperator(): boolean {
+        return true;
+    }
+
+    public get precedence(): number {
+        return this._precedence;
+    }
+    public get leftAssociative(): boolean {
+        return this._leftAssociative;
+    }
+    public abstract value(): number;
+    public get lhs(): ASTNode {
+        return this.getChildren()[0];
+    }
+    public get rhs(): ASTNode {
+        return this.getChildren()[1];
+    }
+}
+
+class Add extends Operator {
+    constructor() {
+        super(1, true);
+    }
+    public value(): number {
+        return this.lhs.value() + this.rhs.value();
+    }
+}
+
+class Subtract extends Operator {
+    constructor() {
+        super(1, true);
+    }
+    public value(): number {
+        return this.lhs.value() - this.rhs.value();
+    }
+}
+
+class Multiply extends Operator {
+    constructor() {
+        super(2, true);
+    }
+    public value(): number {
+        return this.lhs.value() * this.rhs.value();
+    }
+}
+
+class Divide extends Operator {
+    constructor() {
+        super(2, true);
+    }
+    public value(): number {
+        return this.lhs.value() / this.rhs.value();
+    }
+}
+
+class Modulo extends Operator {
+    constructor() {
+        super(2, true);
+    }
+    public value(): number {
+        return this.lhs.value() % this.rhs.value();
+    }
+}
+
+class Power extends Operator {
+    constructor() {
+        super(3, false);
+    }
+    public value(): number {
+        return Math.pow(this.lhs.value(), this.rhs.value());
+    }
+}
+
+class Equals extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() === this.rhs.value() ? 1 : 0;
+    }
+}
+
+class NotEquals extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() !== this.rhs.value() ? 1 : 0;
+    }
+}
+
+class GreaterThan extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() > this.rhs.value() ? 1 : 0;
+    }
+}
+
+class LessThan extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() < this.rhs.value() ? 1 : 0;
+    }
+}
+
+class GreaterThanOrEqual extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() >= this.rhs.value() ? 1 : 0;
+    }
+}
+
+class LessThanOrEqual extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public value(): number {
+        return this.lhs.value() <= this.rhs.value() ? 1 : 0;
+    }
+}
+
+class And extends Operator {
+    constructor() {
+        super(-1, true);
+    }
+    public value(): number {
+        return this.lhs.value() && this.rhs.value() ? 1 : 0;
+    }
+}
+
+class Or extends Operator {
+    constructor() {
+        super(-1, true);
+    }
+    public value(): number {
+        return this.lhs.value() || this.rhs.value() ? 1 : 0;
+    }
+}
+
+class Not extends Operator {
+    constructor() {
+        super(0, true);
+    }
+    public isOperator(): boolean {
+        return false;
+    }
+    public value(): number {
+        return !this.lhs.value() ? 1 : 0;
+    }
+}
+
+class Is extends Operator {
+    constructor() {
+        super(-1, true);
+    }
+    public value(): number {
+        return this.lhs.value() === this.rhs.value() ? 1 : 0;
+    }
+}
+
+export { Operator, Add, Subtract, Multiply, Divide, Modulo, Power, Equals, NotEquals, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, And, Or, Not, Is };

package/src/parsing/expressions/reference.ts

@@ -0,0 +1,42 @@
+import ASTNode from "../ast_node";
+import Identifier from "./identifier";
+
+/**
+ * Represents a reference to a previously defined variable or expression.
+ * 
+ * References point to values defined earlier in the query (e.g., in WITH or LOAD statements).
+ * 
+ * @example
+ * ```typescript
+ * const ref = new Reference("myVar", previousNode);
+ * console.log(ref.value()); // Gets value from referred node
+ * ```
+ */
+class Reference extends Identifier {
+    private _referred: ASTNode | undefined = undefined;
+    
+    /**
+     * Creates a new Reference to a variable.
+     * 
+     * @param value - The identifier name
+     * @param referred - The node this reference points to (optional)
+     */
+    constructor(value: string, referred: ASTNode | undefined = undefined) {
+        super(value);
+        this._referred = referred;
+    }
+    public set referred(node: ASTNode) {
+        this._referred = node;
+    }
+    public toString(): string {
+        return `Reference (${this._value})`;
+    }
+    public value(): any {
+        return this._referred?.value();
+    }
+    public get identifier(): string {
+        return this._value;
+    }
+}
+
+export default Reference;

package/src/parsing/expressions/string.ts

@@ -0,0 +1,34 @@
+import ASTNode from "../ast_node";
+
+/**
+ * Represents a string literal in the AST.
+ * 
+ * @example
+ * ```typescript
+ * const str = new String("hello");
+ * console.log(str.value()); // "hello"
+ * ```
+ */
+class String extends ASTNode {
+    protected _value: string;
+
+    /**
+     * Creates a new String node with the given value.
+     * 
+     * @param value - The string value
+     */
+    constructor(value: string) {
+        super();
+        this._value = value;
+    }
+
+    public value(): string {
+        return this._value;
+    }
+
+    public toString(): string {
+        return `String (${this._value})`;
+    }
+}
+
+export default String;

package/src/parsing/functions/aggregate_function.ts

@@ -0,0 +1,58 @@
+import Function from "./function";
+import ReducerElement from "./reducer_element";
+
+/**
+ * Base class for aggregate functions that reduce multiple values to a single value.
+ * 
+ * Aggregate functions like SUM, AVG, and COLLECT process multiple input values
+ * and produce a single output. They cannot be nested within other aggregate functions.
+ * 
+ * @example
+ * ```typescript
+ * const sumFunc = new Sum();
+ * // Used in: RETURN SUM(values)
+ * ```
+ */
+class AggregateFunction extends Function {
+    private _overridden: any | null = null;
+    
+    /**
+     * Creates a new AggregateFunction with the given name.
+     * 
+     * @param name - The function name
+     */
+    constructor(name: string) {
+        super(name);
+    }
+    
+    /**
+     * Processes a value during the aggregation phase.
+     * 
+     * @param value - The element to aggregate
+     * @throws {Error} If not implemented by subclass
+     */
+    public reduce(value: ReducerElement): void {
+        throw new Error("Method not implemented.");
+    }
+    
+    /**
+     * Creates a reducer element for this aggregate function.
+     * 
+     * @returns A ReducerElement instance
+     * @throws {Error} If not implemented by subclass
+     */
+    public element(): ReducerElement {
+        throw new Error("Method not implemented.");
+    }
+    public get overridden(): any | null {
+        return this._overridden;
+    }
+    public set overridden(value: any | null) {
+        this._overridden = value;
+    }
+    public value(): any {
+        return this._overridden;
+    }
+}
+
+export default AggregateFunction;

package/src/parsing/functions/avg.ts

@@ -0,0 +1,37 @@
+import AggregateFunction from "./aggregate_function";
+import ASTNode from "../ast_node";
+import ReducerElement from "./reducer_element";
+
+class AvgReducerElement extends ReducerElement {
+    private _count: number = 0;
+    private _sum: number | null = null;
+    public get value(): number | null {
+        if(this._sum === null) {
+            return null;
+        }
+        return this._sum / this._count;
+    }
+    public set value(value: number) {
+        this._count += 1;
+        if(this._sum !== null) {
+            this._sum += value;
+        } else {
+            this._sum = value;
+        }
+    }
+}
+
+class Avg extends AggregateFunction {
+    constructor() {
+        super("avg");
+        this._expectedParameterCount = 1;
+    }
+    public reduce(element: AvgReducerElement): void {
+        element.value = this.firstChild().value();
+    }
+    public element(): AvgReducerElement {
+        return new AvgReducerElement();
+    }
+}
+
+export default Avg;

package/src/parsing/functions/collect.ts

@@ -0,0 +1,44 @@
+import AggregateFunction from "./aggregate_function";
+import ReducerElement from "./reducer_element";
+
+class CollectReducerElement extends ReducerElement {
+    private _value: any[] = [];
+    public get value(): any {
+        return this._value;
+    }
+    public set value(value: any) {
+        this._value.push(value);
+    }
+}
+
+class DistinctCollectReducerElement extends ReducerElement {
+    private _value: Map<any, any> = new Map();
+    public get value(): any {
+        return Array.from(this._value.values());
+    }
+    public set value(value: any) {
+        const key: string = JSON.stringify(value);
+        if (!this._value.has(key)) {
+            this._value.set(key, value);
+        }
+    }
+}
+
+class Collect extends AggregateFunction {
+    private _distinct: boolean = false;
+    constructor() {
+        super("collect");
+        this._expectedParameterCount = 1;
+    }
+    public reduce(element: CollectReducerElement): void {
+        element.value = this.firstChild().value();
+    }
+    public element(): CollectReducerElement | DistinctCollectReducerElement {
+        return this._distinct ? new DistinctCollectReducerElement() : new CollectReducerElement();
+    }
+    public set distinct(distinct: boolean) {
+        this._distinct = distinct;
+    }
+}
+
+export default Collect;