flowquery 1.0.5 → 1.0.7

package/README.md

@@ -143,6 +143,80 @@ post {
 return data
 ```
 
+## Extending FlowQuery with Custom Functions
+
+FlowQuery provides a plugin system that allows you to register custom functions using the `@FunctionDef` decorator. 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");  // Function name used in queries
+        this._expectedParameterCount = 1;  // Number of required parameters
+    }
+    
+    public value(): string {
+        const input = this.getChildren()[0].value();
+        return String(input).toUpperCase();
+    }
+}
+```
+
+The decorator automatically registers the function with the FlowQuery function factory.
+
+### Creating Async Data Providers
+
+For functions that fetch data asynchronously (used with `LOAD JSON FROM`), use the `@FunctionDef` decorator with `category: "async"`. The class must have a `fetch` method that returns an async generator:
+
+```typescript
+import { FunctionDef } from "flowquery/extensibility";
+
+@FunctionDef({
+    description: "Provides example data for testing",
+    category: "async",
+    parameters: [],
+    output: { description: "Example data object", type: "object" }
+})
+class GetExampleDataLoader {
+    async *fetch(): AsyncGenerator<any> {
+        yield { id: 1, name: "Alice" };
+        yield { id: 2, name: "Bob" };
+    }
+}
+```
+
+The function name is derived from the class name by removing the `Loader` suffix (if present) and converting to camelCase. In this example, `GetExampleDataLoader` becomes `getExampleData`.
+
+Use the async provider in a FlowQuery statement:
+
+```cypher
+LOAD JSON FROM getExampleData() AS data
+RETURN data.id AS id, data.name AS name
+```
+
+The extensibility module (`flowquery/extensibility`) exports:
+- `Function` - Base class for scalar functions
+- `AggregateFunction` - Base class for aggregate functions (like `sum`, `avg`, `collect`)
+- `AsyncFunction` - Base class for async function calls
+- `PredicateFunction` - Base class for predicate functions (like list comprehensions)
+- `ReducerElement` - Helper class for aggregate function state
+- `FunctionDef` - Decorator for registering functions with metadata
+- `FunctionMetadata`, `FunctionDefOptions`, `ParameterSchema`, `OutputSchema`, `FunctionCategory` - TypeScript types for metadata definitions
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

package/dist/compute/runner.d.ts

@@ -1,5 +1,4 @@
-import { FunctionCreator, AsyncDataProvider } from "../parsing/functions/function_factory";
-import { FunctionMetadata, RegisterFunctionOptions, RegisterAsyncProviderOptions } from "../parsing/functions/function_metadata";
+import { FunctionMetadata } from "../parsing/functions/function_metadata";
 import Function from "../parsing/functions/function";
 /**
  * Executes a FlowQuery statement and retrieves the results.
@@ -17,26 +16,6 @@ import Function from "../parsing/functions/function";
 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

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

@@ -1 +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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,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,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/compute/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AACA,+DAAuC;AAKvC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM;IA8CR;;;;;OAKG;IACH,YAAY,YAA2B,IAAI;QACvC,IAAG,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,gBAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU,EAAe,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,SAAS,EAAe,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACU,GAAG;;YACZ,OAAO,IAAI,OAAO,CAAO,CAAO,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC/C,IAAI,CAAC;oBACD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;oBACvB,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBAC1B,OAAO,EAAE,CAAC;gBACd,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,MAAM,CAAC,CAAC,CAAC,CAAC;gBACd,CAAC;YACL,CAAC,CAAA,CAAC,CAAC;QACP,CAAC;KAAA;IAED;;;;OAIG;IACH,IAAW,OAAO;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC7B,CAAC;CACJ;AAED,kBAAe,MAAM,CAAC"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AACA,+DAAuC;AAIvC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM;IAsBR;;;;;OAKG;IACH,YAAY,YAA2B,IAAI;QACvC,IAAG,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,gBAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU,EAAe,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,SAAS,EAAe,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACU,GAAG;;YACZ,OAAO,IAAI,OAAO,CAAO,CAAO,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC/C,IAAI,CAAC;oBACD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;oBACvB,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBAC1B,OAAO,EAAE,CAAC;gBACd,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,MAAM,CAAC,CAAC,CAAC,CAAC;gBACd,CAAC;YACL,CAAC,CAAA,CAAC,CAAC;QACP,CAAC;KAAA;IAED;;;;OAIG;IACH,IAAW,OAAO;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC7B,CAAC;CACJ;AAED,kBAAe,MAAM,CAAC"}

package/dist/extensibility.d.ts

@@ -0,0 +1,35 @@
+/**
+ * FlowQuery Extensibility API
+ *
+ * This module provides all the exports needed to create custom FlowQuery functions.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```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" }
+ * })
+ * class UpperCase extends Function {
+ *     constructor() {
+ *         super("uppercase");
+ *         this._expectedParameterCount = 1;
+ *     }
+ *     public value(): string {
+ *         return String(this.getChildren()[0].value()).toUpperCase();
+ *     }
+ * }
+ * ```
+ */
+export { default as Function } from "./parsing/functions/function";
+export { default as AggregateFunction } from "./parsing/functions/aggregate_function";
+export { default as AsyncFunction } from "./parsing/functions/async_function";
+export { default as PredicateFunction } from "./parsing/functions/predicate_function";
+export { default as ReducerElement } from "./parsing/functions/reducer_element";
+export { FunctionDef, FunctionMetadata, FunctionDefOptions, ParameterSchema, OutputSchema, FunctionCategory } from "./parsing/functions/function_metadata";
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAGhF,OAAO,EACH,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,gBAAgB,EACnB,MAAM,uCAAuC,CAAC"}

package/dist/extensibility.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * FlowQuery Extensibility API
+ *
+ * This module provides all the exports needed to create custom FlowQuery functions.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```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" }
+ * })
+ * class UpperCase extends Function {
+ *     constructor() {
+ *         super("uppercase");
+ *         this._expectedParameterCount = 1;
+ *     }
+ *     public value(): string {
+ *         return String(this.getChildren()[0].value()).toUpperCase();
+ *     }
+ * }
+ * ```
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionDef = exports.ReducerElement = exports.PredicateFunction = exports.AsyncFunction = exports.AggregateFunction = exports.Function = void 0;
+// Base function classes for creating custom functions
+var function_1 = require("./parsing/functions/function");
+Object.defineProperty(exports, "Function", { enumerable: true, get: function () { return __importDefault(function_1).default; } });
+var aggregate_function_1 = require("./parsing/functions/aggregate_function");
+Object.defineProperty(exports, "AggregateFunction", { enumerable: true, get: function () { return __importDefault(aggregate_function_1).default; } });
+var async_function_1 = require("./parsing/functions/async_function");
+Object.defineProperty(exports, "AsyncFunction", { enumerable: true, get: function () { return __importDefault(async_function_1).default; } });
+var predicate_function_1 = require("./parsing/functions/predicate_function");
+Object.defineProperty(exports, "PredicateFunction", { enumerable: true, get: function () { return __importDefault(predicate_function_1).default; } });
+var reducer_element_1 = require("./parsing/functions/reducer_element");
+Object.defineProperty(exports, "ReducerElement", { enumerable: true, get: function () { return __importDefault(reducer_element_1).default; } });
+// Decorator and metadata types for function registration
+var function_metadata_1 = require("./parsing/functions/function_metadata");
+Object.defineProperty(exports, "FunctionDef", { enumerable: true, get: function () { return function_metadata_1.FunctionDef; } });
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;AAEH,sDAAsD;AACtD,yDAAmE;AAA1D,qHAAA,OAAO,OAAY;AAC5B,6EAAsF;AAA7E,wIAAA,OAAO,OAAqB;AACrC,qEAA8E;AAArE,gIAAA,OAAO,OAAiB;AACjC,6EAAsF;AAA7E,wIAAA,OAAO,OAAqB;AACrC,uEAAgF;AAAvE,kIAAA,OAAO,OAAkB;AAElC,yDAAyD;AACzD,2EAO+C;AAN3C,gHAAA,WAAW,OAAA"}