flowquery 1.0.35 → 1.0.37

package/src/parsing/functions/localtime.ts

@@ -0,0 +1,58 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+import { buildTimeObject, parseTemporalArg } from "./temporal_utils";
+
+/**
+ * Returns a local time value (no timezone offset).
+ * When called with no arguments, returns the current local time.
+ * When called with a string argument, parses it.
+ *
+ * @example
+ * ```
+ * RETURN localtime() AS now
+ * RETURN localtime('14:30:00') AS t
+ * ```
+ */
+@FunctionDef({
+    description:
+        "Returns a local time value (no timezone). With no arguments returns the current local time. " +
+        "Accepts an ISO 8601 time string or a map of components.",
+    category: "scalar",
+    parameters: [
+        {
+            name: "input",
+            description: "Optional. An ISO 8601 time string (HH:MM:SS) or a map of components.",
+            type: "string",
+            required: false,
+        },
+    ],
+    output: {
+        description: "A time object with properties: hour, minute, second, millisecond, formatted",
+        type: "object",
+    },
+    examples: [
+        "RETURN localtime() AS now",
+        "RETURN localtime('14:30:00') AS t",
+        "WITH localtime() AS t RETURN t.hour, t.minute",
+    ],
+})
+class LocalTime extends Function {
+    constructor() {
+        super("localtime");
+        this._expectedParameterCount = null;
+    }
+
+    public value(): any {
+        const children = this.getChildren();
+        if (children.length > 1) {
+            throw new Error("localtime() accepts at most one argument");
+        }
+
+        const d: Date =
+            children.length === 1 ? parseTemporalArg(children[0].value(), "localtime") : new Date();
+
+        return buildTimeObject(d, false);
+    }
+}
+
+export default LocalTime;

package/src/parsing/functions/max.ts

@@ -0,0 +1,37 @@
+import AggregateFunction from "./aggregate_function";
+import { FunctionDef } from "./function_metadata";
+import ReducerElement from "./reducer_element";
+
+class MaxReducerElement extends ReducerElement {
+    private _value: any = null;
+    public get value(): any {
+        return this._value;
+    }
+    public set value(value: any) {
+        if (this._value === null || value > this._value) {
+            this._value = value;
+        }
+    }
+}
+
+@FunctionDef({
+    description: "Returns the maximum value across grouped rows",
+    category: "aggregate",
+    parameters: [{ name: "value", description: "Value to compare", type: "number" }],
+    output: { description: "Maximum value", type: "number", example: 10 },
+    examples: ["WITH [3, 1, 2] AS nums UNWIND nums AS n RETURN max(n)"],
+})
+class Max extends AggregateFunction {
+    constructor() {
+        super("max");
+        this._expectedParameterCount = 1;
+    }
+    public reduce(element: MaxReducerElement): void {
+        element.value = this.firstChild().value();
+    }
+    public element(): MaxReducerElement {
+        return new MaxReducerElement();
+    }
+}
+
+export default Max;

package/src/parsing/functions/min.ts

@@ -0,0 +1,37 @@
+import AggregateFunction from "./aggregate_function";
+import { FunctionDef } from "./function_metadata";
+import ReducerElement from "./reducer_element";
+
+class MinReducerElement extends ReducerElement {
+    private _value: any = null;
+    public get value(): any {
+        return this._value;
+    }
+    public set value(value: any) {
+        if (this._value === null || value < this._value) {
+            this._value = value;
+        }
+    }
+}
+
+@FunctionDef({
+    description: "Returns the minimum value across grouped rows",
+    category: "aggregate",
+    parameters: [{ name: "value", description: "Value to compare", type: "number" }],
+    output: { description: "Minimum value", type: "number", example: 1 },
+    examples: ["WITH [3, 1, 2] AS nums UNWIND nums AS n RETURN min(n)"],
+})
+class Min extends AggregateFunction {
+    constructor() {
+        super("min");
+        this._expectedParameterCount = 1;
+    }
+    public reduce(element: MinReducerElement): void {
+        element.value = this.firstChild().value();
+    }
+    public element(): MinReducerElement {
+        return new MinReducerElement();
+    }
+}
+
+export default Min;

package/src/parsing/functions/nodes.ts

