flowquery 1.0.0

package/src/compute/runner.ts

@@ -0,0 +1,65 @@
+import Operation from "../parsing/operations/operation";
+import Parser from "../parsing/parser";
+
+/**
+ * Executes a FlowQuery statement and retrieves the results.
+ * 
+ * The Runner class parses a FlowQuery statement into an AST and executes it,
+ * managing the execution flow from the first operation to the final return statement.
+ * 
+ * @example
+ * ```typescript
+ * const runner = new Runner("WITH 1 as x RETURN x");
+ * await runner.run();
+ * console.log(runner.results); // [{ x: 1 }]
+ * ```
+ */
+class Runner {
+    private first: Operation;
+    private last: Operation;
+    
+    /**
+     * Creates a new Runner instance and parses the FlowQuery statement.
+     * 
+     * @param statement - The FlowQuery statement to execute
+     * @throws {Error} If the statement is null, empty, or contains syntax errors
+     */
+    constructor(statement: string | null = null) {
+        if(statement === null || statement === "") {
+            throw new Error("Statement cannot be null or empty");
+        }
+        const parser = new Parser();
+        const ast = parser.parse(statement);
+        this.first = ast.firstChild() as Operation;
+        this.last = ast.lastChild() as Operation;
+    }
+    
+    /**
+     * Executes the parsed FlowQuery statement.
+     * 
+     * @returns A promise that resolves when execution completes
+     * @throws {Error} If an error occurs during execution
+     */
+    public async run(): Promise<void> {
+        return new Promise<void>(async (resolve, reject) => {
+            try {
+                await this.first.run();
+                await this.first.finish();
+                resolve();
+            } catch (e) {
+                reject(e);
+            }
+        });
+    }
+    
+    /**
+     * Gets the results from the executed statement.
+     * 
+     * @returns The results from the last operation (typically a RETURN statement)
+     */
+    public get results(): any {
+        return this.last.results;
+    }
+}
+
+export default Runner;

package/src/index.browser.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+
+export default FlowQuery;

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * FlowQuery - A declarative query language for data processing pipelines.
+ * 
+ * This is the main entry point for the FlowQuery command-line interface.
+ * 
+ * @packageDocumentation
+ */
+
+import CommandLine from './io/command_line';
+
+const commandLine = new CommandLine();
+commandLine.loop();

package/src/io/command_line.ts

@@ -0,0 +1,74 @@
+import Runner from '../compute/runner';
+import * as readline from 'readline';
+
+/**
+ * Interactive command-line interface for FlowQuery.
+ * 
+ * Provides a REPL (Read-Eval-Print Loop) for executing FlowQuery statements
+ * and displaying results.
+ * 
+ * @example
+ * ```typescript
+ * const cli = new CommandLine();
+ * cli.loop(); // Starts interactive mode
+ * ```
+ */
+class CommandLine {
+    private rl: readline.Interface;
+
+    /**
+     * Creates a new CommandLine interface.
+     */
+    constructor() {
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+    }
+
+    /**
+     * Starts the interactive command loop.
+     * 
+     * Prompts the user for FlowQuery statements, executes them, and displays results.
+     * Type "exit" to quit the loop.
+     */
+    public loop() {
+        console.log('Welcome to FlowQuery! Type "exit" to quit.');
+        this.rl.setPrompt('> ');
+        this.rl.prompt();
+
+        this.rl.on('line', (input: string) => {
+            if (input === 'exit') {
+                this.rl.close();
+                return;
+            }
+            if(input.trim() === '') {
+                this.rl.prompt();
+                return;
+            }
+            try {
+                const runner = new Runner(input);
+                const promise = runner.run();
+                promise.then(
+                    () => {
+                        console.log(runner.results);
+                    }
+                );
+                promise.catch(
+                    (e) => console.error(e)
+                );
+                promise.finally(
+                    () => this.rl.prompt()
+                );
+            } catch (e) {
+                console.error(e);
+                this.rl.prompt();
+            }
+        }).on('close', () => {
+            console.log('Exiting FlowQuery.');
+            process.exit(0);
+        });
+    }
+}
+
+export default CommandLine;

package/src/parsing/alias.ts

@@ -0,0 +1,23 @@
+import ASTNode from "./ast_node";
+
+class Alias extends ASTNode {
+    private alias: string;
+    constructor(alias: string) {
+        super();
+        this.alias = alias;
+    }
+
+    public toString(): string {
+        return `Alias (${this.alias})`;
+    }
+
+    public getAlias(): string {
+        return this.alias;
+    }
+
+    public value(): string {
+        return this.alias;
+    }
+}
+
+export default Alias;

