flowquery 1.0.5 → 1.0.7

package/tests/extensibility.test.ts

@@ -0,0 +1,563 @@
+import {
+    Function,
+    AggregateFunction,
+    AsyncFunction,
+    PredicateFunction,
+    ReducerElement,
+    FunctionDef,
+    FunctionMetadata,
+    FunctionDefOptions,
+    ParameterSchema,
+    OutputSchema,
+    FunctionCategory
+} from "../src/extensibility";
+import {
+    getRegisteredAsyncProvider,
+    getFunctionMetadata
+} from "../src/parsing/functions/function_metadata";
+
+describe("Extensibility API Exports", () => {
+    test("Function class is exported and can be extended", () => {
+        class CustomFunction extends Function {
+            constructor() {
+                super("customFunc");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): string {
+                return "custom value";
+            }
+        }
+        
+        const func = new CustomFunction();
+        expect(func.name).toBe("customFunc");
+        expect(func.toString()).toBe("Function (customFunc)");
+        expect(func.value()).toBe("custom value");
+    });
+
+    test("Function validates parameter count when set", () => {
+        class TwoParamFunction extends Function {
+            constructor() {
+                super("twoParam");
+                this._expectedParameterCount = 2;
+            }
+        }
+        
+        const func = new TwoParamFunction();
+        
+        // Should throw when wrong number of parameters
+        expect(() => {
+            func.parameters = [];
+        }).toThrow("Function twoParam expected 2 parameters, but got 0");
+    });
+
+    test("Function without expected parameter count accepts any number", () => {
+        class FlexibleFunction extends Function {
+            constructor() {
+                super("flexible");
+                // _expectedParameterCount is null by default
+            }
+        }
+        
+        const func = new FlexibleFunction();
+        // Should not throw
+        func.parameters = [];
+        expect(func.getChildren().length).toBe(0);
+    });
+
+    test("AggregateFunction class is exported and can be extended", () => {
+        class SumElement extends ReducerElement {
+            private _value: number = 0;
+            public get value(): number {
+                return this._value;
+            }
+            public set value(v: number) {
+                this._value = v;
+            }
+        }
+        
+        class CustomSum extends AggregateFunction {
+            private _total: number = 0;
+            
+            constructor() {
+                super("customSum");
+            }
+            
+            public reduce(element: ReducerElement): void {
+                this._total += element.value;
+            }
+            
+            public element(): ReducerElement {
+                const el = new SumElement();
+                el.value = this._total;
+                return el;
+            }
+            
+            public value(): number {
+                return this._total;
+            }
+        }
+        
+        const agg = new CustomSum();
+        expect(agg.name).toBe("customSum");
+        
+        const elem = new SumElement();
+        elem.value = 5;
+        agg.reduce(elem);
+        expect(agg.value()).toBe(5);
+        
+        const elem2 = new SumElement();
+        elem2.value = 3;
+        agg.reduce(elem2);
+        expect(agg.value()).toBe(8);
+    });
+
+    test("PredicateFunction class is exported and can be extended", () => {
+        class CustomPredicate extends PredicateFunction {
+            constructor() {
+                super("customPredicate");
+            }
+            
+            public value(): boolean {
+                return true;
+            }
+        }
+        
+        const pred = new CustomPredicate();
+        expect(pred.name).toBe("customPredicate");
+        expect(pred.toString()).toBe("PredicateFunction (customPredicate)");
+        expect(pred.value()).toBe(true);
+    });
+
+    test("AsyncFunction class is exported and can be instantiated", () => {
+        const asyncFunc = new AsyncFunction("testAsync");
+        expect(asyncFunc.name).toBe("testAsync");
+    });
+
+    test("ReducerElement class is exported and can be extended", () => {
+        class NumberElement extends ReducerElement {
+            private _num: number = 0;
+            
+            public get value(): number {
+                return this._num;
+            }
+            
+            public set value(v: number) {
+                this._num = v;
+            }
+        }
+        
+        const elem = new NumberElement();
+        elem.value = 42;
+        expect(elem.value).toBe(42);
+    });
+});
+
+describe("FunctionDef Decorator", () => {
+    test("FunctionDef decorator can be applied to a scalar function", () => {
+        @FunctionDef({
+            description: "Test function for extensibility",
+            category: "scalar",
+            parameters: [
+                { name: "input", description: "Input value", type: "string" }
+            ],
+            output: { description: "Output value", type: "string" },
+            examples: ["RETURN testExtFunc('hello')"]
+        })
+        class TestExtFunc extends Function {
+            constructor() {
+                super("testExtFunc");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): string {
+                return "test result";
+            }
+        }
+        
+        // Verify the decorated class still works correctly
+        const instance = new TestExtFunc();
+        expect(instance.name).toBe("testExtFunc");
+        expect(instance.value()).toBe("test result");
+    });
+
+    test("FunctionDef decorator can be applied to an aggregate function", () => {
+        @FunctionDef({
+            description: "Test aggregate function",
+            category: "aggregate",
+            parameters: [
+                { name: "value", description: "Numeric value", type: "number" }
+            ],
+            output: { description: "Aggregated result", type: "number" }
+        })
+        class TestAggExt extends AggregateFunction {
+            private _sum: number = 0;
+            
+            constructor() {
+                super("testAggExt");
+            }
+            
+            public value(): number {
+                return this._sum;
+            }
+        }
+        
+        const instance = new TestAggExt();
+        expect(instance.name).toBe("testAggExt");
+        expect(instance.value()).toBe(0);
+    });
+
+    test("FunctionDef decorator can be applied to an async provider", async () => {
+        @FunctionDef({
+            description: "Test async provider for extensibility",
+            category: "async",
+            parameters: [
+                { name: "count", description: "Number of items", type: "number", required: false, default: 1 }
+            ],
+            output: { description: "Data object", type: "object" }
+        })
+        class SimpleLoader {
+            async *fetch(count: number = 1): AsyncGenerator<any> {
+                for (let i = 0; i < count; i++) {
+                    yield { id: i, data: `item${i}` };
+                }
+            }
+        }
+        
+        // Verify the decorated class still works correctly
+        const loader = new SimpleLoader();
+        const results: any[] = [];
+        for await (const item of loader.fetch(2)) {
+            results.push(item);
+        }
+        expect(results.length).toBe(2);
+        expect(results[0]).toEqual({ id: 0, data: "item0" });
+        expect(results[1]).toEqual({ id: 1, data: "item1" });
+        
+        // Verify the async provider was registered
+        const provider = getRegisteredAsyncProvider("simple");
+        expect(provider).toBeDefined();
+        expect(typeof provider).toBe("function");
+        
+        // Verify the metadata was registered
+        const metadata = getFunctionMetadata("simple");
+        expect(metadata).toBeDefined();
+        expect(metadata?.name).toBe("simple");
+        expect(metadata?.category).toBe("async");
+        expect(metadata?.description).toBe("Test async provider for extensibility");
+    });
+
+    test("FunctionDef decorator can be applied to a predicate function", () => {
+        @FunctionDef({
+            description: "Test predicate function",
+            category: "predicate",
+            parameters: [
+                { name: "list", description: "List to check", type: "array" }
+            ],
+            output: { description: "Boolean result", type: "boolean" }
+        })
+        class TestPredExt extends PredicateFunction {
+            constructor() {
+                super("testPredExt");
+            }
+            
+            public value(): boolean {
+                return true;
+            }
+        }
+        
+        const instance = new TestPredExt();
+        expect(instance.name).toBe("testPredExt");
+        expect(instance.value()).toBe(true);
+    });
+});
+
+describe("Type Exports", () => {
+    test("FunctionMetadata type can be used", () => {
+        const meta: FunctionMetadata = {
+            name: "typeTest",
+            description: "Testing type exports",
+            category: "scalar",
+            parameters: [],
+            output: { description: "Output", type: "string" }
+        };
+        
+        expect(meta.name).toBe("typeTest");
+        expect(meta.description).toBe("Testing type exports");
+    });
+
+    test("ParameterSchema type can be used", () => {
+        const param: ParameterSchema = {
+            name: "testParam",
+            description: "A test parameter",
+            type: "string",
+            required: true,
+            default: "default value",
+            example: "example value"
+        };
+        
+        expect(param.name).toBe("testParam");
+        expect(param.required).toBe(true);
+    });
+
+    test("ParameterSchema with nested types", () => {
+        const arrayParam: ParameterSchema = {
+            name: "items",
+            description: "Array of items",
+            type: "array",
+            items: {
+                description: "Item in array",
+                type: "string"
+            }
+        };
+        
+        const objectParam: ParameterSchema = {
+            name: "config",
+            description: "Configuration object",
+            type: "object",
+            properties: {
+                enabled: { description: "Is enabled", type: "boolean" },
+                value: { description: "Value", type: "number" }
+            }
+        };
+        
+        expect(arrayParam.items?.type).toBe("string");
+        expect(objectParam.properties?.enabled.type).toBe("boolean");
+    });
+
+    test("OutputSchema type can be used", () => {
+        const output: OutputSchema = {
+            description: "Result output",
+            type: "object",
+            properties: {
+                success: { description: "Success flag", type: "boolean" },
+                data: { description: "Result data", type: "array" }
+            },
+            example: { success: true, data: [] }
+        };
+        
+        expect(output.type).toBe("object");
+        expect(output.properties?.success.type).toBe("boolean");
+    });
+
+    test("FunctionCategory type accepts standard and custom categories", () => {
+        const scalar: FunctionCategory = "scalar";
+        const aggregate: FunctionCategory = "aggregate";
+        const predicate: FunctionCategory = "predicate";
+        const async: FunctionCategory = "async";
+        const custom: FunctionCategory = "myCustomCategory";
+        
+        expect(scalar).toBe("scalar");
+        expect(aggregate).toBe("aggregate");
+        expect(predicate).toBe("predicate");
+        expect(async).toBe("async");
+        expect(custom).toBe("myCustomCategory");
+    });
+
+    test("FunctionDefOptions type can be used", () => {
+        const options: FunctionDefOptions = {
+            description: "Function options test",
+            category: "scalar",
+            parameters: [],
+            output: { description: "Output", type: "string" },
+            notes: "Some additional notes"
+        };
+        
+        expect(options.description).toBe("Function options test");
+        expect(options.notes).toBe("Some additional notes");
+    });
+});
+
+describe("Plugin Functions Integration with FlowQuery", () => {
+    // Import Runner for executing FlowQuery statements
+    const Runner = require("../src/compute/runner").default;
+
+    test("Custom scalar function can be used in a FlowQuery statement", async () => {
+        // Define and register a custom function via @FunctionDef decorator
+        @FunctionDef({
+            description: "Doubles a number",
+            category: "scalar",
+            parameters: [{ name: "value", description: "Number to double", type: "number" }],
+            output: { description: "Doubled value", type: "number" }
+        })
+        class Double extends Function {
+            constructor() {
+                super("double");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): number {
+                return this.getChildren()[0].value() * 2;
+            }
+        }
+
+        // Execute a FlowQuery statement that uses the custom function
+        const runner = new Runner("WITH 5 AS num RETURN double(num) AS result");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(1);
+        expect(runner.results[0]).toEqual({ result: 10 });
+    });
+
+    test("Custom string function can be used in a FlowQuery statement", async () => {
+        @FunctionDef({
+            description: "Reverses a string",
+            category: "scalar",
+            parameters: [{ name: "text", description: "String to reverse", type: "string" }],
+            output: { description: "Reversed string", type: "string" }
+        })
+        class StrReverse extends Function {
+            constructor() {
+                super("strreverse");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): string {
+                const input = String(this.getChildren()[0].value());
+                return input.split('').reverse().join('');
+            }
+        }
+
+        const runner = new Runner("WITH 'hello' AS s RETURN strreverse(s) AS reversed");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(1);
+        expect(runner.results[0]).toEqual({ reversed: 'olleh' });
+    });
+
+    test("Custom aggregate function can be used in a FlowQuery statement", async () => {
+        // Create a custom reducer element for the aggregate
+        class ProductElement extends ReducerElement {
+            private _value: number = 1;
+            public get value(): number {
+                return this._value;
+            }
+            public set value(v: number) {
+                this._value *= v;
+            }
+        }
+
+        @FunctionDef({
+            description: "Calculates the product of values",
+            category: "aggregate",
+            parameters: [{ name: "value", description: "Number to multiply", type: "number" }],
+            output: { description: "Product of all values", type: "number" }
+        })
+        class Product extends AggregateFunction {
+            constructor() {
+                super("product");
+                this._expectedParameterCount = 1;
+            }
+            
+            public reduce(element: ReducerElement): void {
+                element.value = this.firstChild().value();
+            }
+            
+            public element(): ReducerElement {
+                return new ProductElement();
+            }
+        }
+
+        const runner = new Runner("UNWIND [2, 3, 4] AS num RETURN product(num) AS result");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(1);
+        expect(runner.results[0]).toEqual({ result: 24 });
+    });
+
+    test("Custom function works with expressions and other functions", async () => {
+        @FunctionDef({
+            description: "Adds 100 to a number",
+            category: "scalar",
+            parameters: [{ name: "value", description: "Number", type: "number" }],
+            output: { description: "Number plus 100", type: "number" }
+        })
+        class AddHundred extends Function {
+            constructor() {
+                super("addhundred");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): number {
+                return this.getChildren()[0].value() + 100;
+            }
+        }
+
+        // Use the custom function with expressions
+        const runner = new Runner("WITH 5 * 3 AS num RETURN addhundred(num) + 1 AS result");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(1);
+        expect(runner.results[0]).toEqual({ result: 116 }); // (5*3) + 100 + 1 = 116
+    });
+
+    test("Multiple custom functions can be used together", async () => {
+        @FunctionDef({
+            description: "Triples a number",
+            category: "scalar",
+            parameters: [{ name: "value", description: "Number to triple", type: "number" }],
+            output: { description: "Tripled value", type: "number" }
+        })
+        class Triple extends Function {
+            constructor() {
+                super("triple");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): number {
+                return this.getChildren()[0].value() * 3;
+            }
+        }
+
+        @FunctionDef({
+            description: "Squares a number",
+            category: "scalar",
+            parameters: [{ name: "value", description: "Number to square", type: "number" }],
+            output: { description: "Squared value", type: "number" }
+        })
+        class Square extends Function {
+            constructor() {
+                super("square");
+                this._expectedParameterCount = 1;
+            }
+            
+            public value(): number {
+                const v = this.getChildren()[0].value();
+                return v * v;
+            }
+        }
+
+        // Use both custom functions in a query
+        const runner = new Runner("WITH 2 AS num RETURN triple(num) AS tripled, square(num) AS squared");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(1);
+        expect(runner.results[0]).toEqual({ tripled: 6, squared: 4 });
+    });
+
+    test("Custom async provider can be used in LOAD JSON FROM statement", async () => {
+        @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" };
+            }
+        }
+
+        // Verify registration worked
+        expect(getRegisteredAsyncProvider("getExampleData")).toBeDefined();
+
+        // Use the async provider in a FlowQuery statement
+        const runner = new Runner("LOAD JSON FROM getExampleData() AS data RETURN data.id AS id, data.name AS name");
+        await runner.run();
+        
+        expect(runner.results.length).toBe(2);
+        expect(runner.results[0]).toEqual({ id: 1, name: "Alice" });
+        expect(runner.results[1]).toEqual({ id: 2, name: "Bob" });
+    });
+});

