flowquery 1.0.44 → 1.0.45

package/package.json

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

package/src/parsing/operations/order_by.ts

@@ -1,8 +1,11 @@
+import Expression from "../expressions/expression";
+import Reference from "../expressions/reference";
 import Operation from "./operation";
 
 export interface SortField {
-    field: string;
     direction: "asc" | "desc";
+    /** The parsed expression to evaluate for this sort field. */
+    expression: Expression;
 }
 
 /**
@@ -11,14 +14,23 @@ export interface SortField {
  * Can be attached to a RETURN operation (sorting its results),
  * or used as a standalone accumulating operation after a non-aggregate WITH.
  *
+ * Supports both simple field references and arbitrary expressions:
  * @example
  * ```
  * RETURN x ORDER BY x DESC
+ * RETURN x ORDER BY toLower(x.name) ASC
+ * RETURN x ORDER BY string_distance(toLower(x.name), toLower('Thomas')) ASC
  * ```
  */
 class OrderBy extends Operation {
     private _fields: SortField[];
     private _results: Record<string, any>[] = [];
+    /**
+     * Parallel array of pre-computed sort-key tuples, one entry per
+     * accumulated result row.  Each inner array has one value per sort
+     * field, in the same order as `_fields`.
+     */
+    private _sortKeys: any[][] = [];
 
     constructor(fields: SortField[]) {
         super();
@@ -30,13 +42,50 @@ class OrderBy extends Operation {
     }
 
     /**
-     * Sorts an array of records according to the sort fields.
+     * Evaluates every sort-field expression against the current runtime
+     * context and stores the resulting values.  Must be called once per
+     * accumulated row (from `Return.run()`).
+     */
+    public captureSortKeys(): void {
+        this._sortKeys.push(this._fields.map((f) => f.expression.value()));
+    }
+
+    /**
+     * Sorts an array of records using the pre-computed sort keys captured
+     * during accumulation.  When no keys have been captured (e.g.
+     * aggregated returns), falls back to looking up simple reference
+     * identifiers in each record.
      */
     public sort(records: Record<string, any>[]): Record<string, any>[] {
-        return records.sort((a, b) => {
-            for (const { field, direction } of this._fields) {
-                const aVal = a[field];
-                const bVal = b[field];
+        const useKeys = this._sortKeys.length === records.length;
+        // Build an index array so we can sort records and keys together.
+        const indices = records.map((_, i) => i);
+        const keys = this._sortKeys;
+
+        // Pre-compute fallback field names for when sort keys aren't
+        // available (aggregated returns).  Simple references like `x`
+        // map to the column name; complex expressions have no fallback.
+        const fallbackFields: (string | null)[] = this._fields.map((f) => {
+            const root = f.expression.firstChild();
+            if (root instanceof Reference && f.expression.childCount() === 1) {
+                return (root as Reference).identifier;
+            }
+            return null;
+        });
+
+        indices.sort((ai, bi) => {
+            for (let f = 0; f < this._fields.length; f++) {
+                let aVal: any;
+                let bVal: any;
+                if (useKeys) {
+                    aVal = keys[ai][f];
+                    bVal = keys[bi][f];
+                } else if (fallbackFields[f] !== null) {
+                    aVal = records[ai][fallbackFields[f]!];
+                    bVal = records[bi][fallbackFields[f]!];
+                } else {
+                    continue;
+                }
                 let cmp = 0;
                 if (aVal == null && bVal == null) cmp = 0;
                 else if (aVal == null) cmp = -1;
@@ -44,11 +93,12 @@ class OrderBy extends Operation {
                 else if (aVal < bVal) cmp = -1;
                 else if (aVal > bVal) cmp = 1;
                 if (cmp !== 0) {
-                    return direction === "desc" ? -cmp : cmp;
+                    return this._fields[f].direction === "desc" ? -cmp : cmp;
                 }
             }
             return 0;
         });
+        return indices.map((i) => records[i]);
     }
 
     /**
@@ -64,6 +114,7 @@ class OrderBy extends Operation {
 
     public async initialize(): Promise<void> {
         this._results = [];
+        this._sortKeys = [];
         await this.next?.initialize();
     }
 

package/src/parsing/operations/return.ts

@@ -49,6 +49,10 @@ class Return extends Projection {
             const value: any = typeof raw === "object" && raw !== null ? structuredClone(raw) : raw;
             record.set(alias, value);
         }
+        // Capture sort-key values while expression bindings are still live.
+        if (this._orderBy !== null) {
+            this._orderBy.captureSortKeys();
+        }
         this._results.push(Object.fromEntries(record));
         if (this._orderBy === null && this._limit !== null) {
             this._limit.increment();

package/src/parsing/parser.ts

@@ -876,11 +876,10 @@ class Parser extends BaseParser {
         this.expectAndSkipWhitespaceAndComments();
         const fields: SortField[] = [];
         while (true) {
-            if (!this.token.isIdentifierOrKeyword()) {
-                throw new Error("Expected field name in ORDER BY");
+            const expression: Expression | null = this.parseExpression();
+            if (expression === null) {
+                throw new Error("Expected expression in ORDER BY");
             }
-            const field = this.token.value!;
-            this.setNextToken();
             this.skipWhitespaceAndComments();
             let direction: "asc" | "desc" = "asc";
             if (this.token.isAsc()) {
@@ -892,7 +891,7 @@ class Parser extends BaseParser {
                 this.setNextToken();
                 this.skipWhitespaceAndComments();
             }
-            fields.push({ field, direction });
+            fields.push({ direction, expression });
             if (this.token.isComma()) {
                 this.setNextToken();
                 this.skipWhitespaceAndComments();

package/tests/compute/runner.test.ts

@@ -4114,6 +4114,126 @@ test("Test order by with where", async () => {
     expect(results[4]).toEqual({ x: 3 });
 });
 
+test("Test order by with property access expression", async () => {
+    const runner = new Runner(`
+        unwind [{name: 'Charlie', age: 30}, {name: 'Alice', age: 25}, {name: 'Bob', age: 35}] as person
+        return person.name as name, person.age as age
+        order by person.name asc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ name: "Alice", age: 25 });
+    expect(results[1]).toEqual({ name: "Bob", age: 35 });
+    expect(results[2]).toEqual({ name: "Charlie", age: 30 });
+});
+
+test("Test order by with function expression", async () => {
+    const runner = new Runner(`
+        unwind ['BANANA', 'apple', 'Cherry'] as fruit
+        return fruit
+        order by toLower(fruit)
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ fruit: "apple" });
+    expect(results[1]).toEqual({ fruit: "BANANA" });
+    expect(results[2]).toEqual({ fruit: "Cherry" });
+});
+
+test("Test order by with function expression descending", async () => {
+    const runner = new Runner(`
+        unwind ['BANANA', 'apple', 'Cherry'] as fruit
+        return fruit
+        order by toLower(fruit) desc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ fruit: "Cherry" });
+    expect(results[1]).toEqual({ fruit: "BANANA" });
+    expect(results[2]).toEqual({ fruit: "apple" });
+});
+
+test("Test order by with nested function expression", async () => {
+    const runner = new Runner(`
+        unwind ['Alice', 'Bob', 'ALICE', 'bob'] as name
+        return name
+        order by string_distance(toLower(name), toLower('alice')) asc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(4);
+    // 'Alice' and 'ALICE' have distance 0 from 'alice', should come first
+    expect(results[0].name).toBe("Alice");
+    expect(results[1].name).toBe("ALICE");
+    // 'Bob' and 'bob' have higher distance from 'alice'
+    expect(results[2].name).toBe("Bob");
+    expect(results[3].name).toBe("bob");
+});
+
+test("Test order by with arithmetic expression", async () => {
+    const runner = new Runner(`
+        unwind [{a: 3, b: 1}, {a: 1, b: 5}, {a: 2, b: 2}] as item
+        return item.a as a, item.b as b
+        order by item.a + item.b asc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ a: 3, b: 1 }); // sum = 4
+    expect(results[1]).toEqual({ a: 2, b: 2 }); // sum = 4
+    expect(results[2]).toEqual({ a: 1, b: 5 }); // sum = 6
+});
+
+test("Test order by expression does not leak synthetic keys", async () => {
+    const runner = new Runner(`
+        unwind ['B', 'a', 'C'] as x
+        return x
+        order by toLower(x) asc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    // Results should only contain 'x', no __orderBy_ keys
+    for (const r of results) {
+        expect(Object.keys(r)).toEqual(["x"]);
+    }
+    expect(results[0]).toEqual({ x: "a" });
+    expect(results[1]).toEqual({ x: "B" });
+    expect(results[2]).toEqual({ x: "C" });
+});
+
+test("Test order by with expression and limit", async () => {
+    const runner = new Runner(`
+        unwind ['BANANA', 'apple', 'Cherry', 'date', 'ELDERBERRY'] as fruit
+        return fruit
+        order by toLower(fruit) asc
+        limit 3
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ fruit: "apple" });
+    expect(results[1]).toEqual({ fruit: "BANANA" });
+    expect(results[2]).toEqual({ fruit: "Cherry" });
+});
+
+test("Test order by with mixed simple and expression fields", async () => {
+    const runner = new Runner(`
+        unwind [{name: 'Alice', score: 3}, {name: 'Alice', score: 1}, {name: 'Bob', score: 2}] as item
+        return item.name as name, item.score as score
+        order by name asc, item.score desc
+    `);
+    await runner.run();
+    const results = runner.results;
+    expect(results.length).toBe(3);
+    expect(results[0]).toEqual({ name: "Alice", score: 3 }); // Alice, score 3 desc
+    expect(results[1]).toEqual({ name: "Alice", score: 1 }); // Alice, score 1 desc
+    expect(results[2]).toEqual({ name: "Bob", score: 2 }); // Bob
+});
+
 test("Test delete virtual node operation", async () => {
     const db = Database.getInstance();
     // Create a virtual node first

package/tests/parsing/parser.test.ts

@@ -1269,3 +1269,59 @@ test("OPTIONAL without MATCH throws error", () => {
     const parser = new Parser();
     expect(() => parser.parse("OPTIONAL RETURN 1")).toThrow("Expected MATCH after OPTIONAL");
 });
+
+// ORDER BY expression tests
+
+test("ORDER BY with simple identifier parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse("unwind [1, 2] as x return x order by x");
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with property access parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind [{name: 'Bob'}, {name: 'Alice'}] as person return person.name as name order by person.name asc"
+    );
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with function call parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind ['HELLO', 'WORLD'] as word return word order by toLower(word) asc"
+    );
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with nested function calls parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind ['Alice', 'Bob'] as name return name order by string_distance(toLower(name), toLower('alice')) asc"
+    );
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with arithmetic expression parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind [{a: 3, b: 1}, {a: 1, b: 5}] as item return item.a as a, item.b as b order by item.a + item.b desc"
+    );
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with multiple expression fields parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind [{a: 1, b: 2}] as item return item.a as a, item.b as b order by toLower(item.a) asc, item.b desc"
+    );
+    expect(ast).toBeDefined();
+});
+
+test("ORDER BY with expression and LIMIT parses correctly", () => {
+    const parser = new Parser();
+    const ast = parser.parse(
+        "unwind ['c', 'a', 'b'] as x return x order by toLower(x) asc limit 2"
+    );
+    expect(ast).toBeDefined();
+});