flowquery 1.0.5 → 1.0.7

package/src/parsing/functions/function_metadata.ts

@@ -1,3 +1,10 @@
+/**
+ * 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.
@@ -47,192 +54,204 @@ export interface FunctionMetadata {
     name: string;
     /** Human-readable description of what the function does */
     description: string;
-    /** Category for grouping functions (e.g., "aggregation", "string", "data") */
-    category?: 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[];
-    /** Whether this is an async data provider for LOAD operations */
-    isAsyncProvider?: boolean;
     /** Additional notes or caveats */
     notes?: string;
 }
 
 /**
- * Options for registering a sync function with metadata.
+ * Registry for function metadata collected via decorators.
+ */
+const functionMetadataRegistry: Map<string, FunctionMetadata> = new Map();
+
+/**
+ * Registry for function factories collected via decorators.
+ * Allows @FunctionDef to automatically register functions for instantiation.
+ */
+const functionFactoryRegistry: Map<string, () => any> = new Map();
+
+/**
+ * Type for async data provider functions used in LOAD operations.
+ */
+export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
+
+/**
+ * Registry for async data providers collected via decorators.
+ */
+const asyncProviderRegistry: Map<string, AsyncDataProvider> = new Map();
+
+/**
+ * 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 `fetch` method that returns
+ * an AsyncGenerator. The function name is derived from the class name (removing 'Loader' suffix
+ * if present) and converted to camelCase.
+ * 
+ * @param options - Function metadata (excluding name)
+ * @returns Class decorator
+ * 
+ * @example
+ * ```typescript
+ * // Regular function
+ * @FunctionDef({
+ *     description: "Calculates the sum of numeric values",
+ *     category: "aggregate",
+ *     parameters: [{ name: "value", description: "Numeric value to sum", type: "number" }],
+ *     output: { description: "Sum of all values", type: "number", example: 150 },
+ *     examples: ["WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN sum(n)"]
+ * })
+ * class Sum extends AggregateFunction { ... }
+ * 
+ * // Async data provider
+ * @FunctionDef({
+ *     description: "Fetches random cat facts from the Cat Facts API",
+ *     category: "async",
+ *     parameters: [{ name: "count", description: "Number of facts", type: "number", required: false, default: 1 }],
+ *     output: { description: "Cat fact object", type: "object" },
+ *     examples: ["LOAD JSON FROM catFacts(5) AS fact RETURN fact.text"]
+ * })
+ * class CatFactsLoader {
+ *     async *fetch(count: number = 1): AsyncGenerator<any> { ... }
+ * }
+ * ```
+ */
+export function FunctionDef(options: FunctionDefOptions) {
+    return function <T extends new (...args: any[]) => any>(constructor: T): T {
+        // Handle async providers differently
+        if (options.category === 'async') {
+            // Derive the function name from the class name
+            // Remove 'Loader' suffix if present and convert to lowercase for registry
+            let baseName = constructor.name;
+            if (baseName.endsWith('Loader')) {
+                baseName = baseName.slice(0, -6);
+            }
+            // Keep display name in camelCase, but use lowercase for registry keys
+            const displayName = baseName.charAt(0).toLowerCase() + baseName.slice(1);
+            const registryKey = displayName.toLowerCase();
+            
+            // Register metadata with display name
+            const metadata: FunctionMetadata = {
+                name: displayName,
+                ...options
+            };
+            functionMetadataRegistry.set(registryKey, metadata);
+            
+            // Register the async provider (wraps the class's fetch method)
+            asyncProviderRegistry.set(registryKey, (...args: any[]) => new constructor().fetch(...args));
+            
+            return constructor;
+        }
+        
+        // Regular function handling
+        // Create an instance to get the function name from super() call
+        const instance = new constructor();
+        const baseName = instance.name?.toLowerCase() || constructor.name.toLowerCase();
+        
+        // Use category-qualified key to avoid collisions (e.g., sum vs sum:predicate)
+        // but store the display name without the qualifier
+        const displayName = baseName.includes(':') ? baseName.split(':')[0] : baseName;
+        const registryKey = options.category ? `${displayName}:${options.category}` : displayName;
+        
+        // Register metadata with display name but category-qualified key
+        const metadata: FunctionMetadata = {
+            name: displayName,
+            ...options
+        };
+        functionMetadataRegistry.set(registryKey, metadata);
+        
+        // Register factory function for automatic instantiation
+        // Only register to the simple name if no collision exists (predicate functions use qualified keys)
+        if (options.category !== 'predicate') {
+            functionFactoryRegistry.set(displayName, () => new constructor());
+        }
+        functionFactoryRegistry.set(registryKey, () => new constructor());
+        
+        return constructor;
+    };
+}
+
+/**
+ * Gets all registered function metadata from decorators.
+ * 
+ * @returns Array of function metadata
  */