package/src/parsing/alias_option.ts

@@ -0,0 +1,5 @@
+export enum AliasOption {
+    NOT_ALLOWED = 0,
+    OPTIONAL = 1,
+    REQUIRED = 2,
+};

package/src/parsing/ast_node.ts

@@ -0,0 +1,153 @@
+/**
+ * Represents a node in the Abstract Syntax Tree (AST).
+ * 
+ * The AST is a tree representation of the parsed FlowQuery statement structure.
+ * Each node can have children and maintains a reference to its parent.
+ * 
+ * @example
+ * ```typescript
+ * const root = new ASTNode();
+ * const child = new ASTNode();
+ * root.addChild(child);
+ * ```
+ */
+class ASTNode {
+    protected _parent: ASTNode | null = null;
+    protected children: ASTNode[] = [];
+
+    /**
+     * Adds a child node to this node and sets the child's parent reference.
+     * 
+     * @param child - The child node to add
+     */
+    public addChild(child: ASTNode): void {
+        child._parent = this;
+        this.children.push(child);
+    }
+
+    /**
+     * Returns the first child node.
+     * 
+     * @returns The first child node
+     * @throws {Error} If the node has no children
+     */
+    public firstChild(): ASTNode {
+        if(this.children.length === 0) {
+            throw new Error('Expected child');
+        }
+        return this.children[0];
+    }
+
+    /**
+     * Returns the last child node.
+     * 
+     * @returns The last child node
+     * @throws {Error} If the node has no children
+     */
+    public lastChild(): ASTNode {
+        if(this.children.length === 0) {
+            throw new Error('Expected child');
+        }
+        return this.children[this.children.length - 1];
+    }
+
+    /**
+     * Returns all child nodes.
+     * 
+     * @returns Array of child nodes
+     */
+    public getChildren(): ASTNode[] {
+        return this.children;
+    }
+
+    /**
+     * Returns the number of child nodes.
+     * 
+     * @returns The count of children
+     */
+    public childCount(): number {
+        return this.children.length;
+    }
+
+    /**
+     * Returns the value of this node. Override in subclasses to provide specific values.
+     * 
+     * @returns The node's value, or null if not applicable
+     */
+    public value(): any {
+        return null;
+    }
+
+    /**
+     * Checks if this node represents an operator.
+     * 
+     * @returns True if this is an operator node, false otherwise
+     */
+    public isOperator(): boolean {
+        return false;
+    }
+
+    /**
+     * Checks if this node represents an operand (the opposite of an operator).
+     * 
+     * @returns True if this is an operand node, false otherwise
+     */
+    public isOperand(): boolean {
+        return !this.isOperator();
+    }
+
+    /**
+     * Gets the operator precedence for this node. Higher values indicate higher precedence.
+     * 
+     * @returns The precedence value (0 for non-operators)
+     */
+    public get precedence(): number {
+        return 0;
+    }
+
+    /**
+     * Indicates whether this operator is left-associative.
+     * 
+     * @returns True if left-associative, false otherwise
+     */
+    public get leftAssociative(): boolean {
+        return false;
+    }
+
+    /**
+     * Prints a string representation of the AST tree starting from this node.
+     * 
+     * @returns A formatted string showing the tree structure
+     */
+    public print(): string {
+        return Array.from(this._print(0)).join('\n');
+    }
+
+    /**
+     * Generator function for recursively printing the tree structure.
+     * 
+     * @param indent - The current indentation level
+     * @yields Lines representing each node in the tree
+     */
+    private *_print(indent: number): Generator<string> {
+        if(indent === 0) {
+            yield this.constructor.name;
+        } else if(indent > 0) {
+            yield '-'.repeat(indent) + ` ${this.toString()}`;
+        }
+        for(const child of this.children) {
+            yield* child._print(indent + 1);
+        }
+    }
+
+    /**
+     * Returns a string representation of this node. Override in subclasses for custom formatting.
+     * 
+     * @returns The string representation
+     */
+    protected toString(): string {
+        return this.constructor.name;
+    }
+}
+
+export default ASTNode;

package/src/parsing/base_parser.ts

