flowquery 1.0.35 → 1.0.37

package/package.json

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

package/src/parsing/data_structures/lookup.ts

@@ -2,9 +2,9 @@ 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"]
@@ -33,8 +33,12 @@ class Lookup extends ASTNode {
         return true;
     }
     public value(): any {
-        return this.variable.value()[this.index.value()];
+        const obj = this.variable.value();
+        if (obj === null || obj === undefined) {
+            return null;
+        }
+        return obj[this.index.value()];
     }
 }
 
-export default Lookup;
+export default Lookup;

package/src/parsing/functions/coalesce.ts

@@ -0,0 +1,49 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+/**
+ * Returns the first non-null value from a list of expressions.
+ *
+ * @example
+ * ```
+ * RETURN coalesce(null, null, 'hello', 'world')  // returns 'hello'
+ * MATCH (n) RETURN coalesce(n.nickname, n.name) AS displayName
+ * ```
+ */
+@FunctionDef({
+    description: "Returns the first non-null value from a list of expressions",
+    category: "scalar",
+    parameters: [
+        { name: "expressions", description: "Two or more expressions to evaluate", type: "any" },
+    ],
+    output: {
+        description: "The first non-null value, or null if all values are null",
+        type: "any",
+    },
+    examples: [
+        "RETURN coalesce(null, 'hello', 'world')",
+        "MATCH (n) RETURN coalesce(n.nickname, n.name) AS displayName",
+    ],
+})
+class Coalesce extends Function {
+    constructor() {
+        super("coalesce");
+        this._expectedParameterCount = null; // variable number of parameters
+    }
+
+    public value(): any {
+        const children = this.getChildren();
+        if (children.length === 0) {
+            throw new Error("coalesce() requires at least one argument");
+        }
+        for (const child of children) {
+            const val = child.value();
+            if (val !== null && val !== undefined) {
+                return val;
+            }
+        }
+        return null;
+    }
+}
+
+export default Coalesce;

package/src/parsing/functions/date.ts

@@ -0,0 +1,63 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+import { buildDateObject, parseTemporalArg } from "./temporal_utils";
+
+/**
+ * Returns a date value (no time component).
+ * When called with no arguments, returns the current date.
+ * When called with a string argument, parses it as an ISO 8601 date.
+ * When called with a map argument, constructs a date from components.
+ *
+ * @example
+ * ```
+ * RETURN date() AS today
+ * RETURN date('2025-06-15') AS d
+ * RETURN date({year: 2025, month: 6, day: 15}) AS d
+ * ```
+ */
+@FunctionDef({
+    description:
+        "Returns a date value. With no arguments returns the current date. " +
+        "Accepts an ISO 8601 date string or a map of components (year, month, day).",
+    category: "scalar",
+    parameters: [
+        {
+            name: "input",
+            description: "Optional. An ISO 8601 date string (YYYY-MM-DD) or a map of components.",
+            type: "string",
+            required: false,
+        },
+    ],
+    output: {
+        description:
+            "A date object with properties: year, month, day, " +
+            "epochMillis, dayOfWeek, dayOfYear, quarter, formatted",
+        type: "object",
+    },
+    examples: [
+        "RETURN date() AS today",
+        "RETURN date('2025-06-15') AS d",
+        "RETURN date({year: 2025, month: 6, day: 15}) AS d",
+        "WITH date() AS d RETURN d.year, d.month, d.dayOfWeek",
+    ],
+})
+class DateFunction extends Function {
+    constructor() {
+        super("date");
+        this._expectedParameterCount = null;
+    }
+
+    public value(): any {
+        const children = this.getChildren();
+        if (children.length > 1) {
+            throw new Error("date() accepts at most one argument");
+        }
+
+        const d: Date =
+            children.length === 1 ? parseTemporalArg(children[0].value(), "date") : new Date();
+
+        return buildDateObject(d);
+    }
+}
+
+export default DateFunction;

package/src/parsing/functions/datetime.ts