package/tsconfig.json

@@ -4,6 +4,7 @@
     "outDir": "./dist",
     "rootDir": "./src", // Optional, but recommended to specify the root directory
     "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */    /* Modules */
+    "experimentalDecorators": true,                      /* Enable experimental support for decorators. */
     "module": "commonjs",                                /* Specify what module code is generated. */
     "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
     "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */

package/dist/parsing/functions/predicate_function_factory.d.ts

@@ -1,6 +0,0 @@
-import PredicateFunction from "./predicate_function";
-declare class PredicateFunctionFactory {
-    static create(name: string): PredicateFunction;
-}
-export default PredicateFunctionFactory;
-//# sourceMappingURL=predicate_function_factory.d.ts.map

package/dist/parsing/functions/predicate_function_factory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"predicate_function_factory.d.ts","sourceRoot":"","sources":["../../../src/parsing/functions/predicate_function_factory.ts"],"names":[],"mappings":"AAAA,OAAO,iBAAiB,MAAM,sBAAsB,CAAC;AAGrD,cAAM,wBAAwB;WACZ,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;CAQxD;AAED,eAAe,wBAAwB,CAAC"}

package/dist/parsing/functions/predicate_function_factory.js

@@ -1,19 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const predicate_function_1 = __importDefault(require("./predicate_function"));
-const predicate_sum_1 = __importDefault(require("./predicate_sum"));
-class PredicateFunctionFactory {
-    static create(name) {
-        switch (name.toLowerCase()) {
-            case "sum":
-                return new predicate_sum_1.default();
-            default:
-                return new predicate_function_1.default(name);
-        }
-    }
-}
-exports.default = PredicateFunctionFactory;
-//# sourceMappingURL=predicate_function_factory.js.map

