flowquery 1.0.34 → 1.0.36

package/package.json

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

package/src/graph/database.ts

@@ -34,20 +34,34 @@ class Database {
         }
         const physical = new PhysicalRelationship(null, relationship.type);
         physical.statement = statement;
+        physical.source = relationship.source;
+        physical.target = relationship.target;
         Database.relationships.set(relationship.type, physical);
     }
     public getRelationship(relationship: Relationship): PhysicalRelationship | null {
         return Database.relationships.get(relationship.type!) || null;
     }
+    public getRelationships(relationship: Relationship): PhysicalRelationship[] {
+        const result: PhysicalRelationship[] = [];
+        for (const type of relationship.types) {
+            const physical = Database.relationships.get(type);
+            if (physical) {
+                result.push(physical);
+            }
+        }
+        return result;
+    }
     public async schema(): Promise<Record<string, any>[]> {
         const result: Record<string, any>[] = [];
 
         for (const [label, physical] of Database.nodes) {
             const records = await physical.data();
-            const entry: Record<string, any> = { kind: "node", label };
+            const entry: Record<string, any> = { kind: "Node", label };
             if (records.length > 0) {
                 const { id, ...sample } = records[0];
-                if (Object.keys(sample).length > 0) {
+                const properties = Object.keys(sample);
+                if (properties.length > 0) {
+                    entry.properties = properties;
                     entry.sample = sample;
                 }
             }
@@ -56,10 +70,17 @@ class Database {
 
         for (const [type, physical] of Database.relationships) {
             const records = await physical.data();
-            const entry: Record<string, any> = { kind: "relationship", type };
+            const entry: Record<string, any> = {
+                kind: "Relationship",
+                type,
+                from_label: physical.source?.label || null,
+                to_label: physical.target?.label || null,
+            };
             if (records.length > 0) {
                 const { left_id, right_id, ...sample } = records[0];
-                if (Object.keys(sample).length > 0) {
+                const properties = Object.keys(sample);
+                if (properties.length > 0) {
+                    entry.properties = properties;
                     entry.sample = sample;
                 }
             }
@@ -78,6 +99,23 @@ class Database {
             const data = await node.data();
             return new NodeData(data as NodeRecord[]);
         } else if (element instanceof Relationship) {
+            if (element.types.length > 1) {
+                const physicals = this.getRelationships(element);
+                if (physicals.length === 0) {
+                    throw new Error(
+                        `No physical relationships found for types ${element.types.join(", ")}`
+                    );
+                }
+                const allRecords: RelationshipRecord[] = [];
+                for (let i = 0; i < physicals.length; i++) {
+                    const records = (await physicals[i].data()) as RelationshipRecord[];
+                    const typeName = element.types[i];
+                    for (const record of records) {
+                        allRecords.push({ ...record, _type: typeName });
+                    }
+                }
+                return new RelationshipData(allRecords);
+            }
             const relationship = this.getRelationship(element);
             if (relationship === null) {
                 throw new Error(`Physical relationship not found for type ${element.type}`);

package/src/graph/relationship.ts

@@ -9,7 +9,7 @@ import RelationshipMatchCollector, {
 
 class Relationship extends ASTNode {
     protected _identifier: string | null = null;
-    protected _type: string | null = null;
+    protected _types: string[] = [];
     protected _properties: Map<string, Expression> = new Map();
     protected _hops: Hops = new Hops();
 
@@ -25,7 +25,9 @@ class Relationship extends ASTNode {
     constructor(identifier: string | null = null, type: string | null = null) {
         super();
         this._identifier = identifier;
-        this._type = type;
+        if (type !== null) {
+            this._types = [type];
+        }
     }
     public set identifier(identifier: string) {
         this._identifier = identifier;
@@ -34,10 +36,16 @@ class Relationship extends ASTNode {
         return this._identifier;
     }
     public set type(type: string) {
-        this._type = type;
+        this._types = [type];
     }
     public get type(): string | null {
-        return this._type;
+        return this._types.length > 0 ? this._types[0] : null;
+    }
+    public set types(types: string[]) {
+        this._types = types;
+    }
+    public get types(): string[] {
+        return this._types;
     }
     public get properties(): Map<string, Expression> {
         return this._properties;

package/src/graph/relationship_data.ts

@@ -18,7 +18,7 @@ class RelationshipData extends Data {
     public properties(): Record<string, any> | null {
         const current = this.current();
         if (current) {
-            const { left_id, right_id, ...props } = current;
+            const { left_id, right_id, _type, ...props } = current;
             return props;
         }
         return null;

package/src/graph/relationship_match_collector.ts

@@ -12,11 +12,15 @@ class RelationshipMatchCollector {
     private _nodeIds: Array<string> = [];
 
     public push(relationship: Relationship, traversalId: string): RelationshipMatchRecord {
+        const data = relationship.getData();
+        const currentRecord = data?.current();
+        const actualType =
+            currentRecord && "_type" in currentRecord ? currentRecord["_type"] : relationship.type!;
         const match: RelationshipMatchRecord = {
-            type: relationship.type!,
+            type: actualType,
             startNode: relationship.source?.value() || {},
             endNode: null,
-            properties: relationship.getData()?.properties() as Record<string, any>,
+            properties: data?.properties() as Record<string, any>,
         };
         this._matches.push(match);
         this._nodeIds.push(traversalId);

package/src/graph/relationship_reference.ts

@@ -6,7 +6,7 @@ class RelationshipReference extends Relationship {
     constructor(base: Relationship, reference: Relationship) {
         super();
         this._identifier = base.identifier;
-        this._type = base.type;
+        this._types = base.types;
         this._hops = base.hops!;
         this._source = base.source;
         this._target = base.target;

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,50 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+/**
+ * Returns the first non-null value from a list of expressions.
+ * Equivalent to Neo4j's coalesce() function.
+ *
+ * @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,65 @@
+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.
+ *
+ * Equivalent to Neo4j's date() function.
+ *
+ * @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,65 @@
+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.
+ *
+ * Equivalent to Neo4j's datetime() function.
+ *
+ * @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,9 +41,15 @@ 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";
+import "./trim";
 import "./type";
 
 // Re-export AsyncDataProvider for backwards compatibility

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;