@@ -0,0 +1,63 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+import { buildDatetimeObject, parseTemporalArg } from "./temporal_utils";
+
+/**
+ * Returns a datetime value (date + time + timezone offset).
+ * When called with no arguments, returns the current UTC datetime.
+ * When called with a string argument, parses it as an ISO 8601 datetime.
+ * When called with a map argument, constructs a datetime from components.
+ *
+ * @example
+ * ```
+ * RETURN datetime() AS now
+ * RETURN datetime('2025-06-15T12:30:00Z') AS dt
+ * RETURN datetime({year: 2025, month: 6, day: 15}) AS dt
+ * ```
+ */
+@FunctionDef({
+    description:
+        "Returns a datetime value. With no arguments returns the current UTC datetime. " +
+        "Accepts an ISO 8601 string or a map of components (year, month, day, hour, minute, second, millisecond).",
+    category: "scalar",
+    parameters: [
+        {
+            name: "input",
+            description: "Optional. An ISO 8601 datetime string or a map of components.",
+            type: "string",
+            required: false,
+        },
+    ],
+    output: {
+        description:
+            "A datetime object with properties: year, month, day, hour, minute, second, millisecond, " +
+            "epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted",
+        type: "object",
+    },
+    examples: [
+        "RETURN datetime() AS now",
+        "RETURN datetime('2025-06-15T12:30:00Z') AS dt",
+        "RETURN datetime({year: 2025, month: 6, day: 15, hour: 12}) AS dt",
+        "WITH datetime() AS dt RETURN dt.year, dt.month, dt.day",
+    ],
+})
+class Datetime extends Function {
+    constructor() {
+        super("datetime");
+        this._expectedParameterCount = null;
+    }
+
+    public value(): any {
+        const children = this.getChildren();
+        if (children.length > 1) {
+            throw new Error("datetime() accepts at most one argument");
+        }
+
+        const d: Date =
+            children.length === 1 ? parseTemporalArg(children[0].value(), "datetime") : new Date();
+
+        return buildDatetimeObject(d, true);
+    }
+}
+
+export default Datetime;

package/src/parsing/functions/duration.ts

@@ -0,0 +1,143 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+/**
+ * Regex for ISO 8601 duration strings: P[nY][nM][nW][nD][T[nH][nM][nS]]
+ */
+const ISO_DURATION_REGEX =
+    /^P(?:(\d+(?:\.\d+)?)Y)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+
+function parseDurationString(s: string): Record<string, number> {
+    const match = s.match(ISO_DURATION_REGEX);
+    if (!match) {
+        throw new Error(`duration(): Invalid ISO 8601 duration string: '${s}'`);
+    }
+    return {
+        years: match[1] ? parseFloat(match[1]) : 0,
+        months: match[2] ? parseFloat(match[2]) : 0,
+        weeks: match[3] ? parseFloat(match[3]) : 0,
+        days: match[4] ? parseFloat(match[4]) : 0,
+        hours: match[5] ? parseFloat(match[5]) : 0,
+        minutes: match[6] ? parseFloat(match[6]) : 0,
+        seconds: match[7] ? parseFloat(match[7]) : 0,
+    };
+}
+
+function buildDurationObject(components: Record<string, number>): Record<string, any> {
+    const years = components.years || 0;
+    const months = components.months || 0;
+    const weeks = components.weeks || 0;
+    const days = components.days || 0;
+    const hours = components.hours || 0;
+    const minutes = components.minutes || 0;
+    const seconds = Math.floor(components.seconds || 0);
+    const fractionalSeconds = (components.seconds || 0) - seconds;
+
+    const milliseconds = components.milliseconds
+        ? Math.floor(components.milliseconds)
+        : Math.round(fractionalSeconds * 1000);
+
+    const nanoseconds = components.nanoseconds
+        ? Math.floor(components.nanoseconds)
+        : Math.round(fractionalSeconds * 1_000_000_000) % 1_000_000;
+
+    // Total days including weeks
+    const totalDays = days + weeks * 7;
+
+    // Total seconds for the time portion
+    const totalSeconds = hours * 3600 + minutes * 60 + seconds;
+
+    // Approximate total in various units (months approximated at 30 days)
+    const totalMonths = years * 12 + months;
+
+    // Build ISO 8601 formatted string
+    let formatted = "P";
+    if (years) formatted += `${years}Y`;
+    if (months) formatted += `${months}M`;
+    if (weeks) formatted += `${weeks}W`;
+    if (totalDays - weeks * 7) formatted += `${totalDays - weeks * 7}D`;
+    const hasTime = hours || minutes || seconds || milliseconds;
+    if (hasTime) {
+        formatted += "T";
+        if (hours) formatted += `${hours}H`;
+        if (minutes) formatted += `${minutes}M`;
+        if (seconds || milliseconds) {
+            if (milliseconds) {
+                formatted += `${seconds}.${String(milliseconds).padStart(3, "0")}S`;
+            } else {
+                formatted += `${seconds}S`;
+            }
+        }
+    }
+    if (formatted === "P") formatted = "PT0S";
+
+    return {
+        years,
+        months,
+        weeks,
+        days: totalDays,
+        hours,
+        minutes,
+        seconds,
+        milliseconds,
+        nanoseconds,
+        totalMonths,
+        totalDays,
+        totalSeconds,
+        formatted,
+    };
+}
+
+@FunctionDef({
+    description:
+        "Creates a duration value representing a span of time. " +
+        "Accepts an ISO 8601 duration string (e.g., 'P1Y2M3DT4H5M6S') or a map of components " +
+        "(years, months, weeks, days, hours, minutes, seconds, milliseconds, nanoseconds).",
+    category: "scalar",
+    parameters: [
+        {
+            name: "input",
+            description:
+                "An ISO 8601 duration string or a map of components (years, months, weeks, days, hours, minutes, seconds, milliseconds, nanoseconds)",
+            type: "any",
+        },
+    ],
+    output: {
+        description:
+            "A duration object with properties: years, months, weeks, days, hours, minutes, seconds, " +
+            "milliseconds, nanoseconds, totalMonths, totalDays, totalSeconds, formatted",
+        type: "object",
+    },
+    examples: [
+        "RETURN duration('P1Y2M3D') AS d",
+        "RETURN duration('PT2H30M') AS d",
+        "RETURN duration({days: 14, hours: 16}) AS d",
+        "RETURN duration({months: 5, days: 1, hours: 12}) AS d",
+    ],
+})
+class Duration extends Function {
+    constructor() {
+        super("duration");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const arg = this.getChildren()[0].value();
+        if (arg === null || arg === undefined) {
+            return null;
+        }
+
+        if (typeof arg === "string") {
+            const components = parseDurationString(arg);
+            return buildDurationObject(components);
+        }
+
+        if (typeof arg === "object" && !Array.isArray(arg)) {
+            return buildDurationObject(arg);
+        }
+
+        throw new Error("duration() expects a string or map argument");
+    }
+}
+
+export default Duration;

