@comake/skl-js-engine 1.5.4 → 1.5.6

package/dist/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.d.ts

@@ -0,0 +1,27 @@
+import type { Quad } from '@rdfjs/types';
+import type { AskQuery, ConstructQuery, SelectQuery, Update } from 'sparqljs';
+import type { QueryExecutor, SelectVariableQueryResult } from './SparqlQueryExecutor';
+export interface SparqlEndpointQueryExecutorOptions {
+    /**
+     * The location of the SPARQL endpoint. This value is required.
+     */
+    readonly endpointUrl: string;
+    /**
+     * The location of the SPARQL update endpoint. Defaults to the value of endpointUrl if not set.
+     */
+    readonly updateUrl?: string;
+}
+export declare class SparqlEndpointQueryExecutor implements QueryExecutor {
+    private readonly sparqlClient;
+    private readonly sparqlGenerator;
+    private readonly logger;
+    constructor(options: SparqlEndpointQueryExecutorOptions);
+    executeSparqlSelectAndGetData<TQuery extends SelectQuery | ConstructQuery, TReturn extends SelectVariableQueryResult<any> | Quad = TQuery extends SelectQuery ? SelectVariableQueryResult<any> : Quad>(query: TQuery): Promise<TReturn[]>;
+    executeSparqlSelectAndGetDataRaw<T extends Quad | SelectVariableQueryResult<any> = Quad>(query: string): Promise<T[]>;
+    executeSparqlConstructAndGetDataRaw(query: string): Promise<Quad[]>;
+    executeSparqlUpdate(query: Update): Promise<void>;
+    executeRawSparqlUpdate(query: string): Promise<void>;
+    executeAskQueryAndGetResponse(query: AskQuery): Promise<boolean>;
+    executeSelectCountAndGetResponse(query: SelectQuery): Promise<number>;
+}
+//# sourceMappingURL=SparqlEndpointQueryExecutor.d.ts.map

package/dist/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SparqlEndpointQueryExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,WAAW,EAEX,MAAM,EACP,MAAM,UAAU,CAAC;AAIlB,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,MAAM,WAAW,kCAAkC;IACjD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,2BAA4B,YAAW,aAAa;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBACb,OAAO,EAAE,kCAAkC;IASjD,6BAA6B,CACxC,MAAM,SAAS,WAAW,GAAG,cAAc,EAC3C,OAAO,SAAS,yBAAyB,CAAC,GAAG,CAAC,GAAG,IAAI,GACrD,MAAM,SAAS,WAAW,GAAG,yBAAyB,CAAC,GAAG,CAAC,GAAG,IAAI,EAElE,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,EAAE,CAAC;IAKR,gCAAgC,CAAC,CAAC,SAAS,IAAI,GAAG,yBAAyB,CAAC,GAAG,CAAC,GAAG,IAAI,EAClG,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,EAAE,CAAC;IA2BF,mCAAmC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAYnE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpD,6BAA6B,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAahE,gCAAgC,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CA0BnF"}

package/dist/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SparqlEndpointQueryExecutor = void 0;
+const sparql_http_client_1 = __importDefault(require("sparql-http-client"));
+const sparqljs_1 = require("sparqljs");
+const logger_1 = require("../../../../logger");
+const PerformanceLogger_1 = require("../../../../util/PerformanceLogger");
+class SparqlEndpointQueryExecutor {
+    constructor(options) {
+        this.sparqlClient = new sparql_http_client_1.default({
+            endpointUrl: options.endpointUrl,
+            updateUrl: options.updateUrl ?? options.endpointUrl
+        });
+        this.sparqlGenerator = new sparqljs_1.Generator();
+        this.logger = logger_1.Logger.getInstance();
+    }
+    async executeSparqlSelectAndGetData(query) {
+        const generatedQuery = this.sparqlGenerator.stringify(query);
+        return this.executeSparqlSelectAndGetDataRaw(generatedQuery);
+    }
+    async executeSparqlSelectAndGetDataRaw(query) {
+        const span = PerformanceLogger_1.PerformanceLogger.startSpan('SPARQL.SELECT', { query });
+        try {
+            // This.logger.debug(query);
+            const stream = await this.sparqlClient.query.select(query, { operation: 'postUrlencoded' });
+            const result = await new Promise((resolve, reject) => {
+                const data = [];
+                stream.on('data', (row) => {
+                    data.push(row);
+                });
+                stream.on('end', () => {
+                    resolve(data);
+                });
+                stream.on('error', (error) => {
+                    reject(error);
+                });
+            });
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { resultCount: result.length });
+            return result;
+        }
+        catch (error) {
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { error: true });
+            throw error;
+        }
+    }
+    async executeSparqlConstructAndGetDataRaw(query) {
+        const span = PerformanceLogger_1.PerformanceLogger.startSpan('SPARQL.CONSTRUCT', { query });
+        try {
+            const result = await this.executeSparqlSelectAndGetDataRaw(query);
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { resultCount: result.length });
+            return result;
+        }
+        catch (error) {
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { error: true });
+            throw error;
+        }
+    }
+    async executeSparqlUpdate(query) {
+        const generatedQuery = this.sparqlGenerator.stringify(query);
+        await this.executeRawSparqlUpdate(generatedQuery);
+    }
+    async executeRawSparqlUpdate(query) {
+        const span = PerformanceLogger_1.PerformanceLogger.startSpan('SPARQL.UPDATE', { query });
+        try {
+            await this.sparqlClient.query.update(query);
+            PerformanceLogger_1.PerformanceLogger.endSpan(span);
+        }
+        catch (error) {
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { error: true });
+            throw error;
+        }
+    }
+    async executeAskQueryAndGetResponse(query) {
+        const generatedQuery = this.sparqlGenerator.stringify(query);
+        const span = PerformanceLogger_1.PerformanceLogger.startSpan('SPARQL.ASK', { query: generatedQuery });
+        try {
+            const result = await this.sparqlClient.query.ask(generatedQuery);
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { result });
+            return result;
+        }
+        catch (error) {
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { error: true });
+            throw error;
+        }
+    }
+    async executeSelectCountAndGetResponse(query) {
+        const generatedQuery = this.sparqlGenerator.stringify(query);
+        const span = PerformanceLogger_1.PerformanceLogger.startSpan('SPARQL.COUNT', { query: generatedQuery });
+        try {
+            const stream = await this.sparqlClient.query.select(generatedQuery, { operation: 'postUrlencoded' });
+            const countValue = await new Promise((resolve, reject) => {
+                let count;
+                stream.on('data', (row) => {
+                    count = Number.parseInt(row.count.value, 10);
+                });
+                stream.on('end', () => {
+                    resolve(count);
+                });
+                stream.on('error', (error) => {
+                    reject(error);
+                });
+            });
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { count: countValue });
+            return countValue;
+        }
+        catch (error) {
+            PerformanceLogger_1.PerformanceLogger.endSpan(span, { error: true });
+            throw error;
+        }
+    }
+}
+exports.SparqlEndpointQueryExecutor = SparqlEndpointQueryExecutor;
+//# sourceMappingURL=SparqlEndpointQueryExecutor.js.map

