flowquery 1.0.46 → 1.0.48

package/src/parsing/functions/function_metadata.ts

@@ -1,217 +0,0 @@
-/**
- * Category types for functions.
- * Core categories: scalar, aggregate, predicate, async
- * Additional categories for organization: string, math, data, etc.
- */
-export type FunctionCategory = "scalar" | "aggregate" | "predicate" | "async" | string;
-
-/**
- * Schema definition for function arguments and outputs.
- * Compatible with JSON Schema for LLM consumption.
- */
-export interface ParameterSchema {
-    /** The parameter name */
-    name: string;
-    /** Description of the parameter */
-    description: string;
-    /** JSON Schema type: string, number, boolean, object, array, null */
-    type: "string" | "number" | "boolean" | "object" | "array" | "null" | string;
-    /** Whether the parameter is required (default: true) */
-    required?: boolean;
-    /** Default value if not provided */
-    default?: any;
-    /** For arrays, the schema of items */
-    items?: Omit<ParameterSchema, 'name' | 'required' | 'default'>;
-    /** For objects, the properties schema */
-    properties?: Record<string, Omit<ParameterSchema, 'name' | 'required'>>;
-    /** Enum of allowed values */
-    enum?: any[];
-    /** Example value */
-    example?: any;
-}
-
-/**
- * Schema definition for function output.
- */
-export interface OutputSchema {
-    /** Description of the output */
-    description: string;
-    /** JSON Schema type */
-    type: "string" | "number" | "boolean" | "object" | "array" | "null" | string;
-    /** For arrays, the schema of items */
-    items?: Omit<OutputSchema, 'description'>;
-    /** For objects, the properties schema */
-    properties?: Record<string, Omit<ParameterSchema, 'name' | 'required'>>;
-    /** Example output value */
-    example?: any;
-}
-
-/**
- * Metadata for a registered function, designed for LLM consumption.
- */
-export interface FunctionMetadata {
-    /** The function name */
-    name: string;
-    /** Human-readable description of what the function does */
-    description: string;
-    /** Category that determines function type and behavior */
-    category: FunctionCategory;
-    /** Array of parameter schemas */
-    parameters: ParameterSchema[];
-    /** Output schema */
-    output: OutputSchema;
-    /** Example usage in FlowQuery syntax */
-    examples?: string[];
-    /** Additional notes or caveats */
-    notes?: string;
-}
-
-/**
- * Type for async data provider functions used in LOAD operations.
- */
-export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
-
-/**
- * Centralized registry for function metadata, factories, and async providers.
- * Encapsulates all registration logic for the @FunctionDef decorator.
- */
-class FunctionRegistry {
-    private static metadata: Map<string, FunctionMetadata> = new Map<string, FunctionMetadata>();
-    private static factories: Map<string, () => any> = new Map<string, () => any>();
-
-    /** Registers a regular function class. */
-    static register<T extends new (...args: any[]) => any>(constructor: T, options: FunctionDefOptions): void {
-        const instance: any = new constructor();
-        const displayName: string = (instance.name?.toLowerCase() || constructor.name.toLowerCase());
-        const registryKey: string = options.category ? `${displayName}:${options.category}` : displayName;
-
-        this.metadata.set(registryKey, { name: displayName, ...options });
-        
-        if (options.category !== 'predicate') {
-            this.factories.set(displayName, () => new constructor());
-        }
-        this.factories.set(registryKey, () => new constructor());
-    }
-
-    static getAllMetadata(): FunctionMetadata[] {
-        return Array.from(this.metadata.values());
-    }
-
-    static getMetadata(name: string, category?: string): FunctionMetadata | undefined {
-        const lowerName: string = name.toLowerCase();
-        if (category) return this.metadata.get(`${lowerName}:${category}`);
-        for (const meta of this.metadata.values()) {
-            if (meta.name.toLowerCase() === lowerName) return meta;
-        }
-        return undefined;
-    }
-
-    static getFactory(name: string, category?: string): (() => any) | undefined {
-        const lowerName: string = name.toLowerCase();
-        if (category) return this.factories.get(`${lowerName}:${category}`);
-        return this.factories.get(lowerName);
-    }
-}
-
-/**
- * Decorator options - metadata without the name (derived from class).
- */
-export type FunctionDefOptions = Omit<FunctionMetadata, 'name'>;
-
-/**
- * Class decorator that registers function metadata.
- * The function name is derived from the class's constructor call to super() for regular functions,
- * or from the class name for async providers.
- * 
- * For async providers (category: "async"), the class must have a `generate` method that returns
- * an AsyncGenerator. This allows the function to be used as a data source in LOAD operations.
- * 
- * @param options - Function metadata (excluding name)
- * @returns Class decorator
- * 
- * @example
- * ```typescript
- * // Scalar function example
- * @FunctionDef({
- *   description: "Adds two numbers",
- *   category: "scalar",
- *   parameters: [
- *     { name: "a", description: "First number", type: "number" },
- *     { name: "b", description: "Second number", type: "number" }
- *   ],
- *   output: { description: "Sum of a and b", type: "number" },
- *   examples: ["ADD(2, 3) // returns 5"]
- * })
- * class AddFunction extends Function {
- *   constructor() {
- *     super("add");
- *   }
- *   public execute(a: number, b: number): number {
- *    return a + b;
- *  }
- * }
- * // Aggregate function example
- * @FunctionDef({
- *   description: "Calculates the average of a list of numbers",
- *  category: "aggregate",
- *  parameters: [
- *    { name: "values", description: "Array of numbers", type: "array", items: { type: "number" } }
- *  ],
- *  output: { description: "Average value", type: "number" },
- *  examples: ["AVERAGE([1, 2, 3, 4, 5]) // returns 3"]
- * })
- * class AverageFunction extends AggregateFunction {
- *   constructor() {
- *    super("average");
- *  }
- *  public execute(values: number[]): number {
- *   const sum = values.reduce((acc, val) => acc + val, 0);
- *   return sum / values.length;
- * }
- * }
- * // Async data provider example
- * @FunctionDef({
- *  description: "Fetches data from an external API",
- * category: "async",
- * parameters: [
- *   { name: "endpoint", description: "API endpoint URL", type: "string" }
- * ],
- * output: { description: "Data object", type: "object" },
- * examples: ["MyAsyncDataProvider('https://api.example.com/data')"]
- * })
- * class MyAsyncDataProvider extends AsyncFunction {
- *   public async *generate(endpoint: string): AsyncGenerator<any> {
- *    const response = await fetch(endpoint);
- *   const data = await response.json();
- *   for (const item of data) {
- *    yield item;
- *  }
- * }
- */
-export function FunctionDef(options: FunctionDefOptions) {
-    return function <T extends new (...args: any[]) => any>(constructor: T): T {
-        FunctionRegistry.register(constructor, options);
-        return constructor;
-    };
-}
-
-/**
- * Gets all registered function metadata from decorators.
- */
-export function getRegisteredFunctionMetadata(): FunctionMetadata[] {
-    return FunctionRegistry.getAllMetadata();
-}
-
-/**
- * Gets a registered function factory by name.
- */
-export function getRegisteredFunctionFactory(name: string, category?: string): (() => any) | undefined {
-    return FunctionRegistry.getFactory(name, category);
-}
-
-/**
- * Gets metadata for a specific function by name.
- */
-export function getFunctionMetadata(name: string, category?: string): FunctionMetadata | undefined {
-    return FunctionRegistry.getMetadata(name, category);
-}