package/src/parsing/functions/element_id.ts

@@ -0,0 +1,51 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description:
+        "Returns the element id of a node or relationship as a string. For nodes, returns the string representation of the id property. For relationships, returns the type.",
+    category: "scalar",
+    parameters: [
+        {
+            name: "entity",
+            description: "A node or relationship to get the element id from",
+            type: "object",
+        },
+    ],
+    output: {
+        description: "The element id of the entity as a string",
+        type: "string",
+        example: '"1"',
+    },
+    examples: ["MATCH (n:Person) RETURN elementId(n)", "MATCH (a)-[r]->(b) RETURN elementId(r)"],
+})
+class ElementId extends Function {
+    constructor() {
+        super("elementid");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const obj = this.getChildren()[0].value();
+        if (obj === null || obj === undefined) {
+            return null;
+        }
+        if (typeof obj !== "object" || Array.isArray(obj)) {
+            throw new Error("elementId() expects a node or relationship");
+        }
+
+        // If it's a RelationshipMatchRecord (has type, startNode, endNode, properties)
+        if ("type" in obj && "startNode" in obj && "endNode" in obj && "properties" in obj) {
+            return String(obj.type);
+        }
+
+        // If it's a node record (has id field)
+        if ("id" in obj) {
+            return String(obj.id);
+        }
+
+        throw new Error("elementId() expects a node or relationship");
+    }
+}
+
+export default ElementId;

package/src/parsing/functions/function_factory.ts

@@ -1,7 +1,12 @@
 import AsyncFunction from "./async_function";
 import "./avg";
+import "./coalesce";
 import "./collect";
 import "./count";
+import "./date";
+import "./datetime";
+import "./duration";
+import "./element_id";
 import Function from "./function";
 import {
     AsyncDataProvider,
@@ -11,12 +16,22 @@ import {
     getRegisteredFunctionMetadata,
 } from "./function_metadata";
 import "./functions";
+import "./head";
+import "./id";
 import "./join";
 import "./keys";
+import "./last";
+import "./localdatetime";
+import "./localtime";
+import "./max";
+import "./min";
+import "./nodes";
 import PredicateFunction from "./predicate_function";
 import "./predicate_sum";
+import "./properties";
 import "./rand";
 import "./range";
+import "./relationships";
 import "./replace";
 import "./round";
 import "./schema";
@@ -26,6 +41,11 @@ import "./string_distance";
 import "./stringify";
 // Import built-in functions to ensure their @FunctionDef decorators run
 import "./sum";
+import "./tail";
+import "./time";
+import "./timestamp";
+import "./to_float";
+import "./to_integer";
 import "./to_json";
 import "./to_lower";
 import "./to_string";

package/src/parsing/functions/head.ts

@@ -0,0 +1,42 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Returns the first element of a list",
+    category: "scalar",
+    parameters: [
+        {
+            name: "list",
+            description: "The list to get the first element from",
+            type: "array",
+        },
+    ],
+    output: {
+        description: "The first element of the list",
+        type: "any",
+        example: "1",
+    },
+    examples: ["RETURN head([1, 2, 3])", "WITH ['a', 'b', 'c'] AS items RETURN head(items)"],
+})
+class Head extends Function {
+    constructor() {
+        super("head");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return null;
+        }
+        if (!Array.isArray(val)) {
+            throw new Error("head() expects a list");
+        }
+        if (val.length === 0) {
+            return null;
+        }
+        return val[0];
+    }
+}
+
+export default Head;