package/dist/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SparqlEndpointQueryExecutor.js","sourceRoot":"","sources":["../../../../../src/storage/query-adapter/sparql/query-executor/SparqlEndpointQueryExecutor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Literal, Quad } from '@rdfjs/types';\nimport SparqlClient from 'sparql-http-client';\nimport type {\n  AskQuery,\n  ConstructQuery,\n  SelectQuery,\n  SparqlGenerator,\n  Update\n} from 'sparqljs';\nimport { Generator } from 'sparqljs';\nimport { Logger } from '../../../../logger';\nimport { PerformanceLogger } from '../../../../util/PerformanceLogger';\nimport type { QueryExecutor, SelectVariableQueryResult } from './SparqlQueryExecutor';\n\nexport interface SparqlEndpointQueryExecutorOptions {\n  /**\n   * The location of the SPARQL endpoint. This value is required.\n   */\n  readonly endpointUrl: string;\n  /**\n   * The location of the SPARQL update endpoint. Defaults to the value of endpointUrl if not set.\n   */\n  readonly updateUrl?: string;\n}\n\nexport class SparqlEndpointQueryExecutor implements QueryExecutor {\n  private readonly sparqlClient: SparqlClient;\n  private readonly sparqlGenerator: SparqlGenerator;\n  private readonly logger: Logger;\n  public constructor(options: SparqlEndpointQueryExecutorOptions) {\n    this.sparqlClient = new SparqlClient({\n      endpointUrl: options.endpointUrl,\n      updateUrl: options.updateUrl ?? options.endpointUrl\n    });\n    this.sparqlGenerator = new Generator();\n    this.logger = Logger.getInstance();\n  }\n\n  public async executeSparqlSelectAndGetData<\n    TQuery extends SelectQuery | ConstructQuery,\n    TReturn extends SelectVariableQueryResult<any> | Quad =\n    TQuery extends SelectQuery ? SelectVariableQueryResult<any> : Quad\n  >(\n    query: TQuery\n  ): Promise<TReturn[]> {\n    const generatedQuery = this.sparqlGenerator.stringify(query);\n    return this.executeSparqlSelectAndGetDataRaw(generatedQuery);\n  }\n\n  public async executeSparqlSelectAndGetDataRaw<T extends Quad | SelectVariableQueryResult<any> = Quad>(\n    query: string\n  ): Promise<T[]> {\n    const span = PerformanceLogger.startSpan('SPARQL.SELECT', { query });\n    try {\n      // This.logger.debug(query);\n      const stream = await this.sparqlClient.query.select(query, { operation: 'postUrlencoded' });\n      const result = await new Promise<T[]>((resolve, reject): void => {\n        const data: T[] = [];\n        stream.on('data', (row): void => {\n          data.push(row);\n        });\n\n        stream.on('end', (): void => {\n          resolve(data);\n        });\n\n        stream.on('error', (error): void => {\n          reject(error);\n        });\n      });\n      PerformanceLogger.endSpan(span, { resultCount: result.length });\n      return result;\n    } catch (error) {\n      PerformanceLogger.endSpan(span, { error: true });\n      throw error;\n    }\n  }\n\n  public async executeSparqlConstructAndGetDataRaw(query: string): Promise<Quad[]> {\n    const span = PerformanceLogger.startSpan('SPARQL.CONSTRUCT', { query });\n    try {\n      const result = await this.executeSparqlSelectAndGetDataRaw(query);\n      PerformanceLogger.endSpan(span, { resultCount: result.length });\n      return result;\n    } catch (error) {\n      PerformanceLogger.endSpan(span, { error: true });\n      throw error;\n    }\n  }\n\n  public async executeSparqlUpdate(query: Update): Promise<void> {\n    const generatedQuery = this.sparqlGenerator.stringify(query);\n    await this.executeRawSparqlUpdate(generatedQuery);\n  }\n\n  public async executeRawSparqlUpdate(query: string): Promise<void> {\n    const span = PerformanceLogger.startSpan('SPARQL.UPDATE', { query });\n    try {\n      await this.sparqlClient.query.update(query);\n      PerformanceLogger.endSpan(span);\n    } catch (error) {\n      PerformanceLogger.endSpan(span, { error: true });\n      throw error;\n    }\n  }\n\n  public async executeAskQueryAndGetResponse(query: AskQuery): Promise<boolean> {\n    const generatedQuery = this.sparqlGenerator.stringify(query);\n    const span = PerformanceLogger.startSpan('SPARQL.ASK', { query: generatedQuery });\n    try {\n      const result = await this.sparqlClient.query.ask(generatedQuery);\n      PerformanceLogger.endSpan(span, { result });\n      return result;\n    } catch (error) {\n      PerformanceLogger.endSpan(span, { error: true });\n      throw error;\n    }\n  }\n\n  public async executeSelectCountAndGetResponse(query: SelectQuery): Promise<number> {\n    const generatedQuery = this.sparqlGenerator.stringify(query);\n    const span = PerformanceLogger.startSpan('SPARQL.COUNT', { query: generatedQuery });\n    try {\n      const stream = await this.sparqlClient.query.select(generatedQuery, { operation: 'postUrlencoded' });\n      const countValue = await new Promise<number>((resolve, reject): void => {\n        let count: number;\n        stream.on('data', (row: { count: Literal }): void => {\n          count = Number.parseInt(row.count.value, 10);\n        });\n\n        stream.on('end', (): void => {\n          resolve(count);\n        });\n\n        stream.on('error', (error): void => {\n          reject(error);\n        });\n      });\n      PerformanceLogger.endSpan(span, { count: countValue });\n      return countValue;\n    } catch (error) {\n      PerformanceLogger.endSpan(span, { error: true });\n      throw error;\n    }\n  }\n}\n"]}

package/dist/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.d.ts

@@ -0,0 +1,34 @@
+import type { Quad, Literal, NamedNode } from '@rdfjs/types';
+import type { Update, AskQuery, SelectQuery, ConstructQuery } from 'sparqljs';
+export declare type SelectVariableQueryResult<T> = Record<keyof T, NamedNode | Literal>;
+export interface QueryExecutor {
+    /**
+     * Executes a SPARQL select or construct query.
+     */
+    executeSparqlSelectAndGetData<TQuery extends SelectQuery | ConstructQuery, TReturn extends SelectVariableQueryResult<any> | Quad = TQuery extends SelectQuery ? SelectVariableQueryResult<any> : Quad>(query: TQuery): Promise<TReturn[]>;
+    /**
+     * Executes a raw SPARQL select query.
+     */
+    executeSparqlSelectAndGetDataRaw(query: string): Promise<SelectVariableQueryResult<any>[]>;
+    /**
+     * Executes a raw SPARQL construct query.
+     */
+    executeSparqlConstructAndGetDataRaw(query: string): Promise<Quad[]>;
+    /**
+     * Executes a SPARQL update query.
+     */
+    executeSparqlUpdate(query: Update): Promise<void>;
+    /**
+     * Executes a raw SPARQL update query.
+     */
+    executeRawSparqlUpdate(query: string): Promise<void>;
+    /**
+     * Executes a SPARQL ask query.
+     */
+    executeAskQueryAndGetResponse(query: AskQuery): Promise<boolean>;
+    /**
+     * Executes a SPARQL select query.
+     */
+    executeSelectCountAndGetResponse(query: SelectQuery): Promise<number>;
+}
+//# sourceMappingURL=SparqlQueryExecutor.d.ts.map

package/dist/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SparqlQueryExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EACR,WAAW,EACX,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,oBAAY,yBAAyB,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,6BAA6B,CAC3B,MAAM,SAAS,WAAW,GAAG,cAAc,EAC3C,OAAO,SAAS,yBAAyB,CAAC,GAAG,CAAC,GAAG,IAAI,GACrD,MAAM,SAAS,WAAW,GAAG,yBAAyB,CAAC,GAAG,CAAC,GAAG,IAAI,EAElE,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACtB;;OAEG;IACH,gCAAgC,CAC9B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7C;;OAEG;IACH,mCAAmC,CACjC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACnB;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;OAEG;IACH,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;OAEG;IACH,6BAA6B,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE;;OAEG;IACH,gCAAgC,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE"}

package/dist/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=SparqlQueryExecutor.js.map

package/dist/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SparqlQueryExecutor.js","sourceRoot":"","sources":["../../../../../src/storage/query-adapter/sparql/query-executor/SparqlQueryExecutor.ts"],"names":[],"mappings":"","sourcesContent":["/* eslint-disable @typescript-eslint/method-signature-style */\nimport type { Quad, Literal, NamedNode } from '@rdfjs/types';\nimport type {\n  Update,\n  AskQuery,\n  SelectQuery,\n  ConstructQuery\n} from 'sparqljs';\n\nexport type SelectVariableQueryResult<T> = Record<keyof T, NamedNode | Literal>;\n\nexport interface QueryExecutor {\n  /**\n   * Executes a SPARQL select or construct query.\n   */\n  executeSparqlSelectAndGetData<\n    TQuery extends SelectQuery | ConstructQuery,\n    TReturn extends SelectVariableQueryResult<any> | Quad =\n    TQuery extends SelectQuery ? SelectVariableQueryResult<any> : Quad\n  >(\n    query: TQuery,\n  ): Promise<TReturn[]>;\n  /**\n   * Executes a raw SPARQL select query.\n   */\n  executeSparqlSelectAndGetDataRaw(\n    query: string,\n  ): Promise<SelectVariableQueryResult<any>[]>;\n  /**\n   * Executes a raw SPARQL construct query.\n   */\n  executeSparqlConstructAndGetDataRaw(\n    query: string,\n  ): Promise<Quad[]>;\n  /**\n   * Executes a SPARQL update query.\n   */\n  executeSparqlUpdate(query: Update): Promise<void>;\n  /**\n   * Executes a raw SPARQL update query.\n   */\n  executeRawSparqlUpdate(query: string,): Promise<void>;\n  /**\n   * Executes a SPARQL ask query.\n   */\n  executeAskQueryAndGetResponse(query: AskQuery): Promise<boolean>;\n  /**\n   * Executes a SPARQL select query.\n   */\n  executeSelectCountAndGetResponse(query: SelectQuery): Promise<number>;\n}\n"]}

package/dist/tools/explain-findall-sparql.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=explain-findall-sparql.d.ts.map

package/dist/tools/explain-findall-sparql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-findall-sparql.d.ts","sourceRoot":"","sources":["../../src/tools/explain-findall-sparql.ts"],"names":[],"mappings":""}

package/dist/tools/explain-findall-sparql.js

@@ -0,0 +1,303 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable */
+/* eslint-comments/no-unlimited-disable */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const data_model_1 = __importDefault(require("@rdfjs/data-model"));
+const sparqljs_1 = require("sparqljs");
+const SparqlQueryBuilder_1 = require("../storage/query-adapter/sparql/SparqlQueryBuilder");
+const SparqlUtil_1 = require("../util/SparqlUtil");
+const Util_1 = require("../util/Util");
+function usageAndExit(exitCode) {
+    const msg = [
+        'Usage:',
+        '  node dist/tools/explain-findall-sparql.js --input <file.json> [--format text|json] [--simulate-entity-values N]',
+        '',
+        'Input JSON can be either:',
+        '  1) a full FindAllOptions object: { "where": { ... }, "relations": { ... }, "order": { ... }, "limit": 10, ... }',
+        '  2) a FindOptionsWhere object (treated as { where: <object> })',
+        '',
+        'Notes:',
+        '  - This utility does not query a SPARQL endpoint. When findAll would inject VALUES(?entity) from a pre-SELECT,',
+        '    you can pass --simulate-entity-values N to show an example VALUES block with N placeholder IRIs.',
+        ''
+    ].join('\n');
+    console.error(msg);
+    process.exit(exitCode);
+}
+function parseArgs(argv) {
+    const out = {
+        format: 'text',
+        simulateEntityValues: 0
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--help' || arg === '-h') {
+            usageAndExit(0);
+        }
+        if (arg === '--input' || arg === '-i') {
+            out.input = argv[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--format' || arg === '-f') {
+            const v = argv[i + 1];
+            if (v !== 'text' && v !== 'json') {
+                console.error(`Invalid --format: ${String(v)}`);
+                usageAndExit(2);
+            }
+            out.format = v;
+            i += 1;
+            continue;
+        }
+        if (arg === '--simulate-entity-values') {
+            const v = Number.parseInt(argv[i + 1] ?? '', 10);
+            if (!Number.isFinite(v) || v < 0) {
+                console.error(`Invalid --simulate-entity-values: ${argv[i + 1]}`);
+                usageAndExit(2);
+            }
+            out.simulateEntityValues = v;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            console.error(`Unknown arg: ${arg}`);
+            usageAndExit(2);
+        }
+    }
+    return out;
+}
+function readJsonFile(p) {
+    const abs = path_1.default.isAbsolute(p) ? p : path_1.default.join(process.cwd(), p);
+    const raw = fs_1.default.readFileSync(abs, 'utf8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse JSON from ${abs}: ${e.message}`);
+    }
+}
+function coerceSparqlVariable(v) {
+    if (!v)
+        return undefined;
+    if (typeof v === 'string') {
+        const name = v.startsWith('?') ? v.slice(1) : v;
+        return data_model_1.default.variable(name);
+    }
+    if (typeof v === 'object' && v.termType === 'Variable' && typeof v.value === 'string') {
+        return v;
+    }
+    return undefined;
+}
+function normalizeFindAllOptions(input) {
+    const asOptions = typeof input === 'object' &&
+        input !== null &&
+        ('where' in input || 'select' in input || 'relations' in input || 'order' in input || 'limit' in input || 'offset' in input || 'subQueries' in input);
+    const options = asOptions ? input : { where: input };
+    // Allow simple JSON-friendly forms for variables.
+    const group = coerceSparqlVariable(options.group);
+    const entitySelectVariable = coerceSparqlVariable(options.entitySelectVariable);
+    const subQueries = Array.isArray(options.subQueries)
+        ? options.subQueries.map((sq) => {
+            const select = Array.isArray(sq?.select) ? sq.select.map(coerceSparqlVariable).filter(Boolean) : sq?.select;
+            return { ...sq, ...(select ? { select } : {}) };
+        })
+        : options.subQueries;
+    return {
+        ...options,
+        ...(group ? { group } : {}),
+        ...(entitySelectVariable ? { entitySelectVariable } : {}),
+        ...(subQueries ? { subQueries } : {})
+    };
+}
+function stringifyQuery(query) {
+    const gen = new sparqljs_1.Generator();
+    return gen.stringify(query);
+}
+function buildEntitySelectQueryForFindAll(selectQueryData, options) {
+    // Mirrors SparqlQueryAdapter.buildFindAllQueryData() for the entitySelectQuery creation.
+    const wherePatterns = [...selectQueryData.where, ...selectQueryData.graphWhere];
+    wherePatterns.push({
+        type: 'bgp',
+        triples: [
+            {
+                subject: SparqlUtil_1.entityVariable,
+                predicate: SparqlUtil_1.rdfTypeNamedNode,
+                object: SparqlUtil_1.rdfTypeVariable
+            }
+        ]
+    });
+    const entitySelectVariable = options?.entitySelectVariable ?? SparqlUtil_1.entityVariable;
+    const groupBy = (0, Util_1.ensureArray)(selectQueryData?.group ?? options?.group ?? []);
+    groupBy.push(entitySelectVariable);
+    // All non-aggregated variables in SELECT must be in GROUP BY
+    for (const selectVariable of selectQueryData.selectVariables ?? []) {
+        const expr = selectVariable.expression;
+        if (!('aggregation' in expr) && expr?.constructor?.name === 'Variable') {
+            groupBy.push(expr);
+        }
+    }
+    if (selectQueryData.where.length === 0) {
+        return undefined;
+    }
+    return (0, SparqlUtil_1.createSparqlSelectQuery)([
+        entitySelectVariable,
+        // (GROUP_CONCAT(DISTINCT str(?rdfType); SEPARATOR = " | ") AS ?rdfTypes)
+        {
+            expression: {
+                type: 'aggregate',
+                aggregation: 'group_concat',
+                separator: ' | ',
+                distinct: true,
+                expression: {
+                    type: 'operation',
+                    operator: 'STR',
+                    args: [SparqlUtil_1.rdfTypeVariable]
+                }
+            },
+            variable: SparqlUtil_1.rdfTypesVariable
+        },
+        ...(selectQueryData.selectVariables?.map(({ variable, expression }) => {
+            if (!expression)
+                return variable;
+            return { variable, expression };
+        }) ?? [])
+    ], wherePatterns, selectQueryData.orders, groupBy, options?.limit, options?.offset);
+}
+function simulateEntityIdValues(n) {
+    const values = [];
+    for (let i = 1; i <= n; i += 1) {
+        values.push(data_model_1.default.namedNode(`urn:skl-dry-run:entity-${i}`));
+    }
+    return values;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.input) {
+        usageAndExit(2);
+    }
+    const input = readJsonFile(args.input);
+    const options = normalizeFindAllOptions(input);
+    const qb = new SparqlQueryBuilder_1.SparqlQueryBuilder();
+    const queryData = qb.buildEntitySelectPatternsFromOptions(SparqlUtil_1.entityVariable, options);
+    const selectQueryData = qb.buildEntitySelectPatternsFromOptions(SparqlUtil_1.entityVariable, {
+        ...options,
+        relations: undefined
+    });
+    // Mirrors SparqlQueryAdapter.buildFindAllQueryData() for the relations union tweak.
+    if ((queryData?.relationsQueryData?.unionPatterns ?? []).length > 0) {
+        queryData?.relationsQueryData?.unionPatterns.push((0, SparqlUtil_1.createSparqlGraphPattern)(SparqlUtil_1.entityVariable, [(0, SparqlUtil_1.createSparqlBasicGraphPattern)([SparqlUtil_1.entityGraphTriple])]));
+    }
+    const entitySelectQuery = buildEntitySelectQueryForFindAll(selectQueryData, options);
+    const wouldPreSelectForOrderingAndValues = queryData.orders.length > 0 && options?.limit !== 1 && !!entitySelectQuery;
+    const steps = [];
+    if (entitySelectQuery) {
+        const notes = [];
+        if (wouldPreSelectForOrderingAndValues) {
+            notes.push('In SparqlQueryAdapter.findAll(), this SELECT is executed first to compute entity ordering.', 'Its results are then used to inject a VALUES block over ?entity into the main CONSTRUCT query.');
+            if (options?.limit === undefined) {
+                notes.push('Warning: limit is undefined, so this pre-SELECT may return all matching entity IDs (potentially huge).');
+            }
+            else {
+                notes.push(`VALUES size is <= limit (${options.limit}).`);
+            }
+        }
+        else {
+            notes.push('In some cases (relations/type constraints), findAll executes this SELECT to support framing/type handling.');
+            notes.push('In that path, it also embeds this SELECT as a subquery inside the CONSTRUCT.');
+        }
+        steps.push({
+            kind: 'select',
+            name: 'Entity Pre-SELECT',
+            wouldExecute: wouldPreSelectForOrderingAndValues,
+            sparql: stringifyQuery(entitySelectQuery),
+            notes
+        });
+    }
+    let constructWhere = queryData.graphWhere;
+    let constructNotes = [];
+    if (wouldPreSelectForOrderingAndValues) {
+        if (args.simulateEntityValues > 0) {
+            const variableValueFilters = (0, SparqlUtil_1.createValuesPatternsForVariables)({
+                [SparqlUtil_1.entityVariable.value]: simulateEntityIdValues(args.simulateEntityValues)
+            });
+            constructWhere = [...variableValueFilters, ...constructWhere];
+            constructNotes = [
+                `This CONSTRUCT includes a simulated VALUES(?${SparqlUtil_1.entityVariable.value}) with ${args.simulateEntityValues} placeholder IRIs.`,
+                'In real execution, those VALUES come from the pre-SELECT results.'
+            ];
+        }
+        else {
+            constructNotes = [
+                'In real execution, this CONSTRUCT is preceded by the pre-SELECT and will have a VALUES(?entity) block injected.',
+                'Pass --simulate-entity-values N to show an example VALUES block.'
+            ];
+        }
+    }
+    else if (entitySelectQuery) {
+        // Mirrors the else-if path where the entity select is embedded into the CONSTRUCT.
+        const entitySelectGroupQuery = (0, SparqlUtil_1.createSparqlSelectGroup)([entitySelectQuery]);
+        constructWhere = [entitySelectGroupQuery, ...constructWhere];
+        constructNotes = ['This CONSTRUCT embeds the entity SELECT as a subquery (GROUP pattern) in its WHERE.'];
+    }
+    const constructQuery = qb.buildConstructFromEntitySelectQuery(constructWhere, queryData.graphSelectionTriples, options?.select, queryData.selectVariables);
+    steps.push({
+        kind: 'construct',
+        name: 'Main CONSTRUCT',
+        wouldExecute: true,
+        sparql: stringifyQuery(constructQuery),
+        ...(constructNotes.length > 0 ? { notes: constructNotes } : {})
+    });
+    if (wouldPreSelectForOrderingAndValues && options?.limit === undefined) {
+        steps.push({
+            kind: 'note',
+            name: 'Performance Hint',
+            wouldExecute: false,
+            notes: [
+                'findAll() with no limit triggers a pre-SELECT that can return a very large ID set, then injects it into VALUES(?entity).',
+                'This often causes slow queries due to large intermediate results and huge VALUES blocks.'
+            ]
+        });
+    }
+    const plan = {
+        input,
+        normalizedOptions: options,
+        steps,
+        meta: {
+            wouldPreSelectForOrderingAndValues,
+            hasRelations: (queryData?.relationsQueryData?.unionPatterns ?? []).length > 0,
+            hasTypeConstraint: options?.where?.type !== undefined,
+            limit: options?.limit,
+            offset: options?.offset
+        }
+    };
+    if (args.format === 'json') {
+        console.log(JSON.stringify(plan, null, 2));
+        return;
+    }
+    // Text
+    for (const step of plan.steps) {
+        if (step.kind === 'note') {
+            console.log(`\n# ${step.name}\n`);
+            for (const n of step.notes)
+                console.log(`- ${n}`);
+            continue;
+        }
+        console.log(`\n# ${step.name}\n`);
+        if ('notes' in step && step.notes?.length) {
+            for (const n of step.notes)
+                console.log(`- ${n}`);
+            console.log('');
+        }
+        console.log(step.sparql.trim());
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=explain-findall-sparql.js.map

package/dist/tools/explain-findall-sparql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-findall-sparql.js","sourceRoot":"","sources":["../../src/tools/explain-findall-sparql.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable */\n/* eslint-comments/no-unlimited-disable */\nimport fs from 'fs';\nimport path from 'path';\n\nimport DataFactory from '@rdfjs/data-model';\nimport type { NamedNode, Literal } from '@rdfjs/types';\nimport type { AggregateExpression, ConstructQuery, Pattern, SelectQuery, Variable } from 'sparqljs';\nimport { Generator } from 'sparqljs';\n\nimport type { FindAllOptions, FindOptionsWhere } from '../storage/FindOptionsTypes';\nimport { SparqlQueryBuilder } from '../storage/query-adapter/sparql/SparqlQueryBuilder';\nimport {\n  createSparqlBasicGraphPattern,\n  createSparqlGraphPattern,\n  createSparqlSelectQuery,\n  createValuesPatternsForVariables,\n  entityGraphTriple,\n  entityVariable,\n  rdfTypeNamedNode,\n  rdfTypesVariable,\n  rdfTypeVariable,\n  createSparqlSelectGroup\n} from '../util/SparqlUtil';\nimport { ensureArray } from '../util/Util';\n\ntype OutputFormat = 'text' | 'json';\n\ntype PlanStep =\n  | {\n      kind: 'select';\n      name: string;\n      wouldExecute: boolean;\n      sparql: string;\n      notes?: string[];\n    }\n  | {\n      kind: 'construct';\n      name: string;\n      wouldExecute: boolean;\n      sparql: string;\n      notes?: string[];\n    }\n  | {\n      kind: 'note';\n      name: string;\n      wouldExecute: boolean;\n      notes: string[];\n    };\n\ninterface ExplainPlan {\n  input: unknown;\n  normalizedOptions: FindAllOptions;\n  steps: PlanStep[];\n  meta: Record<string, any>;\n}\n\nfunction usageAndExit(exitCode: number): never {\n  const msg = [\n    'Usage:',\n    '  node dist/tools/explain-findall-sparql.js --input <file.json> [--format text|json] [--simulate-entity-values N]',\n    '',\n    'Input JSON can be either:',\n    '  1) a full FindAllOptions object: { \"where\": { ... }, \"relations\": { ... }, \"order\": { ... }, \"limit\": 10, ... }',\n    '  2) a FindOptionsWhere object (treated as { where: <object> })',\n    '',\n    'Notes:',\n    '  - This utility does not query a SPARQL endpoint. When findAll would inject VALUES(?entity) from a pre-SELECT,',\n    '    you can pass --simulate-entity-values N to show an example VALUES block with N placeholder IRIs.',\n    ''\n  ].join('\\n');\n\n  console.error(msg);\n\n  process.exit(exitCode);\n}\n\nfunction parseArgs(argv: string[]): { input?: string; format: OutputFormat; simulateEntityValues: number } {\n  const out: { input?: string; format: OutputFormat; simulateEntityValues: number } = {\n    format: 'text',\n    simulateEntityValues: 0\n  };\n\n  for (let i = 0; i < argv.length; i += 1) {\n    const arg = argv[i];\n    if (arg === '--help' || arg === '-h') {\n      usageAndExit(0);\n    }\n    if (arg === '--input' || arg === '-i') {\n      out.input = argv[i + 1];\n      i += 1;\n      continue;\n    }\n    if (arg === '--format' || arg === '-f') {\n      const v = argv[i + 1] as OutputFormat | undefined;\n      if (v !== 'text' && v !== 'json') {\n        console.error(`Invalid --format: ${String(v)}`);\n        usageAndExit(2);\n      }\n      out.format = v;\n      i += 1;\n      continue;\n    }\n    if (arg === '--simulate-entity-values') {\n      const v = Number.parseInt(argv[i + 1] ?? '', 10);\n      if (!Number.isFinite(v) || v < 0) {\n        console.error(`Invalid --simulate-entity-values: ${argv[i + 1]}`);\n        usageAndExit(2);\n      }\n      out.simulateEntityValues = v;\n      i += 1;\n      continue;\n    }\n    if (arg.startsWith('-')) {\n      console.error(`Unknown arg: ${arg}`);\n      usageAndExit(2);\n    }\n  }\n\n  return out;\n}\n\nfunction readJsonFile(p: string): any {\n  const abs = path.isAbsolute(p) ? p : path.join(process.cwd(), p);\n  const raw = fs.readFileSync(abs, 'utf8');\n  try {\n    return JSON.parse(raw);\n  } catch (e) {\n    throw new Error(`Failed to parse JSON from ${abs}: ${(e as Error).message}`);\n  }\n}\n\nfunction coerceSparqlVariable(v: any): Variable | undefined {\n  if (!v) return undefined;\n  if (typeof v === 'string') {\n    const name = v.startsWith('?') ? v.slice(1) : v;\n    return DataFactory.variable(name) as any;\n  }\n  if (typeof v === 'object' && v.termType === 'Variable' && typeof v.value === 'string') {\n    return v;\n  }\n  return undefined;\n}\n\nfunction normalizeFindAllOptions(input: any): FindAllOptions {\n  const asOptions =\n    typeof input === 'object' &&\n    input !== null &&\n    ('where' in input || 'select' in input || 'relations' in input || 'order' in input || 'limit' in input || 'offset' in input || 'subQueries' in input);\n\n  const options: FindAllOptions = asOptions ? input : { where: input as FindOptionsWhere };\n\n  // Allow simple JSON-friendly forms for variables.\n  const group = coerceSparqlVariable((options as any).group);\n  const entitySelectVariable = coerceSparqlVariable((options as any).entitySelectVariable);\n\n  const subQueries = Array.isArray((options as any).subQueries)\n    ? (options as any).subQueries.map((sq: any) => {\n        const select = Array.isArray(sq?.select) ? sq.select.map(coerceSparqlVariable).filter(Boolean) : sq?.select;\n        return { ...sq, ...(select ? { select } : {}) };\n      })\n    : (options as any).subQueries;\n\n  return {\n    ...options,\n    ...(group ? { group } : {}),\n    ...(entitySelectVariable ? { entitySelectVariable } : {}),\n    ...(subQueries ? { subQueries } : {})\n  };\n}\n\nfunction stringifyQuery(query: SelectQuery | ConstructQuery): string {\n  const gen = new Generator();\n  return gen.stringify(query);\n}\n\nfunction buildEntitySelectQueryForFindAll(\n  selectQueryData: ReturnType<SparqlQueryBuilder['buildEntitySelectPatternsFromOptions']>,\n  options?: FindAllOptions\n): SelectQuery | undefined {\n  // Mirrors SparqlQueryAdapter.buildFindAllQueryData() for the entitySelectQuery creation.\n  const wherePatterns: Pattern[] = [...selectQueryData.where, ...selectQueryData.graphWhere];\n  wherePatterns.push({\n    type: 'bgp',\n    triples: [\n      {\n        subject: entityVariable,\n        predicate: rdfTypeNamedNode,\n        object: rdfTypeVariable\n      }\n    ]\n  });\n\n  const entitySelectVariable = options?.entitySelectVariable ?? entityVariable;\n  const groupBy = ensureArray(selectQueryData?.group ?? options?.group ?? []);\n  groupBy.push(entitySelectVariable);\n\n  // All non-aggregated variables in SELECT must be in GROUP BY\n  for (const selectVariable of selectQueryData.selectVariables ?? []) {\n    const expr = selectVariable.expression as any;\n    if (!('aggregation' in (expr as AggregateExpression)) && expr?.constructor?.name === 'Variable') {\n      groupBy.push(expr as Variable);\n    }\n  }\n\n  if (selectQueryData.where.length === 0) {\n    return undefined;\n  }\n\n  return createSparqlSelectQuery(\n    [\n      entitySelectVariable,\n      // (GROUP_CONCAT(DISTINCT str(?rdfType); SEPARATOR = \" | \") AS ?rdfTypes)\n      {\n        expression: {\n          type: 'aggregate',\n          aggregation: 'group_concat',\n          separator: ' | ',\n          distinct: true,\n          expression: {\n            type: 'operation',\n            operator: 'STR',\n            args: [rdfTypeVariable]\n          }\n        },\n        variable: rdfTypesVariable\n      } as any,\n      ...(selectQueryData.selectVariables?.map(({ variable, expression }) => {\n        if (!expression) return variable as any;\n        return { variable, expression } as any;\n      }) ?? [])\n    ] as any,\n    wherePatterns,\n    selectQueryData.orders,\n    groupBy as any,\n    options?.limit,\n    options?.offset\n  );\n}\n\nfunction simulateEntityIdValues(n: number): (NamedNode | Literal)[] {\n  const values: NamedNode[] = [];\n  for (let i = 1; i <= n; i += 1) {\n    values.push(DataFactory.namedNode(`urn:skl-dry-run:entity-${i}`));\n  }\n  return values;\n}\n\nasync function main(): Promise<void> {\n  const args = parseArgs(process.argv.slice(2));\n  if (!args.input) {\n    usageAndExit(2);\n  }\n\n  const input = readJsonFile(args.input);\n  const options = normalizeFindAllOptions(input);\n\n  const qb = new SparqlQueryBuilder();\n  const queryData = qb.buildEntitySelectPatternsFromOptions(entityVariable, options);\n  const selectQueryData = qb.buildEntitySelectPatternsFromOptions(entityVariable, {\n    ...options,\n    relations: undefined\n  });\n\n  // Mirrors SparqlQueryAdapter.buildFindAllQueryData() for the relations union tweak.\n  if ((queryData?.relationsQueryData?.unionPatterns ?? []).length > 0) {\n    queryData?.relationsQueryData?.unionPatterns.push(createSparqlGraphPattern(entityVariable, [createSparqlBasicGraphPattern([entityGraphTriple])]));\n  }\n\n  const entitySelectQuery = buildEntitySelectQueryForFindAll(selectQueryData, options);\n  const wouldPreSelectForOrderingAndValues = queryData.orders.length > 0 && options?.limit !== 1 && !!entitySelectQuery;\n\n  const steps: PlanStep[] = [];\n\n  if (entitySelectQuery) {\n    const notes: string[] = [];\n    if (wouldPreSelectForOrderingAndValues) {\n      notes.push(\n        'In SparqlQueryAdapter.findAll(), this SELECT is executed first to compute entity ordering.',\n        'Its results are then used to inject a VALUES block over ?entity into the main CONSTRUCT query.'\n      );\n      if (options?.limit === undefined) {\n        notes.push('Warning: limit is undefined, so this pre-SELECT may return all matching entity IDs (potentially huge).');\n      } else {\n        notes.push(`VALUES size is <= limit (${options.limit}).`);\n      }\n    } else {\n      notes.push('In some cases (relations/type constraints), findAll executes this SELECT to support framing/type handling.');\n      notes.push('In that path, it also embeds this SELECT as a subquery inside the CONSTRUCT.');\n    }\n\n    steps.push({\n      kind: 'select',\n      name: 'Entity Pre-SELECT',\n      wouldExecute: wouldPreSelectForOrderingAndValues,\n      sparql: stringifyQuery(entitySelectQuery),\n      notes\n    });\n  }\n\n  let constructWhere = queryData.graphWhere;\n  let constructNotes: string[] = [];\n\n  if (wouldPreSelectForOrderingAndValues) {\n    if (args.simulateEntityValues > 0) {\n      const variableValueFilters = createValuesPatternsForVariables({\n        [entityVariable.value]: simulateEntityIdValues(args.simulateEntityValues) as any\n      });\n      constructWhere = [...variableValueFilters, ...constructWhere];\n      constructNotes = [\n        `This CONSTRUCT includes a simulated VALUES(?${entityVariable.value}) with ${args.simulateEntityValues} placeholder IRIs.`,\n        'In real execution, those VALUES come from the pre-SELECT results.'\n      ];\n    } else {\n      constructNotes = [\n        'In real execution, this CONSTRUCT is preceded by the pre-SELECT and will have a VALUES(?entity) block injected.',\n        'Pass --simulate-entity-values N to show an example VALUES block.'\n      ];\n    }\n  } else if (entitySelectQuery) {\n    // Mirrors the else-if path where the entity select is embedded into the CONSTRUCT.\n    const entitySelectGroupQuery = createSparqlSelectGroup([entitySelectQuery]);\n    constructWhere = [entitySelectGroupQuery, ...constructWhere];\n    constructNotes = ['This CONSTRUCT embeds the entity SELECT as a subquery (GROUP pattern) in its WHERE.'];\n  }\n\n  const constructQuery = qb.buildConstructFromEntitySelectQuery(constructWhere, queryData.graphSelectionTriples, options?.select, queryData.selectVariables);\n\n  steps.push({\n    kind: 'construct',\n    name: 'Main CONSTRUCT',\n    wouldExecute: true,\n    sparql: stringifyQuery(constructQuery),\n    ...(constructNotes.length > 0 ? { notes: constructNotes } : {})\n  });\n\n  if (wouldPreSelectForOrderingAndValues && options?.limit === undefined) {\n    steps.push({\n      kind: 'note',\n      name: 'Performance Hint',\n      wouldExecute: false,\n      notes: [\n        'findAll() with no limit triggers a pre-SELECT that can return a very large ID set, then injects it into VALUES(?entity).',\n        'This often causes slow queries due to large intermediate results and huge VALUES blocks.'\n      ]\n    });\n  }\n\n  const plan: ExplainPlan = {\n    input,\n    normalizedOptions: options,\n    steps,\n    meta: {\n      wouldPreSelectForOrderingAndValues,\n      hasRelations: (queryData?.relationsQueryData?.unionPatterns ?? []).length > 0,\n      hasTypeConstraint: options?.where?.type !== undefined,\n      limit: options?.limit,\n      offset: options?.offset\n    }\n  };\n\n  if (args.format === 'json') {\n    console.log(JSON.stringify(plan, null, 2));\n    return;\n  }\n\n  // Text\n  for (const step of plan.steps) {\n    if (step.kind === 'note') {\n      console.log(`\\n# ${step.name}\\n`);\n      for (const n of step.notes) console.log(`- ${n}`);\n      continue;\n    }\n    console.log(`\\n# ${step.name}\\n`);\n    if ('notes' in step && step.notes?.length) {\n      for (const n of step.notes) console.log(`- ${n}`);\n      console.log('');\n    }\n    console.log(step.sparql.trim());\n  }\n}\n\nmain().catch((err: unknown) => {\n  console.error(err);\n\n  process.exit(1);\n});\n"]}

package/dist/util/PerformanceLogger.d.ts

@@ -0,0 +1,28 @@
+export interface Span {
+    id: string;
+    parentId?: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    attributes: Record<string, any>;
+    children: Span[];
+}
+export declare class PerformanceLogger {
+    private static asyncLocalStorage?;
+    private static enabled;
+    private static initialized;
+    private static spanCounter;
+    private static initialize;
+    private static generateSpanId;
+    static startSpan(name: string, attributes?: Record<string, any>): Span;
+    static endSpan(span: Span, additionalAttributes?: Record<string, any>): void;
+    static withSpan<T>(name: string, fn: () => Promise<T> | T, attributes?: Record<string, any>): Promise<T>;
+    static withSpanRoot<T>(name: string, fn: () => Promise<T> | T, attributes?: Record<string, any>): Promise<T>;
+    static getCurrentSpan(): Span | undefined;
+    static logSpanTree(rootSpan: Span): void;
+    private static buildSpanTreeLines;
+    private static addAttributeLines;
+    private static formatQuery;
+}
+//# sourceMappingURL=PerformanceLogger.d.ts.map

package/dist/util/PerformanceLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerformanceLogger.d.ts","sourceRoot":"","sources":["../../src/util/PerformanceLogger.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,QAAQ,EAAE,IAAI,EAAE,CAAC;CAClB;AAWD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAM;IACvC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAU;IAChC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAS;IACnC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAK;IAE/B,OAAO,CAAC,MAAM,CAAC,UAAU;IAezB,OAAO,CAAC,MAAM,CAAC,cAAc;WAKf,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;WAyB/D,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;WAa/D,QAAQ,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;WAiCO,YAAY,CAAC,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;WAqCC,cAAc,IAAI,IAAI,GAAG,SAAS;WAUlC,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI;IAyB/C,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA0BjC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAoChC,OAAO,CAAC,MAAM,CAAC,WAAW;CAqB3B"}