flowquery 1.0.3 → 1.0.6

package/README.md

@@ -143,6 +143,188 @@ post {
 return data
 ```
 
+## Extending FlowQuery with Custom Functions
+
+FlowQuery provides a plugin system that allows you to register custom functions. You can create scalar functions for synchronous operations or async providers for data loading.
+
+### Creating a Custom Scalar Function
+
+To create a custom function, extend the `Function` base class and register it with FlowQuery:
+
+```javascript
+const FlowQuery = require('flowquery').default;
+const { Function } = require('flowquery');
+
+// Create a custom function class
+class UpperCase extends Function {
+    constructor() {
+        super("uppercase");  // Function name used in queries
+        this._expectedParameterCount = 1;  // Number of required parameters
+    }
+    
+    // Implement the value() method to define the function's behavior
+    value() {
+        const input = this.getChildren()[0].value();  // Get first parameter
+        return String(input).toUpperCase();
+    }
+}
+
+// Register the function with FlowQuery
+FlowQuery.registerFunction("uppercase", () => new UpperCase());
+
+// Now use it in queries!
+async function main() {
+    const query = new FlowQuery("WITH 'hello world' AS greeting RETURN uppercase(greeting)");
+    await query.run();
+    console.log(query.results);  // [ { expr0: 'HELLO WORLD' } ]
+}
+```
+
+### Registering Functions with Metadata
+
+For better documentation and LLM integration, you can register functions with full metadata using the `@FunctionDef` decorator pattern:
+
+```javascript
+FlowQuery.registerFunction("uppercase", {
+    factory: () => new UpperCase(),
+    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",
+            example: "HELLO WORLD"
+        },
+        examples: ["WITH 'hello' AS s RETURN uppercase(s)"]
+    }
+});
+```
+
+### TypeScript: Using the @FunctionDef Decorator
+
+In TypeScript projects, you can use the `@FunctionDef` decorator directly on your function class. Import from the extensibility module for a clean API:
+
+```typescript
+import { Function, FunctionDef } from "flowquery/extensibility";
+
+@FunctionDef({
+    description: "Converts a string to uppercase",
+    category: "string",
+    parameters: [
+        { name: "text", description: "String to convert", type: "string" }
+    ],
+    output: { 
+        description: "Uppercase string", 
+        type: "string",
+        example: "HELLO WORLD"
+    },
+    examples: ["WITH 'hello' AS s RETURN uppercase(s)"]
+})
+class UpperCase extends Function {
+    constructor() {
+        super("uppercase");
+        this._expectedParameterCount = 1;
+    }
+    
+    public value(): string {
+        const input = this.getChildren()[0].value();
+        return String(input).toUpperCase();
+    }
+}
+```
+
+The decorator automatically registers the function with the FlowQuery function factory.
+
+The extensibility module (`flowquery/extensibility`) exports:
+- `Function` - Base class for scalar functions
+- `AggregateFunction` - Base class for aggregate functions (like `sum`, `avg`, `collect`)
+- `PredicateFunction` - Base class for predicate functions (like list comprehensions)
+- `FunctionDef` - Decorator for registering functions with metadata
+- `ReducerElement` - Helper class for aggregate function state
+- `FunctionFactory` - Direct access to the function factory for advanced usage
+
+### Creating Async Data Providers
+
+For functions that fetch data asynchronously (used with `LOAD ... FROM`), register an async provider:
+
+```javascript
+FlowQuery.registerAsyncProvider("fetchUsers", {
+    provider: async function* (endpoint) {
+        const response = await fetch(endpoint);
+        const data = await response.json();
+        for (const user of data) {
+            yield user;  // Yield each item individually
+        }
+    },
+    metadata: {
+        name: "fetchUsers",
+        description: "Fetches user data from an API endpoint",
+        category: "data",
+        parameters: [
+            { name: "endpoint", description: "API URL to fetch users from", 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"]
+    }
+});
+
+// Use in a query
+const query = new FlowQuery(`
+    LOAD JSON FROM fetchUsers('https://api.example.com/users') AS user
+    RETURN user.name, user.id
+`);
+await query.run();
+```
+
+### Listing and Querying Functions
+
+You can discover available functions programmatically:
+
+```javascript
+// List all functions
+const allFunctions = FlowQuery.listFunctions();
+
+// Filter by category
+const stringFunctions = FlowQuery.listFunctions({ category: "string" });
+const asyncFunctions = FlowQuery.listFunctions({ asyncOnly: true });
+
+// Get metadata for a specific function
+const sumMetadata = FlowQuery.getFunctionMetadata("sum");
+console.log(sumMetadata.description);  // "Calculates the sum of numeric values..."
+```
+
+You can also query functions from within FlowQuery itself:
+
+```cypher
+// List all available functions
+WITH functions() AS funcs
+UNWIND funcs AS f
+RETURN f.name, f.description, f.category
+```
+
+### Unregistering Functions
+
+To remove a registered function:
+
+```javascript
+// Unregister a sync function
+FlowQuery.unregisterFunction("uppercase");
+
+// Unregister an async provider
+FlowQuery.unregisterAsyncProvider("fetchUsers");
+```
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

package/dist/compute/runner.d.ts

@@ -0,0 +1,81 @@
+import { FunctionCreator, AsyncDataProvider } from "../parsing/functions/function_factory";
+import { FunctionMetadata, RegisterFunctionOptions, RegisterAsyncProviderOptions } from "../parsing/functions/function_metadata";
+import Function from "../parsing/functions/function";
+/**
+ * Executes a FlowQuery statement and retrieves the results.
+ *
+ * The Runner class parses a FlowQuery statement into an AST and executes it,
+ * managing the execution flow from the first operation to the final return statement.
+ *
+ * @example
+ * ```typescript
+ * const runner = new Runner("WITH 1 as x RETURN x");
+ * await runner.run();
+ * console.log(runner.results); // [{ x: 1 }]
+ * ```
+ */
+declare class Runner {
+    private first;
+    private last;
+    /**
+     * Register a synchronous plugin function.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static registerFunction: (name: string, factoryOrOptions: FunctionCreator | RegisterFunctionOptions) => void;
+    /**
+     * Unregister a synchronous plugin function.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static unregisterFunction: (name: string) => void;
+    /**
+     * Register an async data provider function for use in LOAD operations.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static registerAsyncProvider: (name: string, providerOrOptions: AsyncDataProvider | RegisterAsyncProviderOptions) => void;
+    /**
+     * Unregister an async data provider function.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static unregisterAsyncProvider: (name: string) => void;
+    /**
+     * List all registered functions with their metadata.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static listFunctions: (options?: {
+        category?: string;
+        asyncOnly?: boolean;
+        syncOnly?: boolean;
+    }) => FunctionMetadata[];
+    /**
+     * Get metadata for a specific function.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static getFunctionMetadata: (name: string) => FunctionMetadata | undefined;
+    /**
+     * Base Function class for creating custom plugin functions.
+     * Added dynamically in index.browser.ts / index.node.ts
+     */
+    static Function: typeof Function;
+    /**
+     * Creates a new Runner instance and parses the FlowQuery statement.
+     *
+     * @param statement - The FlowQuery statement to execute
+     * @throws {Error} If the statement is null, empty, or contains syntax errors
+     */
+    constructor(statement?: string | null);
+    /**
+     * Executes the parsed FlowQuery statement.
+     *
+     * @returns A promise that resolves when execution completes
+     * @throws {Error} If an error occurs during execution
+     */
+    run(): Promise<void>;
+    /**
+     * Gets the results from the executed statement.
+     *
+     * @returns The results from the last operation (typically a RETURN statement)
+     */
+    get results(): any;
+}
+export default Runner;
+//# sourceMappingURL=runner.d.ts.map

package/dist/compute/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AACjI,OAAO,QAAQ,MAAM,+BAA+B,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,cAAM,MAAM;IACR,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,IAAI,CAAY;IAExB;;;OAGG;IACH,MAAM,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,GAAG,uBAAuB,KAAK,IAAI,CAAC;IAE7G;;;OAGG;IACH,MAAM,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,MAAM,CAAC,qBAAqB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,GAAG,4BAA4B,KAAK,IAAI,CAAC;IAE1H;;;OAGG;IACH,MAAM,CAAC,uBAAuB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,MAAM,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,gBAAgB,EAAE,CAAC;IAEvH;;;OAGG;IACH,MAAM,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IAE3E;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAEjC;;;;;OAKG;gBACS,SAAS,GAAE,MAAM,GAAG,IAAW;IAU3C;;;;;OAKG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC;;;;OAIG;IACH,IAAW,OAAO,IAAI,GAAG,CAExB;CACJ;AAED,eAAe,MAAM,CAAC"}

package/dist/extensibility.d.ts

@@ -0,0 +1,9 @@
+/**
+ * FlowQuery Extensibility API
+ *
+ * This module re-exports the extensibility API from the parsing/functions/extensibility module.
+ *
+ * @packageDocumentation
+ */
+export * from "./parsing/functions/extensibility";
+//# sourceMappingURL=extensibility.d.ts.map

package/dist/extensibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensibility.d.ts","sourceRoot":"","sources":["../src/extensibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,mCAAmC,CAAC"}

package/dist/extensibility.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * FlowQuery Extensibility API
+ *
+ * This module re-exports the extensibility API from the parsing/functions/extensibility module.
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./parsing/functions/extensibility"), exports);
+//# sourceMappingURL=extensibility.js.map

package/dist/extensibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensibility.js","sourceRoot":"","sources":["../src/extensibility.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH,oEAAkD"}