flowquery 1.0.6 → 1.0.8

package/src/parsing/functions/function_metadata.ts

@@ -3,7 +3,7 @@
  * Core categories: scalar, aggregate, predicate, async
  * Additional categories for organization: string, math, data, etc.
  */
-export type FunctionCategory = "scalar" | "aggregate" | "predicate" | "async" | "string" | "math" | "data" | "introspection" | string;
+export type FunctionCategory = "scalar" | "aggregate" | "predicate" | "async" | string;
 
 /**
  * Schema definition for function arguments and outputs.
@@ -54,8 +54,8 @@ export interface FunctionMetadata {
     name: string;
     /** Human-readable description of what the function does */
     description: string;
-    /** Category for grouping functions */
-    category?: FunctionCategory;
+    /** Category that determines function type and behavior */
+    category: FunctionCategory;
     /** Array of parameter schemas */
     parameters: ParameterSchema[];
     /** Output schema */
@@ -64,40 +64,75 @@ export interface FunctionMetadata {
     examples?: string[];
     /** Additional notes or caveats */
     notes?: string;
-    /** Whether this is an async data provider (for LOAD operations) */
-    isAsyncProvider?: boolean;
 }
 
 /**
- * Options for registering a sync function with metadata.
+ * Type for async data provider functions used in LOAD operations.
  */
-export interface RegisterFunctionOptions {
-    /** Factory function that creates the Function instance */
-    factory: () => any;
-    /** Function metadata for documentation */
-    metadata: FunctionMetadata;
-}
+export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
 
 /**
- * Options for registering an async data provider with metadata.
+ * Centralized registry for function metadata, factories, and async providers.
+ * Encapsulates all registration logic for the @FunctionDef decorator.
  */
-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;
-}
+class FunctionRegistry {
+    private static metadata: Map<string, FunctionMetadata> = new Map<string, FunctionMetadata>();
+    private static factories: Map<string, () => any> = new Map<string, () => any>();
+    private static asyncProviders: Map<string, AsyncDataProvider> = new Map<string, AsyncDataProvider>();
 
-/**
- * Registry for function metadata collected via decorators.
- */
-const functionMetadataRegistry: Map<string, FunctionMetadata> = new Map();
+    /** Derives a camelCase display name from a class name, removing 'Loader' suffix. */
+    private static deriveDisplayName(className: string): string {
+        const baseName: string = className.endsWith('Loader') ? className.slice(0, -6) : className;
+        return baseName.charAt(0).toLowerCase() + baseName.slice(1);
+    }
 
-/**
- * Registry for function factories collected via decorators.
- * Allows @FunctionDef to automatically register functions for instantiation.
- */
-const functionFactoryRegistry: Map<string, () => any> = new Map();
+    /** Registers an async data provider class. */
+    static registerAsync<T extends new (...args: any[]) => any>(constructor: T, options: FunctionDefOptions): void {
+        const displayName: string = this.deriveDisplayName(constructor.name);
+        const registryKey: string = displayName.toLowerCase();
+
+        this.metadata.set(registryKey, { name: displayName, ...options });
+        this.asyncProviders.set(registryKey, (...args: any[]) => new constructor().fetch(...args));
+    }
+
+    /** Registers a regular function class. */
+    static registerFunction<T extends new (...args: any[]) => any>(constructor: T, options: FunctionDefOptions): void {
+        const instance: any = new constructor();
+        const baseName: string = (instance.name?.toLowerCase() || constructor.name.toLowerCase());
+        const displayName: string = baseName.includes(':') ? baseName.split(':')[0] : baseName;
+        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 === 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);
+    }
+
+    static getAsyncProvider(name: string): AsyncDataProvider | undefined {
+        return this.asyncProviders.get(name.toLowerCase());
+    }
+}
 
 /**
  * Decorator options - metadata without the name (derived from class).
@@ -106,13 +141,19 @@ 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().
+ * 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",
@@ -121,94 +162,55 @@ export type FunctionDefOptions = Omit<FunctionMetadata, 'name'>;
  *     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 {
-        // 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());
+        if (options.category === 'async') {
+            FunctionRegistry.registerAsync(constructor, options);
+        } else {
+            FunctionRegistry.registerFunction(constructor, options);
         }
-        functionFactoryRegistry.set(registryKey, () => new constructor());
-        
         return constructor;
     };
 }
 
 /**
  * Gets all registered function metadata from decorators.
- * 
- * @returns Array of function metadata
  */
 export function getRegisteredFunctionMetadata(): FunctionMetadata[] {
-    return Array.from(functionMetadataRegistry.values());
+    return FunctionRegistry.getAllMetadata();
 }
 
 /**
  * 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 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;
+    return FunctionRegistry.getFactory(name, category);
 }
 
 /**
  * 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 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;
+    return FunctionRegistry.getMetadata(name, category);
+}
+
+/**
+ * Gets a registered async data provider by name.
+ */
+export function getRegisteredAsyncProvider(name: string): AsyncDataProvider | undefined {
+    return FunctionRegistry.getAsyncProvider(name);
 }