@@ -0,0 +1,54 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Returns all nodes in a path as an array",
+    category: "scalar",
+    parameters: [
+        {
+            name: "path",
+            description: "A path value returned from a graph pattern match",
+            type: "array",
+        },
+    ],
+    output: {
+        description: "Array of node records",
+        type: "array",
+        example: "[{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]",
+    },
+    examples: ["MATCH p=(:Person)-[:KNOWS]-(:Person) RETURN nodes(p)"],
+})
+class Nodes extends Function {
+    constructor() {
+        super("nodes");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const path = this.getChildren()[0].value();
+        if (path === null || path === undefined) {
+            return [];
+        }
+        if (!Array.isArray(path)) {
+            throw new Error("nodes() expects a path (array)");
+        }
+        // A path is an array of alternating node and relationship objects:
+        // [node, rel, node, rel, node, ...]
+        // Nodes are plain NodeRecords (have 'id' but not 'type'/'startNode'/'endNode')
+        // Relationships are RelationshipMatchRecords (have 'type', 'startNode', 'endNode', 'properties')
+        return path.filter((element: any) => {
+            if (element === null || element === undefined || typeof element !== "object") {
+                return false;
+            }
+            // A RelationshipMatchRecord has type, startNode, endNode, properties
+            return !(
+                "type" in element &&
+                "startNode" in element &&
+                "endNode" in element &&
+                "properties" in element
+            );
+        });
+    }
+}
+
+export default Nodes;

package/src/parsing/functions/properties.ts

@@ -0,0 +1,56 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description:
+        "Returns a map containing all the properties of a node, relationship, or map. For nodes and relationships, internal identifiers are excluded.",
+    category: "scalar",
+    parameters: [
+        {
+            name: "entity",
+            description: "A node, relationship, or map to extract properties from",
+            type: "object",
+        },
+    ],
+    output: {
+        description: "Map of properties",
+        type: "object",
+        example: "{ name: 'Alice', age: 30 }",
+    },
+    examples: [
+        "MATCH (n:Person) RETURN properties(n)",
+        "WITH { name: 'Alice', age: 30 } AS obj RETURN properties(obj)",
+    ],
+})
+class Properties extends Function {
+    constructor() {
+        super("properties");
+        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("properties() expects a node, relationship, or map");
+        }
+
+        // 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.properties;
+        }
+
+        // If it's a node record (has id field), exclude id
+        if ("id" in obj) {
+            const { id, ...props } = obj;
+            return props;
+        }
+
+        // Otherwise, treat as a plain map and return a copy
+        return { ...obj };
+    }
+}
+
+export default Properties;

package/src/parsing/functions/relationships.ts

@@ -0,0 +1,52 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Returns all relationships in a path as an array",
+    category: "scalar",
+    parameters: [
+        {
+            name: "path",
+            description: "A path value returned from a graph pattern match",
+            type: "array",
+        },
+    ],
+    output: {
+        description: "Array of relationship records",
+        type: "array",
+        example: "[{ type: 'KNOWS', properties: { since: '2020' } }]",
+    },
+    examples: ["MATCH p=(:Person)-[:KNOWS]-(:Person) RETURN relationships(p)"],
+})
+class Relationships extends Function {
+    constructor() {
+        super("relationships");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const path = this.getChildren()[0].value();
+        if (path === null || path === undefined) {
+            return [];
+        }
+        if (!Array.isArray(path)) {
+            throw new Error("relationships() expects a path (array)");
+        }
+        // A path is an array of alternating node and relationship objects:
+        // [node, rel, node, rel, node, ...]
+        // Relationships are RelationshipMatchRecords (have 'type', 'startNode', 'endNode', 'properties')
+        return path.filter((element: any) => {
+            if (element === null || element === undefined || typeof element !== "object") {
+                return false;
+            }
+            return (
+                "type" in element &&
+                "startNode" in element &&
+                "endNode" in element &&
+                "properties" in element
+            );
+        });
+    }
+}
+
+export default Relationships;

package/src/parsing/functions/tail.ts

@@ -0,0 +1,39 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Returns all elements of a list except the first",
+    category: "scalar",
+    parameters: [
+        {
+            name: "list",
+            description: "The list to get all but the first element from",
+            type: "array",
+        },
+    ],
+    output: {
+        description: "All elements except the first",
+        type: "array",
+        example: "[2, 3]",
+    },
+    examples: ["RETURN tail([1, 2, 3])", "WITH ['a', 'b', 'c'] AS items RETURN tail(items)"],
+})
+class Tail extends Function {
+    constructor() {
+        super("tail");
+        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("tail() expects a list");
+        }
+        return val.slice(1);
+    }
+}
+
+export default Tail;