package/src/parsing/functions/id.ts

@@ -0,0 +1,51 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description:
+        "Returns the id of a node or relationship. For nodes, returns the id property. For relationships, returns the type.",
+    category: "scalar",
+    parameters: [
+        {
+            name: "entity",
+            description: "A node or relationship to get the id from",
+            type: "object",
+        },
+    ],
+    output: {
+        description: "The id of the entity",
+        type: "any",
+        example: "1",
+    },
+    examples: ["MATCH (n:Person) RETURN id(n)", "MATCH (a)-[r]->(b) RETURN id(r)"],
+})
+class Id extends Function {
+    constructor() {
+        super("id");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const obj = this.getChildren()[0].value();
+        if (obj === null || obj === undefined) {
+            return null;
+        }
+        if (typeof obj !== "object" || Array.isArray(obj)) {
+            throw new Error("id() expects a node or relationship");
+        }
+
+        // If it's a RelationshipMatchRecord (has type, startNode, endNode, properties)
+        if ("type" in obj && "startNode" in obj && "endNode" in obj && "properties" in obj) {
+            return obj.type;
+        }
+
+        // If it's a node record (has id field)
+        if ("id" in obj) {
+            return obj.id;
+        }
+
+        throw new Error("id() expects a node or relationship");
+    }
+}
+
+export default Id;

package/src/parsing/functions/last.ts

@@ -0,0 +1,42 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Returns the last element of a list",
+    category: "scalar",
+    parameters: [
+        {
+            name: "list",
+            description: "The list to get the last element from",
+            type: "array",
+        },
+    ],
+    output: {
+        description: "The last element of the list",
+        type: "any",
+        example: "3",
+    },
+    examples: ["RETURN last([1, 2, 3])", "WITH ['a', 'b', 'c'] AS items RETURN last(items)"],
+})
+class Last extends Function {
+    constructor() {
+        super("last");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return null;
+        }
+        if (!Array.isArray(val)) {
+            throw new Error("last() expects a list");
+        }
+        if (val.length === 0) {
+            return null;
+        }
+        return val[val.length - 1];
+    }
+}
+
+export default Last;

package/src/parsing/functions/localdatetime.ts

@@ -0,0 +1,63 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+import { buildDatetimeObject, parseTemporalArg } from "./temporal_utils";
+
+/**
+ * Returns a local datetime value (date + time, no timezone offset).
+ * When called with no arguments, returns the current local datetime.
+ * When called with a string argument, parses it as an ISO 8601 datetime.
+ * When called with a map argument, constructs a datetime from components.
+ *
+ * @example
+ * ```
+ * RETURN localdatetime() AS now
+ * RETURN localdatetime('2025-06-15T12:30:00') AS dt
+ * ```
+ */
+@FunctionDef({
+    description:
+        "Returns a local datetime value (no timezone). With no arguments returns the current local datetime. " +
+        "Accepts an ISO 8601 string or a map of components.",
+    category: "scalar",
+    parameters: [
+        {
+            name: "input",
+            description: "Optional. An ISO 8601 datetime string or a map of components.",
+            type: "string",
+            required: false,
+        },
+    ],
+    output: {
+        description:
+            "A datetime object with properties: year, month, day, hour, minute, second, millisecond, " +
+            "epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted",
+        type: "object",
+    },
+    examples: [
+        "RETURN localdatetime() AS now",
+        "RETURN localdatetime('2025-06-15T12:30:00') AS dt",
+        "WITH localdatetime() AS dt RETURN dt.hour, dt.minute",
+    ],
+})
+class LocalDatetime extends Function {
+    constructor() {
+        super("localdatetime");
+        this._expectedParameterCount = null;
+    }
+
+    public value(): any {
+        const children = this.getChildren();
+        if (children.length > 1) {
+            throw new Error("localdatetime() accepts at most one argument");
+        }
+
+        const d: Date =
+            children.length === 1
+                ? parseTemporalArg(children[0].value(), "localdatetime")
+                : new Date();
+
+        return buildDatetimeObject(d, false);
+    }
+}
+
+export default LocalDatetime;