fix: background query overwrote yasr instead of extending it

Author: MathiasVDA

docs/developer-guide.md

@@ -1277,9 +1277,22 @@ interface YasrConfig {
 
   // Error renderers
   errorRenderers?: ErrorRenderer[];
+
+  // Optional callback enabling plugins to execute background SPARQL queries
+  executeQuery?: (query: string, options?: PluginQueryOptions) => Promise<any>;
+}
+
+interface PluginQueryOptions {
+  // Custom Accept header for the request (e.g. "text/turtle", "application/sparql-results+json")
+  acceptHeader?: string;
+  // Abort signal for cancelling in-flight background queries
+  signal?: AbortSignal;
 }
 ```
 
+When YASR is used inside a Yasgui `Tab`, the `executeQuery` callback is automatically
+wired up. When using YASR standalone, you must provide your own implementation.
+
 #### YASR Example
 
 ```javascript
@@ -2253,6 +2266,42 @@ const plugins = yasr.getPlugins();
 console.log('Available plugins:', Object.keys(plugins));
 ```
 
+##### `executeQuery(query: string, options?: PluginQueryOptions): Promise<any>`
+
+Execute a background SPARQL query on behalf of a plugin. This delegates to the
+`executeQuery` callback in the YASR configuration and returns the raw response
+without replacing the currently displayed results.
+
+The returned response object has the following shape:
+
+```typescript
+{
+  ok: boolean;          // true if HTTP status is 2xx
+  status: number;       // HTTP status code
+  statusText: string;   // HTTP status text
+  headers: Headers;     // Response headers
+  content: string;      // Raw response body
+  data: string;         // Alias for content
+  json(): Promise<any>; // Parse content as JSON
+  text(): Promise<string>; // Return content as string
+}
+```
+
+Plugins can use this to fetch additional data (e.g. expanding a node in a graph
+visualization) without interfering with the main query results.
+
+```javascript
+// Inside a plugin
+const response = await this.yasr.executeQuery(
+  'DESCRIBE <http://example.org/resource>',
+  { acceptHeader: 'text/turtle' }
+);
+const turtle = await response.text();
+```
+
+If no `executeQuery` callback is configured, the returned Promise rejects with
+an error.
+
 ##### `download(filename?: string): void`
 
 Download results using current plugin's download method.
@@ -2520,6 +2569,41 @@ interface Plugin<Options = any> {
   download?(filename?: string): DownloadInfo | undefined;
 }
 
+#### Background Queries from Plugins
+
+Plugins can execute additional SPARQL queries via `this.yasr.executeQuery()`
+without overwriting the currently displayed results. This is useful for
+interactive features like expanding a node in a graph visualization.
+
+The query runs in **silent mode** — no YASQE lifecycle events (`queryBefore`,
+`queryResponse`, etc.) are emitted and `yasr.setResponse()` is not called, so
+the visible results remain unchanged.
+
+```typescript
+// Example: fetch additional data when a user interacts with a result
+async expandNode(uri: string): Promise<void> {
+  const controller = new AbortController();
+
+  const response = await this.yasr.executeQuery(
+    `DESCRIBE <${uri}>`,
+    {
+      acceptHeader: 'text/turtle',
+      signal: controller.signal,
+    }
+  );
+
+  const body = await response.text();
+  // … parse and merge into the current visualization
+}
+```
+
+**Response shape** — see [`executeQuery()` method](#executequeryquery-string-options-pluginqueryoptions-promiseany)
+for the full response object description.
+
+**Cancellation** — pass an `AbortSignal` via `options.signal` to cancel
+in-flight requests (e.g. when the user navigates away or triggers a new
+expansion before the previous one finishes).
+
 interface DownloadInfo {
   contentType: string;
   getData: () => string;

package-lock.json

@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@fortawesome/fontawesome-free": "^7.1.0",
-    "@matdata/yasgui-graph-plugin": "^1.5.0",
+    "@matdata/yasgui-graph-plugin": "^1.6.1",
     "@matdata/yasgui-table-plugin": "^1.3.0",
     "@typescript-eslint/eslint-plugin": "^6.13.2",
     "@typescript-eslint/parser": "^6.13.2",

package.json

@@ -33,8 +33,8 @@
     "jsuri": "^1.3.1",
     "lodash-es": "^4.17.15",
     "sortablejs": "^1.10.2",
-    "@matdata/yasgui-graph-plugin": "^1.4.1",
-    "@matdata/yasgui-table-plugin": "^1.1.0"
+    "@matdata/yasgui-graph-plugin": "^1.6.1",
+    "@matdata/yasgui-table-plugin": "^1.3.0"
   },
   "devDependencies": {
     "@types/autosuggest-highlight": "^3.1.0",

packages/yasgui/package.json

@@ -3,7 +3,13 @@ import { addClass, removeClass, getAsValue } from "@matdata/yasgui-utils";
 import { TabListEl } from "./TabElements";
 import TabSettingsModal from "./TabSettingsModal";
 import { default as Yasqe, RequestConfig, PlainRequestConfig, PartialConfig as YasqeConfig } from "@matdata/yasqe";
-import { default as Yasr, Parser, Config as YasrConfig, PersistentConfig as YasrPersistentConfig } from "@matdata/yasr";
+import {
+  default as Yasr,
+  Parser,
+  Config as YasrConfig,
+  PersistentConfig as YasrPersistentConfig,
+  PluginQueryOptions as YasrPluginQueryOptions,
+} from "@matdata/yasr";
 import { mapValues, eq, mergeWith, words, deburr, invert } from "lodash-es";
 import * as shareLink from "./linkUtils";
 import EndpointSelect from "./endpointSelect";
@@ -1584,6 +1590,7 @@ WHERE {
         {
           customQuery: query,
           customAccept: "text/turtle",
+          silent: true,
         },
       );
 
@@ -1672,12 +1679,15 @@ WHERE {
         // Add default renderers to the end, to give our custom ones priority.
         ...(Yasr.defaults.errorRenderers || []),
       ],
-      executeQuery: async (query: string, options?: { acceptHeader?: string }) => {
+      executeQuery: async (query: string, options?: YasrPluginQueryOptions) => {
         if (!this.yasqe) throw new Error("No YASQE instance available");
-        return Yasqe.Sparql.executeQuery(this.yasqe, undefined, {
+        const response = await Yasqe.Sparql.executeQuery(this.yasqe, undefined, {
           customQuery: query,
           customAccept: options?.acceptHeader,
+          signal: options?.signal,
+          silent: true,
         });
+        return response;
       },
     };
     // Allow getDownloadFilName to be overwritten by the global config

packages/yasgui/src/Tab.ts

@@ -174,6 +174,13 @@ export function getAjaxConfig(
 export interface ExecuteQueryOptions {
   customQuery?: string;
   customAccept?: string;
+  /** Optional external abort signal, useful for plugin-driven background fetches. */
+  signal?: AbortSignal;
+  /**
+   * Execute without emitting Yasqe query lifecycle events.
+   * Useful for background/plugin-driven queries that should not update main UI state.
+   */
+  silent?: boolean;
 }
 
 export async function executeQuery(
@@ -182,13 +189,21 @@ export async function executeQuery(
   options?: ExecuteQueryOptions,
 ): Promise<any> {
   const queryStart = Date.now();
+  const silent = !!options?.silent;
   try {
-    yasqe.emit("queryBefore", yasqe, config);
+    if (!silent) yasqe.emit("queryBefore", yasqe, config);
     const populatedConfig = getAjaxConfig(yasqe, config);
     if (!populatedConfig) {
       return; // Nothing to query
     }
     const abortController = new AbortController();
+    if (options?.signal) {
+      if (options.signal.aborted) {
+        abortController.abort();
+      } else {
+        options.signal.addEventListener("abort", () => abortController.abort(), { once: true });
+      }
+    }
 
     // Use custom accept header if provided, otherwise use the default
     const acceptHeader = options?.customAccept || populatedConfig.accept;
@@ -256,17 +271,22 @@ export async function executeQuery(
       populatedConfig.url = url.toString();
     }
     const request = new Request(populatedConfig.url, fetchOptions);
-    yasqe.emit("query", request, abortController);
+    if (!silent) yasqe.emit("query", request, abortController);
     const response = await fetch(request);
 
     // Await the response content and merge with the `Response` object
+    const content = await response.text();
     const queryResponse = {
       ok: response.ok,
       status: response.status,
       statusText: response.statusText,
       headers: response.headers,
       type: response.type,
-      content: await response.text(),
+      content,
+      // Compatibility aliases for plugins that expect fetch-like or axios-like response objects.
+      data: content,
+      json: async () => JSON.parse(content),
+      text: async () => content,
     };
 
     if (!response.ok) {
@@ -278,8 +298,10 @@ export async function executeQuery(
       throw error;
     }
 
-    yasqe.emit("queryResponse", queryResponse, Date.now() - queryStart);
-    yasqe.emit("queryResults", queryResponse.content, Date.now() - queryStart);
+    if (!silent) {
+      yasqe.emit("queryResponse", queryResponse, Date.now() - queryStart);
+      yasqe.emit("queryResults", queryResponse.content, Date.now() - queryStart);
+    }
     return queryResponse;
   } catch (e) {
     if (e instanceof Error && e.message === "Aborted") {
@@ -292,12 +314,12 @@ export async function executeQuery(
         if (e.message.includes("Failed to fetch") || e.message.includes("NetworkError")) {
           enhancedError.message = `${e.message}. The server may have returned an error response (check browser dev tools), but CORS headers are preventing JavaScript from accessing it. Ensure the endpoint returns proper CORS headers even for error responses (Access-Control-Allow-Origin, etc.).`;
         }
-        yasqe.emit("queryResponse", enhancedError, Date.now() - queryStart);
+        if (!silent) yasqe.emit("queryResponse", enhancedError, Date.now() - queryStart);
       } else {
-        yasqe.emit("queryResponse", e, Date.now() - queryStart);
+        if (!silent) yasqe.emit("queryResponse", e, Date.now() - queryStart);
       }
     }
-    yasqe.emit("error", e);
+    if (!silent) yasqe.emit("error", e);
     throw e;
   }
 }

packages/yasqe/src/sparql.ts

@@ -661,6 +661,8 @@ export type Prefixes = { [prefixLabel: string]: string };
 export interface PluginQueryOptions {
   /** Optional custom Accept header for the request (e.g. "text/turtle"). */
   acceptHeader?: string;
+  /** Optional abort signal for cancelling in-flight background queries. */
+  signal?: AbortSignal;
 }
 
 export interface PluginConfig {