@@ -0,0 +1,92 @@
+import Token from "../tokenization/token";
+import Tokenizer from "../tokenization/tokenizer";
+
+/**
+ * Base class for parsers providing common token manipulation functionality.
+ * 
+ * This class handles tokenization and provides utility methods for navigating
+ * through tokens, peeking ahead, and checking token sequences.
+ */
+class BaseParser {
+    private tokens: Token[] = <Token[]>[];
+    private tokenIndex: number = 0;
+
+    /**
+     * Tokenizes a statement and initializes the token array.
+     * 
+     * @param statement - The input statement to tokenize
+     */
+    protected tokenize(statement: string): void {
+        this.tokens = new Tokenizer(statement).tokenize();
+        this.tokenIndex = 0;
+    }
+
+    /**
+     * Advances to the next token in the sequence.
+     */
+    protected setNextToken(): void {
+        this.tokenIndex++;
+    }
+
+    /**
+     * Peeks at the next token without advancing the current position.
+     * 
+     * @returns The next token, or null if at the end of the token stream
+     */
+    protected peek(): Token | null {
+        if(this.tokenIndex + 1 >= this.tokens.length) {
+            return null;
+        }
+        return this.tokens[this.tokenIndex + 1];
+    }
+
+    /**
+     * Checks if a sequence of tokens appears ahead in the token stream.
+     * 
+     * @param tokens - The sequence of tokens to look for
+     * @param skipWhitespaceAndComments - Whether to skip whitespace and comments when matching
+     * @returns True if the token sequence is found ahead, false otherwise
+     */
+    protected ahead(tokens: Token[], skipWhitespaceAndComments: boolean = true): boolean {
+        let j = 0;
+        for(let i=this.tokenIndex; i<this.tokens.length; i++) {
+            if(skipWhitespaceAndComments && this.tokens[i].isWhitespaceOrComment()) {
+                continue;
+            }
+            if(!this.tokens[i].equals(tokens[j])) {
+                return false;
+            }
+            j++;
+            if(j === tokens.length) {
+                break;
+            }
+        }
+        return j === tokens.length;
+    }
+
+    /**
+     * Gets the current token.
+     * 
+     * @returns The current token, or EOF if at the end
+     */
+    protected get token(): Token {
+        if(this.tokenIndex >= this.tokens.length) {
+            return Token.EOF;
+        }
+        return this.tokens[this.tokenIndex];
+    }
+
+    /**
+     * Gets the previous token.
+     * 
+     * @returns The previous token, or EOF if at the beginning
+     */
+    protected get previousToken(): Token {
+        if(this.tokenIndex - 1 < 0) {
+            return Token.EOF;
+        }
+        return this.tokens[this.tokenIndex - 1];
+    }
+}
+
+export default BaseParser;

package/src/parsing/components/csv.ts

@@ -0,0 +1,9 @@
+import ASTNode from "../ast_node";
+
+class CSV extends ASTNode {
+  constructor() {
+    super();
+  }
+}
+
+export default CSV;

package/src/parsing/components/from.ts

@@ -0,0 +1,12 @@
+import ASTNode from "../ast_node";
+
+class From extends ASTNode {
+  constructor() {
+    super()
+  }
+  public value(): string {
+    return this.children[0].value();
+  }
+}
+
+export default From;

package/src/parsing/components/headers.ts

@@ -0,0 +1,12 @@
+import ASTNode from "../ast_node";
+
+class Headers extends ASTNode {
+  constructor() {
+    super()
+  }
+  public value(): object {
+    return this.firstChild().value() as object || {};
+  }
+}
+
+export default Headers;

package/src/parsing/components/json.ts

@@ -0,0 +1,9 @@
+import ASTNode from "../ast_node";
+
+class JSON extends ASTNode {
+  constructor() {
+    super();
+  }
+}
+
+export default JSON;

package/src/parsing/components/null.ts

@@ -0,0 +1,9 @@
+import ASTNode from "../ast_node";
+
+class Null extends ASTNode {
+    constructor() {
+        super();
+    }
+}
+
+export default Null;

package/src/parsing/components/post.ts

@@ -0,0 +1,9 @@
+import ASTNode from "../ast_node";
+
+class Post extends ASTNode {
+    constructor() {
+        super()
+    }
+}
+
+export default Post;

package/src/parsing/components/text.ts

@@ -0,0 +1,9 @@
+import ASTNode from "../ast_node";
+
+class Text extends ASTNode {
+  constructor() {
+    super();
+  }
+}
+
+export default Text;

package/src/parsing/context.ts