-export interface RegisterFunctionOptions {
-    /** Factory function that creates the Function instance */
-    factory: () => any;
-    /** Function metadata for documentation */
-    metadata: FunctionMetadata;
+export function getRegisteredFunctionMetadata(): FunctionMetadata[] {
+    return Array.from(functionMetadataRegistry.values());
 }
 
 /**
- * Options for registering an async data provider with metadata.
+ * Gets a registered function factory by name.
+ * Used by FunctionFactory to instantiate decorator-registered functions.
+ * 
+ * @param name - Function name (case-insensitive)
+ * @param category - Optional category to disambiguate (e.g., 'predicate')
+ * @returns Factory function or undefined
  */
-export interface RegisterAsyncProviderOptions {
-    /** Async generator or function that returns data */
-    provider: (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
-    /** Function metadata for documentation */
-    metadata: FunctionMetadata;
+export function getRegisteredFunctionFactory(name: string, category?: string): (() => any) | undefined {
+    const lowerName = name.toLowerCase();
+    
+    // If category specified, look for exact match
+    if (category) {
+        return functionFactoryRegistry.get(`${lowerName}:${category}`);
+    }
+    
+    // Try direct match first
+    if (functionFactoryRegistry.has(lowerName)) {
+        return functionFactoryRegistry.get(lowerName);
+    }
+    
+    return undefined;
 }
 
 /**
- * Built-in function metadata definitions.
+ * Gets metadata for a specific function by name.
+ * If multiple functions share the same name (e.g., aggregate vs predicate),
+ * optionally specify the category to get the specific one.
+ * 
+ * @param name - Function name (case-insensitive)
+ * @param category - Optional category to disambiguate
+ * @returns Function metadata or undefined
  */
-export const BUILTIN_FUNCTION_METADATA: FunctionMetadata[] = [
-    {
-        name: "sum",
-        description: "Calculates the sum of numeric values across grouped rows",
-        category: "aggregation",
-        parameters: [
-            { name: "value", description: "Numeric value to sum", type: "number" }
-        ],
-        output: { description: "Sum of all values", type: "number", example: 150 },
-        examples: ["WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN sum(n)"]
-    },
-    {
-        name: "avg",
-        description: "Calculates the average of numeric values across grouped rows",
-        category: "aggregation",
-        parameters: [
-            { name: "value", description: "Numeric value to average", type: "number" }
-        ],
-        output: { description: "Average of all values", type: "number", example: 50 },
-        examples: ["WITH [10, 20, 30] AS nums UNWIND nums AS n RETURN avg(n)"]
-    },
-    {
-        name: "collect",
-        description: "Collects values into an array across grouped rows",
-        category: "aggregation",
-        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)"]
-    },
-    {
-        name: "range",
-        description: "Generates an array of sequential integers",
-        category: "generator",
-        parameters: [
-            { name: "start", description: "Starting number (inclusive)", type: "number" },
-            { name: "end", description: "Ending number (inclusive)", type: "number" }
-        ],
-        output: { description: "Array of integers from start to end", type: "array", items: { type: "number" }, example: [1, 2, 3, 4, 5] },
-        examples: ["WITH range(1, 5) AS nums RETURN nums"]
-    },
-    {
-        name: "rand",
-        description: "Generates a random number between 0 and 1",
-        category: "generator",
-        parameters: [],
-        output: { description: "Random number between 0 and 1", type: "number", example: 0.7234 },
-        examples: ["WITH rand() AS r RETURN r"]
-    },
-    {
-        name: "round",
-        description: "Rounds a number to the nearest integer",
-        category: "math",
-        parameters: [
-            { name: "value", description: "Number to round", type: "number" }
-        ],
-        output: { description: "Rounded integer", type: "number", example: 4 },
-        examples: ["WITH 3.7 AS n RETURN round(n)"]
-    },
-    {
-        name: "split",
-        description: "Splits a string into an array by a delimiter",
-        category: "string",
-        parameters: [
-            { name: "text", description: "String to split", type: "string" },
-            { name: "delimiter", description: "Delimiter to split by", type: "string" }
-        ],
-        output: { description: "Array of string parts", type: "array", items: { type: "string" }, example: ["a", "b", "c"] },
-        examples: ["WITH 'a,b,c' AS s RETURN split(s, ',')"]
-    },
-    {
-        name: "join",
-        description: "Joins an array of strings with a delimiter",
-        category: "string",
-        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, ',')"]
-    },
-    {
-        name: "replace",
-        description: "Replaces occurrences of a pattern in a string",
-        category: "string",
-        parameters: [
-            { name: "text", description: "Source string", type: "string" },
-            { name: "pattern", description: "Pattern to find", type: "string" },
-            { name: "replacement", description: "Replacement string", type: "string" }
-        ],
-        output: { description: "String with replacements", type: "string", example: "hello world" },
-        examples: ["WITH 'hello there' AS s RETURN replace(s, 'there', 'world')"]
-    },
-    {
-        name: "stringify",
-        description: "Converts a value to its JSON string representation",
-        category: "conversion",
-        parameters: [
-            { name: "value", description: "Value to stringify", type: "any" }
-        ],
-        output: { description: "JSON string", type: "string", example: "{\"a\":1}" },
-        examples: ["WITH {a: 1} AS obj RETURN stringify(obj)"]
-    },
-    {
-        name: "tojson",
-        description: "Parses a JSON string into an object",
-        category: "conversion",
-        parameters: [
-            { name: "text", description: "JSON string to parse", type: "string" }
-        ],
-        output: { description: "Parsed object or array", type: "object", example: { a: 1 } },
-        examples: ["WITH '{\"a\": 1}' AS s RETURN tojson(s)"]
-    },
-    {
-        name: "size",
-        description: "Returns the length of an array or string",
-        category: "utility",
-        parameters: [
-            { name: "value", description: "Array or string to measure", type: "array" }
-        ],
-        output: { description: "Length of the input", type: "number", example: 3 },
-        examples: ["WITH [1, 2, 3] AS arr RETURN size(arr)"]
-    },
-    {
-        name: "functions",
-        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: "introspection",
-        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"
-        ]
+export function getFunctionMetadata(name: string, category?: string): FunctionMetadata | undefined {
+    const lowerName = name.toLowerCase();
+    
+    // If category specified, look for exact match
+    if (category) {
+        return functionMetadataRegistry.get(`${lowerName}:${category}`);
     }
-];
+    
+    // Otherwise, first try direct match (for functions without category conflicts)
+    // Then search for any function with matching name
+    for (const [key, meta] of functionMetadataRegistry) {
+        if (meta.name === lowerName) {
+            return meta;
+        }
+    }
+    
+    return undefined;
+}
+
+/**
+ * Gets a registered async data provider by name.
+ * Used by FunctionFactory to get decorator-registered async providers.
+ * 
+ * @param name - Function name (case-insensitive)
+ * @returns Async data provider or undefined
+ */
+export function getRegisteredAsyncProvider(name: string): AsyncDataProvider | undefined {
+    return asyncProviderRegistry.get(name.toLowerCase());
+}

package/src/parsing/functions/functions.ts

@@ -1,5 +1,6 @@
 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.
@@ -15,6 +16,32 @@ import FunctionFactory from "./function_factory";
  * 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");

package/src/parsing/functions/join.ts

@@ -1,7 +1,18 @@
 import ASTNode from "../ast_node";
 import Function from "./function";
 import String from "../expressions/string";
+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");

package/src/parsing/functions/predicate_function.ts

@@ -13,6 +13,10 @@ class PredicateFunction extends ASTNode {
         this._name = name;
     }
 
+    public get name(): string {
+        return this._name;
+    }
+
     protected get reference(): Reference {
         return this.firstChild() as Reference;
     }

package/src/parsing/functions/predicate_sum.ts

@@ -1,5 +1,18 @@
 import PredicateFunction from "./predicate_function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Calculates the sum of values in an array with optional filtering. Uses list comprehension syntax: sum(variable IN array [WHERE condition] | expression)",
+    category: "predicate",
+    parameters: [
+        { name: "variable", description: "Variable name to bind each element", type: "string" },
+        { name: "array", description: "Array to iterate over", type: "array" },
+        { name: "expression", description: "Expression to sum for each element", type: "any" },
+        { name: "where", description: "Optional filter condition", type: "boolean", required: false }
+    ],
+    output: { description: "Sum of the evaluated expressions", type: "number", example: 6 },
+    examples: ["WITH [1, 2, 3] AS nums RETURN sum(n IN nums | n)", "WITH [1, 2, 3, 4] AS nums RETURN sum(n IN nums WHERE n > 1 | n * 2)"]
+})
 class PredicateSum extends PredicateFunction {
     constructor() {
         super("sum");

package/src/parsing/functions/rand.ts

@@ -1,5 +1,13 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Generates a random number between 0 and 1",
+    category: "scalar",
+    parameters: [],
+    output: { description: "Random number between 0 and 1", type: "number", example: 0.7234 },
+    examples: ["WITH rand() AS r RETURN r"]
+})
 class Rand extends Function {
     constructor() {
         super("rand");

package/src/parsing/functions/range.ts

@@ -1,5 +1,16 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Generates an array of sequential integers",
+    category: "scalar",
+    parameters: [
+        { name: "start", description: "Starting number (inclusive)", type: "number" },
+        { name: "end", description: "Ending number (inclusive)", type: "number" }
+    ],
+    output: { description: "Array of integers from start to end", type: "array", items: { type: "number" }, example: [1, 2, 3, 4, 5] },
+    examples: ["WITH range(1, 5) AS nums RETURN nums"]
+})
 class Range extends Function {
     constructor() {
         super("range");

package/src/parsing/functions/replace.ts

@@ -1,5 +1,17 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Replaces occurrences of a pattern in a string",
+    category: "scalar",
+    parameters: [
+        { name: "text", description: "Source string", type: "string" },
+        { name: "pattern", description: "Pattern to find", type: "string" },
+        { name: "replacement", description: "Replacement string", type: "string" }
+    ],
+    output: { description: "String with replacements", type: "string", example: "hello world" },
+    examples: ["WITH 'hello there' AS s RETURN replace(s, 'there', 'world')"]
+})
 class Replace extends Function {
     constructor() {
         super("replace");

package/src/parsing/functions/round.ts

@@ -1,5 +1,15 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Rounds a number to the nearest integer",
+    category: "scalar",
+    parameters: [
+        { name: "value", description: "Number to round", type: "number" }
+    ],
+    output: { description: "Rounded integer", type: "number", example: 4 },
+    examples: ["WITH 3.7 AS n RETURN round(n)"]
+})
 class Round extends Function {
     constructor() {
         super("round");

package/src/parsing/functions/size.ts

@@ -1,5 +1,15 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Returns the length of an array or string",
+    category: "scalar",
+    parameters: [
+        { name: "value", description: "Array or string to measure", type: "array" }
+    ],
+    output: { description: "Length of the input", type: "number", example: 3 },
+    examples: ["WITH [1, 2, 3] AS arr RETURN size(arr)"]
+})
 class Size extends Function {
     constructor() {
         super("size");

package/src/parsing/functions/split.ts

@@ -1,7 +1,18 @@
 import ASTNode from "../ast_node";
 import Function from "./function";
 import String from "../expressions/string";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Splits a string into an array by a delimiter",
+    category: "scalar",
+    parameters: [
+        { name: "text", description: "String to split", type: "string" },
+        { name: "delimiter", description: "Delimiter to split by", type: "string" }
+    ],
+    output: { description: "Array of string parts", type: "array", items: { type: "string" }, example: ["a", "b", "c"] },
+    examples: ["WITH 'a,b,c' AS s RETURN split(s, ',')"]
+})
 class Split extends Function {
     constructor() {
         super("split");

package/src/parsing/functions/stringify.ts

@@ -1,7 +1,17 @@
 import ASTNode from "../ast_node";
 import Function from "./function";
 import Number from "../expressions/number";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Converts a value to its JSON string representation",
+    category: "scalar",
+    parameters: [
+        { name: "value", description: "Value to stringify", type: "any" }
+    ],
+    output: { description: "JSON string", type: "string", example: "{\"a\":1}" },
+    examples: ["WITH {a: 1} AS obj RETURN stringify(obj)"]
+})
 class Stringify extends Function {
     constructor() {
         super("stringify");

package/src/parsing/functions/sum.ts

@@ -1,5 +1,6 @@
 import AggregateFunction from "./aggregate_function";
 import ReducerElement from "./reducer_element";
+import { FunctionDef } from "./function_metadata";
 
 class SumReducerElement extends ReducerElement {
     private _value: any = null;
@@ -15,6 +16,15 @@ class SumReducerElement extends ReducerElement {
     }
 }
 
+@FunctionDef({
+    description: "Calculates the sum of numeric values across grouped rows",
+    category: "aggregate",
+    parameters: [
+        { name: "value", description: "Numeric value to sum", type: "number" }
+    ],
+    output: { description: "Sum of all values", type: "number", example: 150 },
+    examples: ["WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN sum(n)"]
+})
 class Sum extends AggregateFunction {
     constructor() {
         super("sum");

package/src/parsing/functions/to_json.ts

@@ -1,5 +1,15 @@
 import Function from "./function";
+import { FunctionDef } from "./function_metadata";
 
+@FunctionDef({
+    description: "Parses a JSON string into an object",
+    category: "scalar",
+    parameters: [
+        { name: "text", description: "JSON string to parse", type: "string" }
+    ],
+    output: { description: "Parsed object or array", type: "object", example: { a: 1 } },
+    examples: ["WITH '{\"a\": 1}' AS s RETURN tojson(s)"]
+})
 class ToJson extends Function {
     constructor() {
         super("tojson");

package/src/parsing/parser.ts

@@ -31,7 +31,6 @@ import AggregateFunction from "./functions/aggregate_function";
 import ObjectUtils from "../utils/object_utils";
 import PredicateFunction from "./functions/predicate_function";
 import Token from "../tokenization/token";
-import PredicateFunctionFactory from "./functions/predicate_function_factory";
 import FString from "./expressions/f_string";
 import String from "./expressions/string";
 import AggregatedWith from "./operations/aggregated_with";
@@ -617,7 +616,7 @@ class Parser extends BaseParser {
         if(this.token.value === null) {
             throw new Error('Expected identifier');
         }
-        const func = PredicateFunctionFactory.create(this.token.value);
+        const func = FunctionFactory.createPredicate(this.token.value);
         this.setNextToken();
         if(!this.token.isLeftParenthesis()) {
             throw new Error('Expected left parenthesis');