package/src/parsing/functions/functions.ts

@@ -1,70 +0,0 @@
-import Function from "./function";
-import FunctionFactory from "./function_factory";
-import { FunctionDef } from "./function_metadata";
-
-/**
- * Built-in function that lists all registered functions with their metadata.
- * 
- * Can be used in FlowQuery to discover available functions:
- * - `WITH functions() AS funcs RETURN funcs` - returns all functions
- * - `WITH functions('aggregation') AS funcs RETURN funcs` - returns functions in a category
- * 
- * @example
- * ```
- * WITH functions() AS funcs 
- * UNWIND funcs AS func 
- * RETURN func.name, func.description
- * ```
- */
-@FunctionDef({
-    description: "Lists all registered functions with their metadata. Useful for discovering available functions and their documentation. Results include name, description, parameters, output schema, and usage examples.",
-    category: "scalar",
-    parameters: [
-        { name: "category", description: "Optional category to filter by (e.g., 'aggregation', 'string', 'math')", type: "string", required: false }
-    ],
-    output: { 
-        description: "Array of function metadata objects", 
-        type: "array",
-        items: {
-            type: "object",
-            properties: {
-                name: { description: "Function name", type: "string" },
-                description: { description: "What the function does", type: "string" },
-                category: { description: "Function category", type: "string" },
-                parameters: { description: "Array of parameter definitions", type: "array" },
-                output: { description: "Output schema", type: "object" },
-                examples: { description: "Usage examples", type: "array" }
-            }
-        }
-    },
-    examples: [
-        "WITH functions() AS funcs RETURN funcs",
-        "WITH functions('aggregation') AS funcs UNWIND funcs AS f RETURN f.name, f.description"
-    ]
-})
-class Functions extends Function {
-    constructor() {
-        super("functions");
-        this._expectedParameterCount = null; // 0 or 1 parameter
-    }
-
-    public value(): any {
-        const children = this.getChildren();
-        
-        if (children.length === 0) {
-            // Return all functions
-            return FunctionFactory.listFunctions();
-        } else if (children.length === 1) {
-            // Filter by category
-            const category = children[0].value();
-            if (typeof category === 'string') {
-                return FunctionFactory.listFunctions({ category });
-            }
-            throw new Error("functions() category parameter must be a string");
-        } else {
-            throw new Error("functions() takes 0 or 1 parameters");
-        }
-    }
-}
-
-export default Functions;

package/src/parsing/functions/head.ts

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

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

@@ -1,40 +0,0 @@
-import ASTNode from "../ast_node";
-import String from "../expressions/string";
-import Function from "./function";
-import { FunctionDef } from "./function_metadata";
-
-@FunctionDef({
-    description: "Joins an array of strings with a delimiter",
-    category: "scalar",
-    parameters: [
-        { name: "array", description: "Array of values to join", type: "array" },
-        { 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, ',')"],
-})
-class Join extends Function {
-    constructor() {
-        super("join");
-        this._expectedParameterCount = 2;
-    }
-    public set parameters(nodes: ASTNode[]) {
-        if (nodes.length === 1) {
-            nodes.push(new String(""));
-        }
-        super.parameters = nodes;
-    }
-    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");
-        }
-        return array.join(delimiter);
-    }
-}
-
-export default Join;

package/src/parsing/functions/keys.ts

@@ -1,29 +0,0 @@
-import Function from "./function";
-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" }],
-    output: { description: "Array of keys", type: "array", example: "['name', 'age']" },
-    examples: ["WITH { name: 'Alice', age: 30 } AS obj RETURN keys(obj)"],
-})
-class Keys extends Function {
-    constructor() {
-        super("keys");
-        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("keys() expects an object, not an array or primitive");
-        }
-        return Object.keys(obj);
-    }
-}
-
-export default Keys;

package/src/parsing/functions/last.ts

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

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

package/src/parsing/functions/localtime.ts

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

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