flowquery 1.0.46 → 1.0.48

package/src/parsing/functions/collect.ts

@@ -1,54 +0,0 @@
-import AggregateFunction from "./aggregate_function";
-import ReducerElement from "./reducer_element";
-import { FunctionDef } from "./function_metadata";
-
-class CollectReducerElement extends ReducerElement {
-    private _value: any[] = [];
-    public get value(): any {
-        return this._value;
-    }
-    public set value(value: any) {
-        this._value.push(value);
-    }
-}
-
-class DistinctCollectReducerElement extends ReducerElement {
-    private _value: Map<any, any> = new Map();
-    public get value(): any {
-        return Array.from(this._value.values());
-    }
-    public set value(value: any) {
-        const key: string = JSON.stringify(value);
-        if (!this._value.has(key)) {
-            this._value.set(key, value);
-        }
-    }
-}
-
-@FunctionDef({
-    description: "Collects values into an array across grouped rows",
-    category: "aggregate",
-    parameters: [
-        { name: "value", description: "Value to collect", type: "any" }
-    ],
-    output: { description: "Array of collected values", type: "array", example: [1, 2, 3] },
-    examples: ["WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN collect(n)"]
-})
-class Collect extends AggregateFunction {
-    private _distinct: boolean = false;
-    constructor() {
-        super("collect");
-        this._expectedParameterCount = 1;
-    }
-    public reduce(element: CollectReducerElement): void {
-        element.value = this.firstChild().value();
-    }
-    public element(): CollectReducerElement | DistinctCollectReducerElement {
-        return this._distinct ? new DistinctCollectReducerElement() : new CollectReducerElement();
-    }
-    public set distinct(distinct: boolean) {
-        this._distinct = distinct;
-    }
-}
-
-export default Collect;

package/src/parsing/functions/count.ts

@@ -1,54 +0,0 @@
-import AggregateFunction from "./aggregate_function";
-import { FunctionDef } from "./function_metadata";
-import ReducerElement from "./reducer_element";
-
-class CountReducerElement extends ReducerElement {
-    private _value: number = 0;
-    public get value(): any {
-        return this._value;
-    }
-    public set value(value: any) {
-        this._value += 1;
-    }
-}
-
-class DistinctCountReducerElement extends ReducerElement {
-    private _seen: Set<string> = new Set();
-    public get value(): any {
-        return this._seen.size;
-    }
-    public set value(value: any) {
-        const key: string = JSON.stringify(value);
-        this._seen.add(key);
-    }
-}
-
-@FunctionDef({
-    description: "Counts the number of values across grouped rows",
-    category: "aggregate",
-    parameters: [{ name: "value", description: "Value to count", type: "any" }],
-    output: { description: "Number of values", type: "number", example: 3 },
-    examples: [
-        "WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN count(n)",
-        "WITH [1, 2, 2, 3] AS nums UNWIND nums AS n RETURN count(distinct n)",
-    ],
-})
-class Count extends AggregateFunction {
-    private _distinct: boolean = false;
-    constructor() {
-        super("count");
-        this._expectedParameterCount = 1;
-        this._supports_distinct = true;
-    }
-    public reduce(element: CountReducerElement | DistinctCountReducerElement): void {
-        element.value = this.firstChild().value();
-    }
-    public element(): CountReducerElement | DistinctCountReducerElement {
-        return this._distinct ? new DistinctCountReducerElement() : new CountReducerElement();
-    }
-    public set distinct(distinct: boolean) {
-        this._distinct = distinct;
-    }
-}
-
-export default Count;

package/src/parsing/functions/date.ts

@@ -1,63 +0,0 @@
-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

@@ -1,63 +0,0 @@
-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

@@ -1,143 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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.ts

@@ -1,60 +0,0 @@
-import ASTNode from "../ast_node";
-
-/**
- * Base class for all functions in FlowQuery.
- * 
- * Functions can have parameters and may support the DISTINCT modifier.
- * Subclasses implement specific function logic.
- * 
- * @example
- * ```typescript
- * const func = FunctionFactory.create("sum");
- * func.parameters = [expression1, expression2];
- * ```
- */
-class Function extends ASTNode {
-    protected _name: string;
-    protected _expectedParameterCount: number | null = null;
-    protected _supports_distinct: boolean = false;
-
-    /**
-     * Creates a new Function with the given name.
-     * 
-     * @param name - The function name
-     */
-    constructor(name?: string) {
-        super();
-        this._name = name || this.constructor.name;
-    }
-
-    /**
-     * Sets the function parameters.
-     * 
-     * @param nodes - Array of AST nodes representing the function arguments
-     * @throws {Error} If the number of parameters doesn't match expected count
-     */
-    public set parameters(nodes: ASTNode[]) {
-        if (this._expectedParameterCount !== null && this._expectedParameterCount !== nodes.length) {
-            throw new Error(`Function ${this._name} expected ${this._expectedParameterCount} parameters, but got ${nodes.length}`);
-        }
-        this.children = nodes;
-    }
-
-    public get name(): string {
-        return this._name;
-    }
-
-    public toString(): string {
-        return `Function (${this._name})`;
-    }
-
-    public set distinct(distinct: boolean) {
-        if (this._supports_distinct) {
-            this._supports_distinct = distinct;
-        } else {
-            throw new Error(`Function ${this._name} does not support distinct`);
-        }
-    }
-}
-
-export default Function;

