flowquery 1.0.6 → 1.0.7

package/src/index.browser.ts

@@ -7,100 +7,14 @@
  */
 
 import {default as FlowQuery} from "./compute/runner";
-import FunctionFactory, { FunctionCreator, AsyncDataProvider } from "./parsing/functions/function_factory";
+import FunctionFactory from "./parsing/functions/function_factory";
 import { 
     FunctionMetadata, 
     ParameterSchema, 
-    OutputSchema,
-    RegisterFunctionOptions,
-    RegisterAsyncProviderOptions 
+    OutputSchema
 } from "./parsing/functions/function_metadata";
 import Function from "./parsing/functions/function";
 
-/**
- * Register a synchronous plugin function.
- * 
- * @param name - The function name
- * @param factoryOrOptions - Factory function or options object with metadata
- * 
- * @example
- * ```javascript
- * // Simple registration
- * FlowQuery.registerFunction("uppercase", () => new MyUpperCaseFunction());
- * 
- * // Registration with metadata for LLM consumption
- * FlowQuery.registerFunction("uppercase", {
- *     factory: () => new MyUpperCaseFunction(),
- *     metadata: {
- *         name: "uppercase",
- *         description: "Converts a string to uppercase",
- *         category: "string",
- *         parameters: [{ name: "text", description: "String to convert", type: "string" }],
- *         output: { description: "Uppercase string", type: "string" },
- *         examples: ["WITH 'hello' AS s RETURN uppercase(s)"]
- *     }
- * });
- * ```
- */
-FlowQuery.registerFunction = function(name: string, factoryOrOptions: FunctionCreator | RegisterFunctionOptions): void {
-    FunctionFactory.register(name, factoryOrOptions);
-};
-
-/**
- * Unregister a synchronous plugin function.
- * 
- * @param name - The function name
- */
-FlowQuery.unregisterFunction = function(name: string): void {
-    FunctionFactory.unregister(name);
-};
-
-/**
- * Register an async data provider function for use in LOAD operations.
- * 
- * @param name - The function name
- * @param providerOrOptions - Async provider or options object with metadata
- * 
- * @example
- * ```javascript
- * // Registration with metadata for LLM consumption
- * FlowQuery.registerAsyncProvider("fetchUsers", {
- *     provider: async function* (endpoint) {
- *         const response = await fetch(endpoint);
- *         const data = await response.json();
- *         for (const item of data) yield item;
- *     },
- *     metadata: {
- *         name: "fetchUsers",
- *         description: "Fetches user data from an API",
- *         category: "data",
- *         parameters: [{ name: "endpoint", description: "API URL", type: "string" }],
- *         output: { 
- *             description: "User object", 
- *             type: "object",
- *             properties: {
- *                 id: { description: "User ID", type: "number" },
- *                 name: { description: "User name", type: "string" }
- *             }
- *         },
- *         examples: ["LOAD JSON FROM fetchUsers('https://api.example.com/users') AS user"]
- *     }
- * });
- * ```
- */
-FlowQuery.registerAsyncProvider = function(name: string, providerOrOptions: AsyncDataProvider | RegisterAsyncProviderOptions): void {
-    FunctionFactory.registerAsyncProvider(name, providerOrOptions);
-};
-
-/**
- * Unregister an async data provider function.
- * 
- * @param name - The function name
- */
-FlowQuery.unregisterAsyncProvider = function(name: string): void {
-    FunctionFactory.unregisterAsyncProvider(name);
-};
-
 /**
  * List all registered functions with their metadata.
  * 

package/src/index.node.ts

@@ -7,100 +7,14 @@
  */
 
 import {default as FlowQuery} from "./compute/runner";
-import FunctionFactory, { FunctionCreator, AsyncDataProvider } from "./parsing/functions/function_factory";
+import FunctionFactory, { AsyncDataProvider } from "./parsing/functions/function_factory";
 import { 
     FunctionMetadata, 
     ParameterSchema, 
-    OutputSchema,
-    RegisterFunctionOptions,
-    RegisterAsyncProviderOptions 
+    OutputSchema
 } from "./parsing/functions/function_metadata";
 import Function from "./parsing/functions/function";
 