package/src/parsing/functions/temporal_utils.ts

@@ -0,0 +1,180 @@
+/**
+ * Shared utility functions for temporal (date/time) operations.
+ *
+ * These helpers are used by the datetime, date, time, localdatetime,
+ * localtime, and timestamp functions.
+ */
+
+/**
+ * Computes the ISO day of the week (1 = Monday, 7 = Sunday).
+ */
+function isoDayOfWeek(d: Date): number {
+    const jsDay = d.getDay(); // 0 = Sunday, 6 = Saturday
+    return jsDay === 0 ? 7 : jsDay;
+}
+
+/**
+ * Computes the day of the year (1-based).
+ */
+function dayOfYear(d: Date): number {
+    const start = new Date(d.getFullYear(), 0, 0);
+    const diff = d.getTime() - start.getTime();
+    const oneDay = 1000 * 60 * 60 * 24;
+    return Math.floor(diff / oneDay);
+}
+
+/**
+ * Computes the quarter (1-4) from a month (0-11).
+ */
+function quarter(month: number): number {
+    return Math.floor(month / 3) + 1;
+}
+
+/**
+ * Pads a number to a given width with leading zeros.
+ */
+function pad(n: number, width: number = 2): string {
+    return String(n).padStart(width, "0");
+}
+
+/**
+ * Formats a timezone offset in ±HH:MM format.
+ */
+function formatTimezoneOffset(d: Date): string {
+    const offset = -d.getTimezoneOffset();
+    if (offset === 0) return "Z";
+    const sign = offset > 0 ? "+" : "-";
+    const absOffset = Math.abs(offset);
+    const hours = Math.floor(absOffset / 60);
+    const minutes = absOffset % 60;
+    return `${sign}${pad(hours)}:${pad(minutes)}`;
+}
+
+/**
+ * Parses a temporal argument (string or map) into a Date object.
+ *
+ * @param arg - The argument to parse (string or object with year/month/day/hour/minute/second/millisecond)
+ * @param fnName - The calling function name for error messages
+ * @returns A Date object
+ */
+export function parseTemporalArg(arg: any, fnName: string): Date {
+    if (typeof arg === "string") {
+        const d = new Date(arg);
+        if (isNaN(d.getTime())) {
+            throw new Error(`${fnName}(): Invalid temporal string: '${arg}'`);
+        }
+        return d;
+    }
+
+    if (typeof arg === "number") {
+        // Treat as epoch milliseconds
+        return new Date(arg);
+    }
+
+    if (typeof arg === "object" && arg !== null && !Array.isArray(arg)) {
+        // Map-style construction: {year, month, day, hour, minute, second, millisecond}
+        const year = arg.year ?? new Date().getFullYear();
+        const month = (arg.month ?? 1) - 1; // JS months are 0-based
+        const day = arg.day ?? 1;
+        const hour = arg.hour ?? 0;
+        const minute = arg.minute ?? 0;
+        const second = arg.second ?? 0;
+        const millisecond = arg.millisecond ?? 0;
+        return new Date(year, month, day, hour, minute, second, millisecond);
+    }
+
+    throw new Error(
+        `${fnName}(): Expected a string, number (epoch millis), or map argument, got ${typeof arg}`
+    );
+}
+
+/**
+ * Builds a datetime result object with full temporal properties.
+ *
+ * @param d - The Date object
+ * @param utc - If true, use UTC values; if false, use local values
+ * @returns An object with year, month, day, hour, minute, second, millisecond,
+ *          epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted
+ */
+export function buildDatetimeObject(d: Date, utc: boolean): Record<string, any> {
+    const year = utc ? d.getUTCFullYear() : d.getFullYear();
+    const month = utc ? d.getUTCMonth() + 1 : d.getMonth() + 1;
+    const day = utc ? d.getUTCDate() : d.getDate();
+    const hour = utc ? d.getUTCHours() : d.getHours();
+    const minute = utc ? d.getUTCMinutes() : d.getMinutes();
+    const second = utc ? d.getUTCSeconds() : d.getSeconds();
+    const millisecond = utc ? d.getUTCMilliseconds() : d.getMilliseconds();
+
+    const datePart = new Date(year, month - 1, day);
+
+    const formatted = utc
+        ? d.toISOString()
+        : `${year}-${pad(month)}-${pad(day)}T${pad(hour)}:${pad(minute)}:${pad(second)}.${pad(millisecond, 3)}`;
+
+    return {
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        millisecond,
+        epochMillis: d.getTime(),
+        epochSeconds: Math.floor(d.getTime() / 1000),
+        dayOfWeek: isoDayOfWeek(datePart),
+        dayOfYear: dayOfYear(datePart),
+        quarter: quarter(month - 1),
+        formatted,
+    };
+}
+
+/**
+ * Builds a date result object (no time component).
+ *
+ * @param d - The Date object
+ * @returns An object with year, month, day, epochMillis, dayOfWeek, dayOfYear, quarter, formatted
+ */
+export function buildDateObject(d: Date): Record<string, any> {
+    const year = d.getFullYear();
+    const month = d.getMonth() + 1;
+    const day = d.getDate();
+
+    // Strip time component for epoch calculation
+    const dateOnly = new Date(year, month - 1, day);
+
+    return {
+        year,
+        month,
+        day,
+        epochMillis: dateOnly.getTime(),
+        dayOfWeek: isoDayOfWeek(dateOnly),
+        dayOfYear: dayOfYear(dateOnly),
+        quarter: quarter(month - 1),
+        formatted: `${year}-${pad(month)}-${pad(day)}`,
+    };
+}
+
+/**
+ * Builds a time result object (no date component).
+ *
+ * @param d - The Date object
+ * @param utc - If true, use UTC values; if false, use local values
+ * @returns An object with hour, minute, second, millisecond, formatted
+ */
+export function buildTimeObject(d: Date, utc: boolean): Record<string, any> {
+    const hour = utc ? d.getUTCHours() : d.getHours();
+    const minute = utc ? d.getUTCMinutes() : d.getMinutes();
+    const second = utc ? d.getUTCSeconds() : d.getSeconds();
+    const millisecond = utc ? d.getUTCMilliseconds() : d.getMilliseconds();
+
+    const timePart = `${pad(hour)}:${pad(minute)}:${pad(second)}.${pad(millisecond, 3)}`;
+    const formatted = utc ? `${timePart}Z` : timePart;
+
+    return {
+        hour,
+        minute,
+        second,
+        millisecond,
+        formatted,
+    };
+}