package/src/parsing/functions/function_factory.ts

@@ -1,195 +0,0 @@
-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,
-    FunctionMetadata,
-    getFunctionMetadata,
-    getRegisteredFunctionFactory,
-    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";
-import "./size";
-import "./split";
-import "./string_distance";
-import "./stringify";
-import "./substring";
-// 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
-export { AsyncDataProvider };
-
-/**
- * Factory for creating function instances by name.
- *
- * All functions are registered via the @FunctionDef decorator.
- * Maps function names (case-insensitive) to their corresponding implementation classes.
- * Supports built-in functions like sum, avg, collect, range, split, join, etc.
- *
- * @example
- * ```typescript
- * const sumFunc = FunctionFactory.create("sum");
- * const avgFunc = FunctionFactory.create("AVG");
- * ```
- */
-class FunctionFactory {
-    /**
-     * Gets an async data provider by name.
-     *
-     * @param name - The function name (case-insensitive)
-     * @returns The async data provider, or undefined if not found
-     */
-    public static getAsyncProvider(name: string): AsyncDataProvider | undefined {
-        return getRegisteredFunctionFactory(name.toLowerCase());
-    }
-
-    /**
-     * Checks if a function name is registered as an async data provider.
-     *
-     * @param name - The function name (case-insensitive)
-     * @returns True if the function is an async data provider
-     */
-    public static isAsyncProvider(name: string): boolean {
-        return getRegisteredFunctionFactory(name.toLowerCase(), "async") !== undefined;
-    }
-
-    /**
-     * Gets metadata for a specific function.
-     *
-     * @param name - The function name (case-insensitive)
-     * @returns The function metadata, or undefined if not found
-     */
-    public static getMetadata(name: string): FunctionMetadata | undefined {
-        return getFunctionMetadata(name.toLowerCase());
-    }
-
-    /**
-     * Lists all registered functions with their metadata.
-     *
-     * @param options - Optional filter options
-     * @returns Array of function metadata
-     */
-    public static listFunctions(options?: {
-        category?: string;
-        asyncOnly?: boolean;
-        syncOnly?: boolean;
-    }): FunctionMetadata[] {
-        const result: FunctionMetadata[] = [];
-
-        for (const meta of getRegisteredFunctionMetadata()) {
-            if (options?.category && meta.category !== options.category) continue;
-            if (options?.asyncOnly && meta.category !== "async") continue;
-            if (options?.syncOnly && meta.category === "async") continue;
-            result.push(meta);
-        }
-
-        return result;
-    }
-
-    /**
-     * Lists all registered function names.
-     *
-     * @returns Array of function names
-     */
-    public static listFunctionNames(): string[] {
-        return getRegisteredFunctionMetadata().map((m) => m.name);
-    }
-
-    /**
-     * Gets all function metadata as a JSON-serializable object for LLM consumption.
-     *
-     * @returns Object with functions grouped by category
-     */
-    public static toJSON(): { functions: FunctionMetadata[]; categories: string[] } {
-        const functions = FunctionFactory.listFunctions();
-        const categories = [
-            ...new Set(functions.map((f) => f.category).filter(Boolean)),
-        ] as string[];
-        return { functions, categories };
-    }
-
-    /**
-     * Creates a function instance by name.
-     *
-     * @param name - The function name (case-insensitive)
-     * @returns A Function instance of the appropriate type
-     */
-    public static create(name: string): Function {
-        const lowerName: string = name.toLowerCase();
-
-        // Check decorator-registered functions (built-ins use @FunctionDef)
-        const decoratorFactory = getRegisteredFunctionFactory(lowerName);
-        if (decoratorFactory) {
-            return decoratorFactory();
-        }
-
-        throw new Error(`Unknown function: ${name}`);
-    }
-
-    /**
-     * Creates a predicate function instance by name.
-     * Predicate functions are used in WHERE clauses with quantifiers (e.g., ANY, ALL).
-     *
-     * @param name - The function name (case-insensitive)
-     * @returns A PredicateFunction instance of the appropriate type
-     */
-    public static createPredicate(name: string): PredicateFunction {
-        const lowerName: string = name.toLowerCase();
-
-        // Check decorator-registered predicate functions
-        const decoratorFactory = getRegisteredFunctionFactory(lowerName, "predicate");
-        if (decoratorFactory) {
-            return decoratorFactory();
-        }
-
-        throw new Error(`Unknown predicate function: ${name}`);
-    }
-
-    public static createAsync(name: string): AsyncFunction {
-        const lowerName: string = name.toLowerCase();
-        const decoratorFactory = getRegisteredFunctionFactory(lowerName, "async");
-        if (decoratorFactory) {
-            return decoratorFactory() as AsyncFunction;
-        }
-        throw new Error(`Unknown async function: ${name}`);
-    }
-}
-
-export default FunctionFactory;