-/**
- * Register a synchronous plugin function.
- * 
- * @param name - The function name
- * @param factoryOrOptions - Factory function or options object with metadata
- * 
- * @example
- * ```javascript
- * // Simple registration
- * FlowQuery.registerFunction("uppercase", () => new MyUpperCaseFunction());
- * 
- * // Registration with metadata for LLM consumption
- * FlowQuery.registerFunction("uppercase", {
- *     factory: () => new MyUpperCaseFunction(),
- *     metadata: {
- *         name: "uppercase",
- *         description: "Converts a string to uppercase",
- *         category: "string",
- *         parameters: [{ name: "text", description: "String to convert", type: "string" }],
- *         output: { description: "Uppercase string", type: "string" },
- *         examples: ["WITH 'hello' AS s RETURN uppercase(s)"]
- *     }
- * });
- * ```
- */
-FlowQuery.registerFunction = function(name: string, factoryOrOptions: FunctionCreator | RegisterFunctionOptions): void {
-    FunctionFactory.register(name, factoryOrOptions);
-};
-
-/**
- * Unregister a synchronous plugin function.
- * 
- * @param name - The function name
- */
-FlowQuery.unregisterFunction = function(name: string): void {
-    FunctionFactory.unregister(name);
-};
-
-/**
- * Register an async data provider function for use in LOAD operations.
- * 
- * @param name - The function name
- * @param providerOrOptions - Async provider or options object with metadata
- * 
- * @example
- * ```javascript
- * // Registration with metadata for LLM consumption
- * FlowQuery.registerAsyncProvider("fetchUsers", {
- *     provider: async function* (endpoint) {
- *         const response = await fetch(endpoint);
- *         const data = await response.json();
- *         for (const item of data) yield item;
- *     },
- *     metadata: {
- *         name: "fetchUsers",
- *         description: "Fetches user data from an API",
- *         category: "data",
- *         parameters: [{ name: "endpoint", description: "API URL", type: "string" }],
- *         output: { 
- *             description: "User object", 
- *             type: "object",
- *             properties: {
- *                 id: { description: "User ID", type: "number" },
- *                 name: { description: "User name", type: "string" }
- *             }
- *         },
- *         examples: ["LOAD JSON FROM fetchUsers('https://api.example.com/users') AS user"]
- *     }
- * });
- * ```
- */
-FlowQuery.registerAsyncProvider = function(name: string, providerOrOptions: AsyncDataProvider | RegisterAsyncProviderOptions): void {
-    FunctionFactory.registerAsyncProvider(name, providerOrOptions);
-};
-
-/**
- * Unregister an async data provider function.
- * 
- * @param name - The function name
- */
-FlowQuery.unregisterAsyncProvider = function(name: string): void {
-    FunctionFactory.unregisterAsyncProvider(name);
-};
-
 /**
  * List all registered functions with their metadata.
  * 
@@ -131,11 +45,8 @@ export {
     FlowQuery, 
     Function, 
     FunctionFactory, 
-    FunctionCreator, 
     AsyncDataProvider,
     FunctionMetadata,
     ParameterSchema,
-    OutputSchema,
-    RegisterFunctionOptions,
-    RegisterAsyncProviderOptions
+    OutputSchema
 };

package/src/parsing/functions/function_factory.ts

@@ -17,27 +17,20 @@ import "./functions";
 import "./predicate_sum";
 import { 
     FunctionMetadata, 
-    RegisterFunctionOptions, 
-    RegisterAsyncProviderOptions,
     getRegisteredFunctionMetadata,
     getFunctionMetadata,
-    getRegisteredFunctionFactory
+    getRegisteredFunctionFactory,
+    getRegisteredAsyncProvider,
+    AsyncDataProvider
 } from "./function_metadata";
 
-/**
- * Type for synchronous function factories.
- */
-export type FunctionCreator = () => Function;
-
-/**
- * Type for async data provider functions used in LOAD operations.
- * These functions can yield data asynchronously.
- */
-export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
+// 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.
  * 