@@ -0,0 +1,48 @@
+import ASTNode from "./ast_node";
+
+/**
+ * Maintains a stack of AST nodes to track parsing context.
+ * 
+ * Used during parsing to maintain the current context and check for specific node types
+ * in the parsing hierarchy, which helps with context-sensitive parsing decisions.
+ * 
+ * @example
+ * ```typescript
+ * const context = new Context();
+ * context.push(node);
+ * const hasReturn = context.containsType(Return);
+ * ```
+ */
+class Context {
+    private stack: ASTNode[] = [];
+    
+    /**
+     * Pushes a node onto the context stack.
+     * 
+     * @param node - The AST node to push
+     */
+    public push(node: ASTNode): void {
+        this.stack.push(node);
+    }
+    
+    /**
+     * Pops the top node from the context stack.
+     * 
+     * @returns The popped node, or undefined if the stack is empty
+     */
+    public pop(): ASTNode | undefined {
+        return this.stack.pop();
+    }
+    
+    /**
+     * Checks if the stack contains a node of the specified type.
+     * 
+     * @param type - The constructor of the node type to search for
+     * @returns True if a node of the specified type is found in the stack, false otherwise
+     */
+    public containsType(type: new (...args: any[]) => ASTNode): boolean {
+        return this.stack.some((v) => v instanceof type);
+    }
+}
+
+export default Context;

package/src/parsing/data_structures/associative_array.ts

@@ -0,0 +1,43 @@
+import ASTNode from "../ast_node";
+import KeyValuePair from "./key_value_pair";
+
+/**
+ * Represents an associative array (object/dictionary) in the AST.
+ * 
+ * Associative arrays map string keys to values, similar to JSON objects.
+ * 
+ * @example
+ * ```typescript
+ * // For { name: "Alice", age: 30 }
+ * const obj = new AssociativeArray();
+ * obj.addKeyValue(new KeyValuePair("name", nameExpr));
+ * obj.addKeyValue(new KeyValuePair("age", ageExpr));
+ * ```
+ */
+class AssociativeArray extends ASTNode {
+    /**
+     * Adds a key-value pair to the associative array.
+     * 
+     * @param keyValuePair - The key-value pair to add
+     */
+    public addKeyValue(keyValuePair: KeyValuePair): void {
+        this.addChild(keyValuePair);
+    }
+
+    public toString(): string {
+        return 'AssociativeArray';
+    }
+    private *_value(): Iterable<Record<PropertyKey, any>> {
+        for(const child of this.children) {
+            const key_value = child as KeyValuePair;
+            yield {
+                [key_value.key]: key_value._value
+            };
+        }
+    }
+    public value(): Record<string, any> {
+        return Object.assign({}, ...this._value());
+    }
+}
+
+export default AssociativeArray;

package/src/parsing/data_structures/json_array.ts

@@ -0,0 +1,31 @@
+import ASTNode from "../ast_node";
+
+/**
+ * Represents a JSON array in the AST.
+ * 
+ * JSON arrays are ordered collections of values.
+ * 
+ * @example
+ * ```typescript
+ * // For [1, 2, 3]
+ * const arr = new JSONArray();
+ * arr.addValue(new Number("1"));
+ * arr.addValue(new Number("2"));
+ * arr.addValue(new Number("3"));
+ * ```
+ */
+class JSONArray extends ASTNode {
+    /**
+     * Adds a value to the array.
+     * 
+     * @param value - The AST node representing the value to add
+     */
+    public addValue(value: ASTNode): void {
+        this.addChild(value);
+    }
+    public value(): any[] {
+        return this.children.map(child => child.value());
+    }
+}
+
+export default JSONArray;

package/src/parsing/data_structures/key_value_pair.ts

@@ -0,0 +1,37 @@
+import ASTNode from "../ast_node";
+import String from "../expressions/string";
+
+/**
+ * Represents a key-value pair in an associative array.
+ * 
+ * Used to build object literals in FlowQuery.
+ * 
+ * @example
+ * ```typescript
+ * const kvp = new KeyValuePair("name", new String("Alice"));
+ * ```
+ */
+class KeyValuePair extends ASTNode {
+    /**
+     * Creates a new key-value pair.
+     * 
+     * @param key - The key string
+     * @param value - The AST node representing the value
+     */
+    constructor(key: string, value: ASTNode) {
+        super();
+        this.addChild(new String(key));
+        this.addChild(value);
+    }
+    public get key(): string {
+        return this.children[0].value();
+    }
+    public get _value(): any {
+        return this.children[1].value();
+    }
+    public toString(): string {
+        return `KeyValuePair`;
+    }
+}
+
+export default KeyValuePair;