package/dist/parsing/functions/predicate_function_factory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"predicate_function_factory.js","sourceRoot":"","sources":["../../../src/parsing/functions/predicate_function_factory.ts"],"names":[],"mappings":";;;;;AAAA,8EAAqD;AACrD,oEAA2C;AAE3C,MAAM,wBAAwB;IACnB,MAAM,CAAC,MAAM,CAAC,IAAY;QAC7B,QAAQ,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,KAAK,KAAK;gBACN,OAAO,IAAI,uBAAY,EAAE,CAAC;YAC9B;gBACI,OAAO,IAAI,4BAAiB,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;IACL,CAAC;CACJ;AAED,kBAAe,wBAAwB,CAAC"}

package/misc/apps/RAG/src/index.ts

@@ -1,20 +0,0 @@
-import { FlowQuery } from 'flowquery';
-
-/**
- * RAG (Retrieval Augmented Generation) loop using FlowQuery.
- * 
- * This is a starter template - customize it for your RAG implementation.
- */
-async function main() {
-    // Example: Run a simple FlowQuery query
-    const query = new FlowQuery('WITH 1 AS x RETURN x + 1');
-
-    try {
-        await query.run();
-        console.log('Result:', query.results); // [ { expr0: 2 } ]
-    } catch (error) {
-        console.error('Error running query:', error);
-    }
-}
-
-main();

package/src/parsing/functions/predicate_function_factory.ts

@@ -1,15 +0,0 @@
-import PredicateFunction from "./predicate_function";
-import PredicateSum from "./predicate_sum";
-
-class PredicateFunctionFactory {
-    public static create(name: string): PredicateFunction {
-        switch (name.toLowerCase()) {
-            case "sum":
-                return new PredicateSum();
-            default:
-                return new PredicateFunction(name);
-        }
-    }
-}
-
-export default PredicateFunctionFactory;