@@ -48,113 +41,6 @@ export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, un
  * ```
  */
 class FunctionFactory {
-    /**
-     * Registry for plugin functions (synchronous).
-     */
-    private static plugins: Map<string, FunctionCreator> = new Map();
-
-    /**
-     * Registry for async data provider functions used in LOAD operations.
-     */
-    private static asyncProviders: Map<string, AsyncDataProvider> = new Map();
-
-    /**
-     * Registry for function metadata (both sync and async).
-     */
-    private static metadata: Map<string, FunctionMetadata> = new Map();
-
-    /**
-     * Registers a synchronous plugin function.
-     * 
-     * @param name - The function name (will be lowercased)
-     * @param factoryOrOptions - Factory function or options object with metadata
-     */
-    public static register(name: string, factoryOrOptions: FunctionCreator | RegisterFunctionOptions): void {
-        const lowerName = name.toLowerCase();
-        if (typeof factoryOrOptions === 'function') {
-            FunctionFactory.plugins.set(lowerName, factoryOrOptions);
-        } else {
-            FunctionFactory.plugins.set(lowerName, factoryOrOptions.factory);
-            FunctionFactory.metadata.set(lowerName, {
-                ...factoryOrOptions.metadata,
-                name: lowerName,
-                isAsyncProvider: false
-            });
-        }
-    }
-
-    /**
-     * Unregisters a synchronous plugin function.
-     * 
-     * @param name - The function name to unregister
-     */
-    public static unregister(name: string): void {
-        const lowerName = name.toLowerCase();
-        FunctionFactory.plugins.delete(lowerName);
-        FunctionFactory.metadata.delete(lowerName);
-    }
-
-    /**
-     * Registers an async data provider function for use in LOAD operations.
-     * 
-     * @param name - The function name (will be lowercased)
-     * @param providerOrOptions - Async provider or options object with metadata
-     * 
-     * @example
-     * ```typescript
-     * // Register with metadata for LLM consumption
-     * FunctionFactory.registerAsyncProvider("fetchUsers", {
-     *     provider: async function* (endpoint: string) {
-     *         const response = await fetch(endpoint);
-     *         const data = await response.json();
-     *         for (const item of data) {
-     *             yield item;
-     *         }
-     *     },
-     *     metadata: {
-     *         name: "fetchUsers",
-     *         description: "Fetches user data from an API endpoint",
-     *         parameters: [
-     *             { name: "endpoint", description: "API endpoint URL", type: "string" }
-     *         ],
-     *         output: {
-     *             description: "User objects",
-     *             type: "object",
-     *             properties: {
-     *                 id: { description: "User ID", type: "number" },
-     *                 name: { description: "User name", type: "string" }
-     *             }
-     *         },
-     *         examples: ["LOAD JSON FROM fetchUsers('https://api.example.com/users') AS user"]
-     *     }
-     * });
-     * ```
-     */
-    public static registerAsyncProvider(name: string, providerOrOptions: AsyncDataProvider | RegisterAsyncProviderOptions): void {
-        const lowerName = name.toLowerCase();
-        if (typeof providerOrOptions === 'function') {
-            FunctionFactory.asyncProviders.set(lowerName, providerOrOptions);
-        } else {
-            FunctionFactory.asyncProviders.set(lowerName, providerOrOptions.provider);
-            FunctionFactory.metadata.set(lowerName, {
-                ...providerOrOptions.metadata,
-                name: lowerName,
-                isAsyncProvider: true
-            });
-        }
-    }
-
-    /**
-     * Unregisters an async data provider function.
-     * 
-     * @param name - The function name to unregister
-     */
-    public static unregisterAsyncProvider(name: string): void {
-        const lowerName = name.toLowerCase();
-        FunctionFactory.asyncProviders.delete(lowerName);
-        FunctionFactory.metadata.delete(lowerName);
-    }
-
     /**
      * Gets an async data provider by name.
      * 
@@ -162,7 +48,7 @@ class FunctionFactory {
      * @returns The async data provider, or undefined if not found
      */
     public static getAsyncProvider(name: string): AsyncDataProvider | undefined {
-        return FunctionFactory.asyncProviders.get(name.toLowerCase());
+        return getRegisteredAsyncProvider(name.toLowerCase());
     }
 
     /**
@@ -172,7 +58,7 @@ class FunctionFactory {
      * @returns True if the function is an async data provider
      */
     public static isAsyncProvider(name: string): boolean {
-        return FunctionFactory.asyncProviders.has(name.toLowerCase());
+        return getRegisteredAsyncProvider(name.toLowerCase()) !== undefined;
     }
 
     /**
@@ -182,45 +68,26 @@ class FunctionFactory {
      * @returns The function metadata, or undefined if not found
      */
     public static getMetadata(name: string): FunctionMetadata | undefined {
-        const lowerName = name.toLowerCase();
-        // Check plugin metadata first
-        if (FunctionFactory.metadata.has(lowerName)) {
-            return FunctionFactory.metadata.get(lowerName);
-        }
-        // Fall back to decorator-registered metadata
-        return getFunctionMetadata(lowerName);
+        return getFunctionMetadata(name.toLowerCase());
     }
 
     /**
      * Lists all registered functions with their metadata.
-     * Includes both built-in and plugin functions.
      * 
      * @param options - Optional filter options
      * @returns Array of function metadata
      */
     public static listFunctions(options?: { 
         category?: string; 
-        includeBuiltins?: boolean;
         asyncOnly?: boolean;
         syncOnly?: boolean;
     }): FunctionMetadata[] {
         const result: FunctionMetadata[] = [];
-        const includeBuiltins = options?.includeBuiltins !== false;
-        
-        // Add decorator-registered functions (built-ins)
-        if (includeBuiltins) {
-            for (const meta of getRegisteredFunctionMetadata()) {
-                if (options?.category && meta.category !== options.category) continue;
-                if (options?.asyncOnly) continue; // Built-ins are sync
-                result.push(meta);
-            }
-        }
         
-        // Add plugin functions
-        for (const [name, meta] of FunctionFactory.metadata) {
+        for (const meta of getRegisteredFunctionMetadata()) {
             if (options?.category && meta.category !== options.category) continue;
-            if (options?.asyncOnly && !meta.isAsyncProvider) continue;
-            if (options?.syncOnly && meta.isAsyncProvider) continue;
+            if (options?.asyncOnly && meta.category !== 'async') continue;
+            if (options?.syncOnly && meta.category === 'async') continue;
             result.push(meta);
         }
         
@@ -233,10 +100,7 @@ class FunctionFactory {
      * @returns Array of function names
      */
     public static listFunctionNames(): string[] {
-        const builtinNames = getRegisteredFunctionMetadata().map(m => m.name);
-        const pluginNames = Array.from(FunctionFactory.plugins.keys());
-        const asyncNames = Array.from(FunctionFactory.asyncProviders.keys());
-        return [...new Set([...builtinNames, ...pluginNames, ...asyncNames])];
+        return getRegisteredFunctionMetadata().map(m => m.name);
     }
 
     /**
@@ -259,11 +123,6 @@ class FunctionFactory {
     public static create(name: string): Function {
         const lowerName = name.toLowerCase();
         
-        // Check plugin registry first (allows overriding built-ins)
-        if (FunctionFactory.plugins.has(lowerName)) {
-            return FunctionFactory.plugins.get(lowerName)!();
-        }
-
         // Check decorator-registered functions (built-ins use @FunctionDef)
         const decoratorFactory = getRegisteredFunctionFactory(lowerName);
         if (decoratorFactory) {

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,28 @@ 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.
+ * Registry for function metadata collected via decorators.
  */
-export interface RegisterFunctionOptions {
-    /** Factory function that creates the Function instance */
-    factory: () => any;
-    /** Function metadata for documentation */
-    metadata: FunctionMetadata;
-}
+const functionMetadataRegistry: Map<string, FunctionMetadata> = new Map();
 
 /**
- * Options for registering an async data provider with metadata.
+ * Registry for function factories collected via decorators.
+ * Allows @FunctionDef to automatically register functions for instantiation.
  */
-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;
-}
+const functionFactoryRegistry: Map<string, () => any> = new Map();
 
 /**
- * Registry for function metadata collected via decorators.
+ * Type for async data provider functions used in LOAD operations.
  */
-const functionMetadataRegistry: Map<string, FunctionMetadata> = new Map();
+export type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
 
 /**
- * Registry for function factories collected via decorators.
- * Allows @FunctionDef to automatically register functions for instantiation.
+ * Registry for async data providers collected via decorators.
  */
-const functionFactoryRegistry: Map<string, () => any> = new Map();
+const asyncProviderRegistry: Map<string, AsyncDataProvider> = new Map();
 
 /**
  * Decorator options - metadata without the name (derived from class).
@@ -106,13 +94,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,10 +115,48 @@ 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 {
+        // 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();
@@ -212,3 +244,14 @@ export function getFunctionMetadata(name: string, category?: string): FunctionMe
     
     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());
+}