flowquery 1.0.25 → 1.0.27

package/src/parsing/expressions/reference.ts

@@ -3,9 +3,9 @@ import Identifier from "./identifier";
 
 /**
  * Represents a reference to a previously defined variable or expression.
- * 
+ *
  * References point to values defined earlier in the query (e.g., in WITH or LOAD statements).
- * 
+ *
  * @example
  * ```typescript
  * const ref = new Reference("myVar", previousNode);
@@ -14,10 +14,10 @@ import Identifier from "./identifier";
  */
 class Reference extends Identifier {
     private _referred: ASTNode | undefined = undefined;
-    
+
     /**
      * Creates a new Reference to a variable.
-     * 
+     *
      * @param value - The identifier name
      * @param referred - The node this reference points to (optional)
      */
@@ -25,6 +25,9 @@ class Reference extends Identifier {
         super(value);
         this._referred = referred;
     }
+    public get referred(): ASTNode | undefined {
+        return this._referred;
+    }
     public set referred(node: ASTNode) {
         this._referred = node;
     }
@@ -39,4 +42,4 @@ class Reference extends Identifier {
     }
 }
 
-export default Reference;
+export default Reference;

package/src/parsing/parser.ts

@@ -220,6 +220,7 @@ class Parser extends BaseParser {
     }
 
     private parseWhere(): Where | null {
+        this.skipWhitespaceAndComments();
         if (!this.token.isWhere()) {
             return null;
         }
@@ -437,8 +438,15 @@ class Parser extends BaseParser {
             node.identifier = identifier;
             this.variables.set(identifier, node);
         } else if (identifier !== null) {
-            const reference = this.variables.get(identifier);
-            if (reference === undefined || reference.constructor !== Node) {
+            let reference = this.variables.get(identifier);
+            // Resolve through Expression -> Reference -> Node (e.g., after WITH)
+            if (reference instanceof Expression && reference.firstChild() instanceof Reference) {
+                const inner = (reference.firstChild() as Reference).referred;
+                if (inner instanceof Node) {
+                    reference = inner;
+                }
+            }
+            if (reference === undefined || !(reference instanceof Node)) {
                 throw new Error(`Undefined node reference: ${identifier}`);
             }
             node = new NodeReference(node, reference);
@@ -628,8 +636,15 @@ class Parser extends BaseParser {
             relationship.identifier = variable;
             this.variables.set(variable, relationship);
         } else if (variable !== null) {
-            const reference = this.variables.get(variable);
-            if (reference === undefined || reference.constructor !== Relationship) {
+            let reference = this.variables.get(variable);
+            // Resolve through Expression -> Reference -> Relationship (e.g., after WITH)
+            if (reference instanceof Expression && reference.firstChild() instanceof Reference) {
+                const inner = (reference.firstChild() as Reference).referred;
+                if (inner instanceof Relationship) {
+                    reference = inner;
+                }
+            }
+            if (reference === undefined || !(reference instanceof Relationship)) {
                 throw new Error(`Undefined relationship reference: ${variable}`);
             }
             relationship = new RelationshipReference(relationship, reference);

package/tests/compute/runner.test.ts

@@ -414,7 +414,7 @@ test("Test lookup which is keyword", async () => {
     expect(results[0]).toEqual({ aa: 1 });
 });
 
-test("Test lookup which is keyword", async () => {
+test("Test lookup which is keyword with bracket notation", async () => {
     const runner = new Runner('RETURN {return: 1}["return"] as aa');
     await runner.run();
     const results = runner.results;
@@ -1556,3 +1556,49 @@ test("Test reserved keywords as relationship types and labels", async () => {
     expect(results.length).toBe(1);
     expect(results[0]).toEqual({ name1: "Node 1", name2: "Node 2" });
 });
+
+test("Test match with node reference passed through WITH", async () => {
+    await new Runner(`
+        CREATE VIRTUAL (:User) AS {
+            UNWIND [
+                {id: 1, name: 'Alice', mail: 'alice@test.com', jobTitle: 'CEO'},
+                {id: 2, name: 'Bob', mail: 'bob@test.com', jobTitle: 'VP'},
+                {id: 3, name: 'Carol', mail: 'carol@test.com', jobTitle: 'VP'},
+                {id: 4, name: 'Dave', mail: 'dave@test.com', jobTitle: 'Engineer'}
+            ] AS record
+            RETURN record.id AS id, record.name AS name, record.mail AS mail, record.jobTitle AS jobTitle
+        }
+    `).run();
+    await new Runner(`
+        CREATE VIRTUAL (:User)-[:MANAGES]-(:User) AS {
+            UNWIND [
+                {left_id: 1, right_id: 2},
+                {left_id: 1, right_id: 3},
+                {left_id: 2, right_id: 4}
+            ] AS record
+            RETURN record.left_id AS left_id, record.right_id AS right_id
+        }
+    `).run();
+    // Equivalent to:
+    //   MATCH (ceo:User)-[:MANAGES]->(dr1:User)
+    //   WHERE ceo.jobTitle = 'CEO'
+    //   WITH ceo, dr1
+    //   MATCH (ceo)-[:MANAGES]->(dr2:User)
+    //   WHERE dr1.mail <> dr2.mail
+    //   RETURN ceo, dr1, dr2
+    const match = new Runner(`
+        MATCH (ceo:User)-[:MANAGES]->(dr1:User)
+        WHERE ceo.jobTitle = 'CEO'
+        WITH ceo, dr1
+        MATCH (ceo)-[:MANAGES]->(dr2:User)
+        WHERE dr1.mail <> dr2.mail
+        RETURN ceo.name AS ceo, dr1.name AS dr1, dr2.name AS dr2
+    `);
+    await match.run();
+    const results = match.results;
+    // CEO (Alice) manages Bob and Carol. All distinct pairs:
+    // (Alice, Bob, Carol) and (Alice, Carol, Bob)
+    expect(results.length).toBe(2);
+    expect(results[0]).toEqual({ ceo: "Alice", dr1: "Bob", dr2: "Carol" });
+    expect(results[1]).toEqual({ ceo: "Alice", dr1: "Carol", dr2: "Bob" });
+});

package/tests/parsing/parser.test.ts

@@ -867,6 +867,22 @@ test("Test node with properties", () => {
     expect(node.properties.get("value")?.value()).toBe("hello");
 });
 
+test("Test WHERE in CREATE VIRTUAL sub-query", () => {
+    const parser = new Parser();
+    const ast = parser.parse(`
+        CREATE VIRTUAL (:Email)-[:HAS_ATTACHMENT]-(:File) AS {
+            LOAD JSON FROM '/data/emails.json' AS email
+            WHERE email.hasAttachments = true
+            UNWIND email.attachments AS fileId
+            RETURN email.id AS left_id, fileId AS right_id
+        }
+    `);
+    const create = ast.firstChild() as CreateRelationship;
+    expect(create.relationship).not.toBeNull();
+    expect(create.relationship!.type).toBe("HAS_ATTACHMENT");
+    expect(create.statement).not.toBeNull();
+});
+
 test("Test relationship with properties", () => {
     const parser = new Parser();
     const ast = parser.parse("MATCH (:Person)-[r:LIKES{since: 2022}]->(:Food) return a");

package/misc/apps/RAG/src/plugins/README.md

@@ -1,139 +0,0 @@
-# FlowQuery Plugin System
-
-This folder contains the plugin system for adding async data loader functions to FlowQuery.
-
-## Quick Start
-
-1. Create a new file in `loaders/` (e.g., `my-api.ts`)
-2. Define your plugin following the `AsyncLoaderPlugin` interface
-3. Import and add it to the `allPlugins` array in `index.ts`
-
-## Creating a Plugin
-
-### Basic Plugin Structure
-
-```typescript
-import { AsyncLoaderPlugin } from '../types';
-
-// Your async data provider function
-async function* myDataProvider(arg1: string, arg2?: number): AsyncGenerator<any, void, unknown> {
-    const response = await fetch(`https://api.example.com/${arg1}`);
-    const data = await response.json();
-    
-    // Yield items one at a time (for arrays)
-    if (Array.isArray(data)) {
-        for (const item of data) {
-            yield item;
-        }
-    } else {
-        yield data;
-    }
-}
-
-// Export the plugin definition
-export const myPlugin: AsyncLoaderPlugin = {
-    name: 'myData',  // Function name in FlowQuery
-    provider: myDataProvider,
-    metadata: {
-        description: 'Fetches data from My API',
-        category: 'data',
-        parameters: [
-            { name: 'arg1', description: 'First argument', type: 'string', required: true },
-            { name: 'arg2', description: 'Optional second arg', type: 'number', required: false }
-        ],
-        output: {
-            description: 'Data item',
-            type: 'object',
-            properties: {
-                id: { description: 'Item ID', type: 'number' },
-                value: { description: 'Item value', type: 'string' }
-            }
-        },
-        examples: [
-            "LOAD JSON FROM myData('users') AS item RETURN item.id, item.value"
-        ]
-    }
-};
-
-export default myPlugin;
-```
-
-### Register the Plugin
-
-Add your plugin to `index.ts`:
-
-```typescript
-import myPlugin from './loaders/my-api';
-
-const allPlugins: AsyncLoaderPlugin[] = [
-    // ... existing plugins
-    myPlugin,
-];
-```
-
-## Using Plugins in FlowQuery
-
-Once registered, use your plugin in FlowQuery queries:
-
-```sql
--- Fetch data from your custom source
-LOAD JSON FROM myData('users') AS user
-WHERE user.active = true
-RETURN user.name, user.email
-
--- Combine with filtering and ordering
-LOAD JSON FROM myData('products', 50) AS product
-WHERE product.price > 10
-ORDER BY product.name ASC
-RETURN product.name, product.price
-```
-
-## Available Built-in Plugins
-
-| Plugin | Description | Example |
-|--------|-------------|---------|
-| `fetchJson` | Fetch JSON from any URL | `fetchJson('https://api.example.com/data')` |
-
-> **Note**: Additional plugins may be registered. Check `index.ts` for the current list of available plugins.
-
-## Plugin Types
-
-### AsyncLoaderPlugin
-
-```typescript
-interface AsyncLoaderPlugin {
-    name: string;                    // Function name (lowercased when registered)
-    provider: AsyncDataProvider;     // The async generator/function
-    metadata?: PluginMetadata;       // Optional metadata for LLM consumption
-}
-```
-
-### AsyncDataProvider
-
-```typescript
-type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
-```
-
-Plugins can return either:
-- An `AsyncGenerator` that yields items one at a time
-- A `Promise` that resolves to an array or single value
-
-### PluginMetadata
-
-```typescript
-interface PluginMetadata {
-    name: string;
-    description: string;
-    category?: string;
-    parameters?: ParameterSchema[];
-    output?: OutputSchema;
-    examples?: string[];
-}
-```
-
-## Tips
-
-1. **Use generators for large datasets** - Yield items one at a time to avoid memory issues
-2. **Add comprehensive metadata** - This helps LLMs understand and use your functions
-3. **Handle errors gracefully** - Throw descriptive errors for API failures
-4. **Include examples** - Show users how to use your plugin in FlowQuery

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

@@ -1,72 +0,0 @@
-/**
- * Plugin loader - automatically discovers and loads all plugins.
- * 
- * To add a new plugin:
- * 1. Create a new file in the `loaders/` directory
- * 2. Add the @FunctionDef decorator with category: 'async' to your loader class
- * 3. Import the class in this file (the decorator auto-registers with FlowQuery)
- */
-
-import FlowQuery from 'flowquery';
-import { FunctionMetadata } from 'flowquery/extensibility';
-
-// Import plugin classes - the @FunctionDef decorator auto-registers them with FlowQuery
-// This step is essential to ensure decorators are executed so that plugins are registered with FlowQuery
-import './loaders/FetchJson';
-import './loaders/CatFacts';
-import './loaders/MockData';
-import './loaders/Llm';
-import './loaders/Table';
-import './loaders/Form';
-import './loaders/Weather';
-
-/**
- * Initialize plugins.
- * Plugins are auto-registered via @FunctionDef decorators when imported.
- * This function just logs the registered plugins for debugging.
- */
-export function initializePlugins(): void {
-    const plugins = getLoadedPluginNames();
-    console.log(`FlowQuery plugins loaded: ${plugins.join(', ')}`);
-}
-
-/**
- * Get the list of loaded plugin names.
- * Uses FlowQuery's introspection to discover registered async providers.
- */
-export function getLoadedPluginNames(): string[] {
-    return FlowQuery.listFunctions({ asyncOnly: true }).map(f => f.name);
-}
-
-/**
- * Get metadata for all loaded plugins.
- * Uses FlowQuery's functions() introspection as the single source of truth.
- */
-export function getAllPluginMetadata(): FunctionMetadata[] {
-    return FlowQuery.listFunctions({ asyncOnly: true });
-}
-
-/**
- * Get all available async loader plugins by querying FlowQuery directly.
- * This is the preferred async method that uses functions() introspection.
- * 
- * @returns Promise resolving to array of plugin metadata
- */
-export async function getAvailableLoaders(): Promise<FunctionMetadata[]> {
-    const runner = new FlowQuery(`
-        WITH functions() AS funcs 
-        UNWIND funcs AS f 
-        WHERE f.isAsyncProvider = true
-        RETURN f
-    `);
-    await runner.run();
-    return runner.results.map((r: any) => r.expr0 as FunctionMetadata);
-}
-
-// Re-export types for external use
-export type { FunctionMetadata, FunctionDefOptions, ParameterSchema, OutputSchema } from 'flowquery/extensibility';
-export { FunctionDef } from 'flowquery/extensibility';
-
-// Re-export standalone loader functions for use outside of FlowQuery
-export { llm, llmStream, extractContent } from './loaders/Llm';
-export type { LlmOptions, LlmResponse } from './loaders/Llm';

package/misc/apps/RAG/src/plugins/loaders/CatFacts.ts

@@ -1,70 +0,0 @@
-/**
- * Example plugin: Fetch random cat facts from the Cat Facts API.
- *
- * Usage in FlowQuery:
- *   CALL catFacts(5) YIELD text, length
- */
-import { AsyncFunction, FunctionDef } from "flowquery/extensibility";
-
-const CAT_FACTS_API = "https://catfact.ninja/facts";
-
-/**
- * CatFacts class - fetches random cat facts from the Cat Facts API.
- */
-@FunctionDef({
-    description: "Fetches random cat facts from the Cat Facts API (catfact.ninja)",
-    category: "async",
-    parameters: [
-        {
-            name: "count",
-            description: "Number of cat facts to fetch",
-            type: "number",
-            required: false,
-            default: 1,
-        },
-    ],
-    output: {
-        description: "Cat fact object",
-        type: "object",
-        properties: {
-            text: { description: "The cat fact text", type: "string" },
-            length: { description: "Length of the fact text", type: "number" },
-        },
-    },
-    examples: ["CALL catFacts() YIELD text", "CALL catFacts(5) YIELD text, length"],
-})
-export class CatFacts extends AsyncFunction {
-    private readonly apiUrl: string;
-
-    constructor(apiUrl: string = CAT_FACTS_API) {
-        super();
-        this.apiUrl = apiUrl;
-    }
-
-    /**
-     * Fetches random cat facts from the Cat Facts API.
-     *
-     * @param count - Number of cat facts to fetch (default: 1)
-     */
-    async *generate(count: number = 1): AsyncGenerator<any, void, unknown> {
-        const url = `${this.apiUrl}?limit=${count}`;
-        const response = await fetch(url);
-
-        if (!response.ok) {
-            throw new Error(`Failed to fetch cat facts: ${response.statusText}`);
-        }
-
-        const json = await response.json();
-        const data = json.data || [];
-
-        for (const item of data) {
-            // Map 'fact' to 'text' for backwards compatibility with existing queries
-            yield {
-                text: item.fact,
-                length: item.length,
-            };
-        }
-    }
-}
-
-export default CatFacts;

package/misc/apps/RAG/src/plugins/loaders/FetchJson.ts

@@ -1,65 +0,0 @@
-/**
- * Example plugin: Fetch JSON data from a URL.
- *
- * Usage in FlowQuery:
- *   CALL fetchJson('https://api.example.com/data') YIELD name, value
- */
-import { AsyncFunction, FunctionDef } from "flowquery/extensibility";
-
-/**
- * FetchJson class - fetches JSON data from a URL and yields items.
- */
-@FunctionDef({
-    description:
-        "Fetches JSON data from a URL. If the response is an array, yields each item individually.",
-    category: "async",
-    parameters: [
-        {
-            name: "url",
-            description: "The URL to fetch JSON from",
-            type: "string",
-            required: true,
-        },
-        {
-            name: "options",
-            description: "Optional fetch options (headers, method, etc.)",
-            type: "object",
-            required: false,
-        },
-    ],
-    output: {
-        description: "JSON data items",
-        type: "object",
-    },
-    examples: [
-        "CALL fetchJson('https://api.example.com/users') YIELD name",
-        "CALL fetchJson('https://api.example.com/data') YIELD name, active WHERE active = true",
-    ],
-})
-export class FetchJson extends AsyncFunction {
-    /**
-     * Fetches JSON data from a URL and yields each item if array, or the object itself.
-     *
-     * @param url - The URL to fetch JSON from
-     * @param options - Optional fetch options
-     */
-    async *generate(url: string, options?: RequestInit): AsyncGenerator<any, void, unknown> {
-        const response = await fetch(url, options);
-
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-
-        const data = await response.json();
-
-        if (Array.isArray(data)) {
-            for (const item of data) {
-                yield item;
-            }
-        } else {
-            yield data;
-        }
-    }
-}
-
-export default FetchJson;