flowquery 1.0.43 → 1.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowquery",
-  "version": "1.0.43",
+  "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/functions/join.ts

@@ -1,6 +1,6 @@
 import ASTNode from "../ast_node";
-import Function from "./function";
 import String from "../expressions/string";
+import Function from "./function";
 import { FunctionDef } from "./function_metadata";
 
 @FunctionDef({
@@ -8,10 +8,10 @@ import { FunctionDef } from "./function_metadata";
     category: "scalar",
     parameters: [
         { name: "array", description: "Array of values to join", type: "array" },
-        { name: "delimiter", description: "Delimiter to join with", type: "string" }
+        { name: "delimiter", description: "Delimiter to join with", type: "string" },
     ],
     output: { description: "Joined string", type: "string", example: "a,b,c" },
-    examples: ["WITH ['a', 'b', 'c'] AS arr RETURN join(arr, ',')"]
+    examples: ["WITH ['a', 'b', 'c'] AS arr RETURN join(arr, ',')"],
 })
 class Join extends Function {
     constructor() {
@@ -19,7 +19,7 @@ class Join extends Function {
         this._expectedParameterCount = 2;
     }
     public set parameters(nodes: ASTNode[]) {
-        if(nodes.length === 1) {
+        if (nodes.length === 1) {
             nodes.push(new String(""));
         }
         super.parameters = nodes;
@@ -27,6 +27,9 @@ class Join extends Function {
     public value(): any {
         const array = this.getChildren()[0].value();
         const delimiter = this.getChildren()[1].value();
+        if (array === null || array === undefined) {
+            return null;
+        }
         if (!Array.isArray(array) || typeof delimiter !== "string") {
             throw new Error("Invalid arguments for join function");
         }
@@ -34,4 +37,4 @@ class Join extends Function {
     }
 }
 
-export default Join;
+export default Join;

package/src/parsing/functions/keys.ts

@@ -4,11 +4,9 @@ import { FunctionDef } from "./function_metadata";
 @FunctionDef({
     description: "Returns the keys of an object (associative array) as an array",
     category: "scalar",
-    parameters: [
-        { name: "object", description: "Object to extract keys from", type: "object" }
-    ],
+    parameters: [{ name: "object", description: "Object to extract keys from", type: "object" }],
     output: { description: "Array of keys", type: "array", example: "['name', 'age']" },
-    examples: ["WITH { name: 'Alice', age: 30 } AS obj RETURN keys(obj)"]
+    examples: ["WITH { name: 'Alice', age: 30 } AS obj RETURN keys(obj)"],
 })
 class Keys extends Function {
     constructor() {
@@ -19,7 +17,7 @@ class Keys extends Function {
     public value(): any {
         const obj = this.getChildren()[0].value();
         if (obj === null || obj === undefined) {
-            return [];
+            return null;
         }
         if (typeof obj !== "object" || Array.isArray(obj)) {
             throw new Error("keys() expects an object, not an array or primitive");
@@ -28,4 +26,4 @@ class Keys extends Function {
     }
 }
 
-export default Keys;
+export default Keys;

package/src/parsing/functions/range.ts

@@ -6,10 +6,15 @@ import { FunctionDef } from "./function_metadata";
     category: "scalar",
     parameters: [
         { name: "start", description: "Starting number (inclusive)", type: "number" },
-        { name: "end", description: "Ending number (inclusive)", type: "number" }
+        { name: "end", description: "Ending number (inclusive)", type: "number" },
     ],
-    output: { description: "Array of integers from start to end", type: "array", items: { type: "number" }, example: [1, 2, 3, 4, 5] },
-    examples: ["WITH range(1, 5) AS nums RETURN nums"]
+    output: {
+        description: "Array of integers from start to end",
+        type: "array",
+        items: { type: "number" },
+        example: [1, 2, 3, 4, 5],
+    },
+    examples: ["WITH range(1, 5) AS nums RETURN nums"],
 })
 class Range extends Function {
     constructor() {
@@ -19,6 +24,9 @@ class Range extends Function {
     public value(): any {
         const start = this.getChildren()[0].value();
         const end = this.getChildren()[1].value();
+        if (start === null || start === undefined || end === null || end === undefined) {
+            return null;
+        }
         if (typeof start !== "number" || typeof end !== "number") {
             throw new Error("Invalid arguments for range function");
         }
@@ -26,4 +34,4 @@ class Range extends Function {
     }
 }
 
-export default Range;
+export default Range;

package/src/parsing/functions/replace.ts

@@ -7,10 +7,10 @@ import { FunctionDef } from "./function_metadata";
     parameters: [
         { name: "text", description: "Source string", type: "string" },
         { name: "pattern", description: "Pattern to find", type: "string" },
-        { name: "replacement", description: "Replacement string", type: "string" }
+        { name: "replacement", description: "Replacement string", type: "string" },
     ],
     output: { description: "String with replacements", type: "string", example: "hello world" },
-    examples: ["WITH 'hello there' AS s RETURN replace(s, 'there', 'world')"]
+    examples: ["WITH 'hello there' AS s RETURN replace(s, 'there', 'world')"],
 })
 class Replace extends Function {
     constructor() {
@@ -21,11 +21,18 @@ class Replace extends Function {
         const str = this.getChildren()[0].value();
         const search = this.getChildren()[1].value();
         const replacement = this.getChildren()[2].value();
-        if (typeof str !== "string" || typeof search !== "string" || typeof replacement !== "string") {
+        if (str === null || str === undefined) {
+            return null;
+        }
+        if (
+            typeof str !== "string" ||
+            typeof search !== "string" ||
+            typeof replacement !== "string"
+        ) {
             throw new Error("Invalid arguments for replace function");
         }
         return str.replace(new RegExp(search, "g"), replacement);
     }
 }
 
-export default Replace;
+export default Replace;

package/src/parsing/functions/round.ts

@@ -4,11 +4,9 @@ import { FunctionDef } from "./function_metadata";
 @FunctionDef({
     description: "Rounds a number to the nearest integer",
     category: "scalar",
-    parameters: [
-        { name: "value", description: "Number to round", type: "number" }
-    ],
+    parameters: [{ name: "value", description: "Number to round", type: "number" }],
     output: { description: "Rounded integer", type: "number", example: 4 },
-    examples: ["WITH 3.7 AS n RETURN round(n)"]
+    examples: ["WITH 3.7 AS n RETURN round(n)"],
 })
 class Round extends Function {
     constructor() {
@@ -17,6 +15,9 @@ class Round extends Function {
     }
     public value(): any {
         const value = this.getChildren()[0].value();
+        if (value === null || value === undefined) {
+            return null;
+        }
         if (typeof value !== "number") {
             throw new Error("Invalid argument for round function");
         }
@@ -24,4 +25,4 @@ class Round extends Function {
     }
 }
 
-export default Round;
+export default Round;

package/src/parsing/functions/size.ts

@@ -4,11 +4,9 @@ import { FunctionDef } from "./function_metadata";
 @FunctionDef({
     description: "Returns the length of an array or string",
     category: "scalar",
-    parameters: [
-        { name: "value", description: "Array or string to measure", type: "array" }
-    ],
+    parameters: [{ name: "value", description: "Array or string to measure", type: "array" }],
     output: { description: "Length of the input", type: "number", example: 3 },
-    examples: ["WITH [1, 2, 3] AS arr RETURN size(arr)"]
+    examples: ["WITH [1, 2, 3] AS arr RETURN size(arr)"],
 })
 class Size extends Function {
     constructor() {
@@ -17,6 +15,9 @@ class Size extends Function {
     }
     public value(): any {
         const arr = this.getChildren()[0].value();
+        if (arr === null || arr === undefined) {
+            return null;
+        }
         if (!Array.isArray(arr)) {
             throw new Error("Invalid argument for size function");
         }
@@ -24,4 +25,4 @@ class Size extends Function {
     }
 }
 
-export default Size;
+export default Size;

package/src/parsing/functions/split.ts

@@ -1,6 +1,6 @@
 import ASTNode from "../ast_node";
-import Function from "./function";
 import String from "../expressions/string";
+import Function from "./function";
 import { FunctionDef } from "./function_metadata";
 
 @FunctionDef({
@@ -8,10 +8,15 @@ import { FunctionDef } from "./function_metadata";
     category: "scalar",
     parameters: [
         { name: "text", description: "String to split", type: "string" },
-        { name: "delimiter", description: "Delimiter to split by", type: "string" }
+        { name: "delimiter", description: "Delimiter to split by", type: "string" },
     ],
-    output: { description: "Array of string parts", type: "array", items: { type: "string" }, example: ["a", "b", "c"] },
-    examples: ["WITH 'a,b,c' AS s RETURN split(s, ',')"]
+    output: {
+        description: "Array of string parts",
+        type: "array",
+        items: { type: "string" },
+        example: ["a", "b", "c"],
+    },
+    examples: ["WITH 'a,b,c' AS s RETURN split(s, ',')"],
 })
 class Split extends Function {
     constructor() {
@@ -19,7 +24,7 @@ class Split extends Function {
         this._expectedParameterCount = 2;
     }
     public set parameters(nodes: ASTNode[]) {
-        if(nodes.length === 1) {
+        if (nodes.length === 1) {
             nodes.push(new String(""));
         }
         super.parameters = nodes;
@@ -27,6 +32,9 @@ class Split extends Function {
     public value(): any {
         const str = this.getChildren()[0].value();
         const delimiter = this.getChildren()[1].value();
+        if (str === null || str === undefined) {
+            return null;
+        }
         if (typeof str !== "string" || typeof delimiter !== "string") {
             throw new Error("Invalid arguments for split function");
         }
@@ -34,4 +42,4 @@ class Split extends Function {
     }
 }
 
-export default Split;
+export default Split;

package/src/parsing/functions/string_distance.ts

@@ -68,6 +68,9 @@ class StringDistance extends Function {
     public value(): any {
         const str1 = this.getChildren()[0].value();
         const str2 = this.getChildren()[1].value();
+        if (str1 === null || str1 === undefined || str2 === null || str2 === undefined) {
+            return null;
+        }
         if (typeof str1 !== "string" || typeof str2 !== "string") {
             throw new Error(
                 "Invalid arguments for string_distance function: both arguments must be strings"

package/src/parsing/functions/stringify.ts

@@ -1,16 +1,14 @@
 import ASTNode from "../ast_node";
-import Function from "./function";
 import Number from "../expressions/number";
+import Function from "./function";
 import { FunctionDef } from "./function_metadata";
 
 @FunctionDef({
     description: "Converts a value to its JSON string representation",
     category: "scalar",
-    parameters: [
-        { name: "value", description: "Value to stringify", type: "any" }
-    ],
-    output: { description: "JSON string", type: "string", example: "{\"a\":1}" },
-    examples: ["WITH {a: 1} AS obj RETURN stringify(obj)"]
+    parameters: [{ name: "value", description: "Value to stringify", type: "any" }],
+    output: { description: "JSON string", type: "string", example: '{"a":1}' },
+    examples: ["WITH {a: 1} AS obj RETURN stringify(obj)"],
 })
 class Stringify extends Function {
     constructor() {
@@ -18,7 +16,7 @@ class Stringify extends Function {
         this._expectedParameterCount = 2;
     }
     public set parameters(nodes: ASTNode[]) {
-        if(nodes.length === 1) {
+        if (nodes.length === 1) {
             nodes.push(new Number("3")); // Default to 3 if only one parameter is provided
         }
         super.parameters = nodes;
@@ -26,6 +24,9 @@ class Stringify extends Function {
     public value(): any {
         const value = this.getChildren()[0].value();
         const indent = parseInt(this.getChildren()[1].value());
+        if (value === null || value === undefined) {
+            return null;
+        }
         if (typeof value !== "object") {
             throw new Error("Invalid argument for stringify function");
         }
@@ -33,4 +34,4 @@ class Stringify extends Function {
     }
 }
 
-export default Stringify;
+export default Stringify;

package/src/parsing/functions/substring.ts

@@ -37,6 +37,9 @@ class Substring extends Function {
         const original = children[0].value();
         const start = children[1].value();
 
+        if (original === null || original === undefined) {
+            return null;
+        }
         if (typeof original !== "string") {
             throw new Error(
                 "Invalid argument for substring function: expected a string as the first argument"

package/src/parsing/functions/to_json.ts

@@ -4,11 +4,9 @@ import { FunctionDef } from "./function_metadata";
 @FunctionDef({
     description: "Parses a JSON string into an object",
     category: "scalar",
-    parameters: [
-        { name: "text", description: "JSON string to parse", type: "string" }
-    ],
+    parameters: [{ name: "text", description: "JSON string to parse", type: "string" }],
     output: { description: "Parsed object or array", type: "object", example: { a: 1 } },
-    examples: ["WITH '{\"a\": 1}' AS s RETURN tojson(s)"]
+    examples: ["WITH '{\"a\": 1}' AS s RETURN tojson(s)"],
 })
 class ToJson extends Function {
     constructor() {
@@ -17,6 +15,9 @@ class ToJson extends Function {
     }
     public value(): any {
         const str = this.getChildren()[0].value();
+        if (str === null || str === undefined) {
+            return null;
+        }
         if (typeof str !== "string") {
             throw new Error("Invalid arguments for tojson function");
         }
@@ -24,4 +25,4 @@ class ToJson extends Function {
     }
 }
 
-export default ToJson;
+export default ToJson;

package/src/parsing/functions/to_lower.ts

@@ -15,6 +15,9 @@ class ToLower extends Function {
     }
     public value(): any {
         const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return null;
+        }
         if (typeof val !== "string") {
             throw new Error("Invalid argument for toLower function: expected a string");
         }

package/src/parsing/functions/to_string.ts

@@ -20,7 +20,7 @@ class ToString extends Function {
     public value(): any {
         const val = this.getChildren()[0].value();
         if (val === null || val === undefined) {
-            return String(val);
+            return null;
         }
         if (typeof val === "object") {
             return JSON.stringify(val);

package/src/parsing/functions/trim.ts

@@ -15,6 +15,9 @@ class Trim extends Function {
     }
     public value(): any {
         const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return null;
+        }
         if (typeof val !== "string") {
             throw new Error("Invalid argument for trim function: expected a string");
         }

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();