package/src/parsing/functions/time.ts

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

package/src/parsing/functions/timestamp.ts

@@ -0,0 +1,37 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+/**
+ * Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).
+ *
+ * @example
+ * ```
+ * RETURN timestamp() AS ts
+ * ```
+ */
+@FunctionDef({
+    description: "Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).",
+    category: "scalar",
+    parameters: [],
+    output: {
+        description: "Milliseconds since Unix epoch",
+        type: "number",
+        example: 1718450000000,
+    },
+    examples: [
+        "RETURN timestamp() AS ts",
+        "WITH timestamp() AS before, timestamp() AS after RETURN after - before",
+    ],
+})
+class Timestamp extends Function {
+    constructor() {
+        super("timestamp");
+        this._expectedParameterCount = 0;
+    }
+
+    public value(): any {
+        return Date.now();
+    }
+}
+
+export default Timestamp;

package/src/parsing/functions/to_float.ts

@@ -0,0 +1,50 @@
+import Function from "./function";
+import { FunctionDef } from "./function_metadata";
+
+@FunctionDef({
+    description: "Converts a value to a floating point number",
+    category: "scalar",
+    parameters: [
+        {
+            name: "value",
+            description: "The value to convert to a float",
+            type: "any",
+        },
+    ],
+    output: {
+        description: "The floating point representation of the value",
+        type: "number",
+        example: "3.14",
+    },
+    examples: ['RETURN toFloat("3.14")', "RETURN toFloat(42)", "RETURN toFloat(true)"],
+})
+class ToFloat extends Function {
+    constructor() {
+        super("tofloat");
+        this._expectedParameterCount = 1;
+    }
+
+    public value(): any {
+        const val = this.getChildren()[0].value();
+        if (val === null || val === undefined) {
+            return null;
+        }
+        if (typeof val === "boolean") {
+            return val ? 1.0 : 0.0;
+        }
+        if (typeof val === "number") {
+            return val;
+        }
+        if (typeof val === "string") {
+            const trimmed = val.trim();
+            const parsed = Number(trimmed);
+            if (isNaN(parsed)) {
+                throw new Error(`Cannot convert string "${val}" to float`);
+            }
+            return parsed;
+        }
+        throw new Error("toFloat() expects a number, string, or boolean");
+    }
+}
+
+export default ToFloat;