@eagleoutice/flowr 2.1.11 → 2.2.0

package/r-bridge/shell-executor.d.ts

@@ -1,10 +1,46 @@
 import type { RShellExecutionOptions } from './shell';
 import type { SemVer } from 'semver';
-export declare class RShellExecutor {
+import type { SyncParser } from './parser';
+import { type RParseRequest } from './retriever';
+/**
+ * This is a synchronous alternative to the {@link RShell}.
+ * Please be aware that using this is expensive.
+ * Every request effectively causes a new initialization of the R interpreter.
+ *
+ * With this class you can {@link RShellExecutor#run|run(command)} commands,
+ * that are potentially decorated with {@link RShellExecutor#addPrerequisites|prerequisites}.
+ * For compatibility,
+ * we provide {@link RShellExecutor#parse|parse(request)} and {@link RShellExecutor#rVersion|rVersion()}.
+ */
+export declare class RShellExecutor implements SyncParser<string> {
+    readonly name = "r-shell";
     readonly options: Readonly<RShellExecutionOptions>;
     private readonly prerequisites;
     constructor(options?: Partial<RShellExecutionOptions>);
+    /**
+     * Adds commands that should be executed for every {@link RShellExecutor#run|run}.
+     */
     addPrerequisites(commands: string | string[]): this;
+    /**
+     * @returns the version of the R interpreter available to this executor.
+     *
+     * @see {@link RShellExecutor#usedRVersion}
+     * @see {@link RShell#rVersion}
+     * @see {@link RShell#usedRVersion}
+     */
+    rVersion(): Promise<string | 'unknown' | 'none'>;
+    /**
+     * Instead of returning a promise, this method returns the version of the R interpreter available to this executor,
+     * in the SemVer format.
+     */
     usedRVersion(): SemVer | null;
+    /**
+     * Runs the given command in the R interpreter.
+     */
     run(command: string, returnErr?: boolean): string;
+    /**
+     * Parses the given request and returns the result.
+     */
+    parse(request: RParseRequest): string;
+    close(): void;
 }

package/r-bridge/shell-executor.js

@@ -11,23 +11,55 @@ const preload_1 = __importDefault(require("semver/preload"));
 const log_1 = require("../util/log");
 const init_1 = require("./init");
 const convert_values_1 = require("./lang-4.x/convert-values");
+const retriever_1 = require("./retriever");
 const executorLog = log_1.log.getSubLogger({ name: 'RShellExecutor' });
+/**
+ * This is a synchronous alternative to the {@link RShell}.
+ * Please be aware that using this is expensive.
+ * Every request effectively causes a new initialization of the R interpreter.
+ *
+ * With this class you can {@link RShellExecutor#run|run(command)} commands,
+ * that are potentially decorated with {@link RShellExecutor#addPrerequisites|prerequisites}.
+ * For compatibility,
+ * we provide {@link RShellExecutor#parse|parse(request)} and {@link RShellExecutor#rVersion|rVersion()}.
+ */
 class RShellExecutor {
+    name = 'r-shell';
     options;
     prerequisites;
     constructor(options) {
         this.options = (0, objects_1.deepMergeObject)((0, shell_1.getDefaultRShellOptions)(), options);
         this.prerequisites = [(0, init_1.initCommand)(this.options.eol)];
     }
+    /**
+     * Adds commands that should be executed for every {@link RShellExecutor#run|run}.
+     */
     addPrerequisites(commands) {
         this.prerequisites.push(...(typeof commands == 'string' ? [commands] : commands));
         return this;
     }
+    /**
+     * @returns the version of the R interpreter available to this executor.
+     *
+     * @see {@link RShellExecutor#usedRVersion}
+     * @see {@link RShell#rVersion}
+     * @see {@link RShell#usedRVersion}
+     */
+    rVersion() {
+        return Promise.resolve(this.usedRVersion()?.format() ?? 'unknown');
+    }
+    /**
+     * Instead of returning a promise, this method returns the version of the R interpreter available to this executor,
+     * in the SemVer format.
+     */
     usedRVersion() {
         const version = this.run(`cat(paste0(R.version$major,".",R.version$minor), ${(0, convert_values_1.ts2r)(this.options.eol)})`);
         (0, log_1.expensiveTrace)(executorLog, () => `raw version: ${JSON.stringify(version)}`);
         return preload_1.default.coerce(version);
     }
+    /**
+     * Runs the given command in the R interpreter.
+     */
     run(command, returnErr = false) {
         command += ';base::quit()';
         (0, log_1.expensiveTrace)(executorLog, () => `> ${JSON.stringify(command)}`);
@@ -40,6 +72,13 @@ class RShellExecutor {
         });
         return (returnErr ? returns.stderr : returns.stdout).trim();
     }
+    /**
+     * Parses the given request and returns the result.
+     */
+    parse(request) {
+        return (0, retriever_1.retrieveParseDataFromRCode)(request, this);
+    }
+    close() { }
 }
 exports.RShellExecutor = RShellExecutor;
 //# sourceMappingURL=shell-executor.js.map

package/r-bridge/shell.d.ts

@@ -1,6 +1,8 @@
 import { type MergeableRecord } from '../util/objects';
 import type { SemVer } from 'semver';
 import type { AsyncOrSync } from 'ts-essentials';
+import type { AsyncParser } from './parser';
+import type { RParseRequest } from './retriever';
 export type OutputStreamSelector = 'stdout' | 'stderr' | 'both';
 export interface CollectorTimeout extends MergeableRecord {
     /**
@@ -72,22 +74,26 @@ export declare function getDefaultRShellOptions(): RShellOptions;
  * You can configure it by {@link RShellOptions}.
  *
  * At the moment we are using a live R session (and not networking etc.) to communicate with R easily,
- * which allows us to install packages etc. However, this might and probably will change in the future (leaving this
- * as a legacy mode :D)
+ * which allows us to install packages etc. However, this might and probably will change in the future
+ * (leaving this as a legacy mode :D)
  */
-export declare class RShell {
+export declare class RShell implements AsyncParser<string> {
+    readonly name = "r-shell";
+    readonly async = true;
     readonly options: Readonly<RShellOptions>;
     private session;
     private readonly log;
     private versionCache;
     private tempDirs;
     constructor(options?: Partial<RShellOptions>);
+    parse(request: RParseRequest): Promise<string>;
     private revive;
     /**
-   * sends the given command directly to the current R session
-   * will not do anything to alter input markers!
-   */
+     * sends the given command directly to the current R session
+     * will not do anything to alter input markers!
+     */
     sendCommand(command: string): void;
+    rVersion(): Promise<string | 'unknown' | 'none'>;
     usedRVersion(): Promise<SemVer | null>;
     injectLibPaths(...paths: readonly string[]): void;
     tryToInjectHomeLibPath(): void;

package/r-bridge/shell.js

@@ -38,6 +38,7 @@ const fs_1 = __importDefault(require("fs"));
 const init_1 = require("./init");
 const config_1 = require("../config");
 const convert_values_1 = require("./lang-4.x/convert-values");
+const retriever_1 = require("./retriever");
 exports.DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION = {
     from: 'stdout',
     postamble: `🐧${'-'.repeat(5)}🐧`,
@@ -54,7 +55,7 @@ let DEFAULT_R_SHELL_OPTIONS = undefined;
 function getDefaultRShellOptions() {
     if (!DEFAULT_R_SHELL_OPTIONS) {
         DEFAULT_R_SHELL_OPTIONS = {
-            pathToRExecutable: (0, config_1.getConfig)().rPath ?? exports.DEFAULT_R_PATH,
+            pathToRExecutable: (0, config_1.getEngineConfig)('r-shell')?.rPath ?? exports.DEFAULT_R_PATH,
             // -s is a short form of --no-echo (and the old version --slave), but this one works in R 3 and 4
             // (see https://github.com/wch/r-source/commit/f1ff49e74593341c74c20de9517f31a22c8bcb04)
             commandLineOptions: ['--vanilla', '--quiet', '--no-save', '-s'],
@@ -74,10 +75,12 @@ function getDefaultRShellOptions() {
  * You can configure it by {@link RShellOptions}.
  *
  * At the moment we are using a live R session (and not networking etc.) to communicate with R easily,
- * which allows us to install packages etc. However, this might and probably will change in the future (leaving this
- * as a legacy mode :D)
+ * which allows us to install packages etc. However, this might and probably will change in the future
+ * (leaving this as a legacy mode :D)
  */
 class RShell {
+    name = 'r-shell';
+    async = true;
     options;
     session;
     log;
@@ -90,6 +93,9 @@ class RShell {
         this.session = new RShellSession(this.options, this.log);
         this.revive();
     }
+    parse(request) {
+        return (0, retriever_1.retrieveParseDataFromRCode)(request, this);
+    }
     revive() {
         if (this.options.revive === 0 /* RShellReviveOptions.Never */) {
             return;
@@ -104,15 +110,18 @@ class RShell {
         });
     }
     /**
-   * sends the given command directly to the current R session
-   * will not do anything to alter input markers!
-   */
+     * sends the given command directly to the current R session
+     * will not do anything to alter input markers!
+     */
     sendCommand(command) {
         if (this.log.settings.minLevel <= 1 /* LogLevel.Trace */) {
             this.log.trace(`> ${JSON.stringify(command)}`);
         }
         this._sendCommand(command);
     }
+    async rVersion() {
+        return (await this.usedRVersion())?.format() ?? 'unknown';
+    }
     async usedRVersion() {
         if (this.versionCache !== null) {
             return this.versionCache;

package/search/flowr-search-builder.d.ts

@@ -0,0 +1,193 @@
+import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
+import type { FlowrFilterExpression } from './flowr-search-filters';
+import type { FlowrSearchGeneratorNode, GeneratorNames } from './search-executor/search-generators';
+import type { FlowrSearchTransformerNode, GetOutputOfTransformer, TransformerNames } from './search-executor/search-transformer';
+import type { SlicingCriteria } from '../slicing/criterion/parse';
+import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+type FlowrCriteriaReturn<C extends SlicingCriteria> = FlowrSearchElements<ParentInformation, C extends [] ? never : C extends [infer _] ? [
+    FlowrSearchElement<ParentInformation>
+] : FlowrSearchElement<ParentInformation>[]>;
+/**
+ * This object holds all the methods to generate search queries.
+ * For compatibility, please use the {@link Q} identifier object to access these methods.
+ */
+export declare const FlowrSearchGenerator: {
+    /**
+     * Initialize a search query with the given elements.
+     * <b>This is not intended to serialize well</b> wrt. the nodes,
+     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
+     */
+    readonly from: (from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[]) => FlowrSearchBuilder<"from">;
+    /**
+     * Returns all elements (nodes/dataflow vertices) from the given data.
+     */
+    readonly all: () => FlowrSearchBuilder<"all">;
+    /**
+     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
+     * You may pass a negative line number to count from the back.
+     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
+     */
+    readonly get: (filter: FlowrSearchGetFilter) => FlowrSearchBuilder<"get">;
+    /**
+     * Returns all elements that match the given {@link SlicingCriteria|criteria}
+     * (e.g., `criterion('2@x', '3@<-')`,
+     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
+     * This will throw an error, if any criteria cannot be resolved to an id.
+     */
+    readonly criterion: <Criteria extends SlicingCriteria>(...criterion: Criteria) => FlowrSearchBuilder<"criterion", [], ParentInformation, FlowrCriteriaReturn<Criteria>>;
+    /**
+     * Short form of {@link get} with only the
+     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
+     * `get({line, column})`.
+     */
+    readonly loc: (line?: number, column?: number) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
+     * `get({name, line})`.
+     */
+    readonly varInLine: (name: string, line: number) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
+     * `get({name})`.
+     */
+    readonly var: (name: string) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
+     * `get({id})`.
+     */
+    readonly id: (id: NodeId) => FlowrSearchBuilder<"get">;
+};
+/**
+ * This is the root object to use for creating searches.
+ * See the {@link FlowrSearchGenerator} for the available methods.
+ * After the query is generated,
+ * you can use what is provided by the {@link FlowrSearchBuilder} to further refine the search.
+ */
+export declare const Q: {
+    /**
+     * Initialize a search query with the given elements.
+     * <b>This is not intended to serialize well</b> wrt. the nodes,
+     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
+     */
+    readonly from: (from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[]) => FlowrSearchBuilder<"from">;
+    /**
+     * Returns all elements (nodes/dataflow vertices) from the given data.
+     */
+    readonly all: () => FlowrSearchBuilder<"all">;
+    /**
+     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
+     * You may pass a negative line number to count from the back.
+     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
+     */
+    readonly get: (filter: FlowrSearchGetFilter) => FlowrSearchBuilder<"get">;
+    /**
+     * Returns all elements that match the given {@link SlicingCriteria|criteria}
+     * (e.g., `criterion('2@x', '3@<-')`,
+     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
+     * This will throw an error, if any criteria cannot be resolved to an id.
+     */
+    readonly criterion: <Criteria extends SlicingCriteria>(...criterion: Criteria) => FlowrSearchBuilder<"criterion", [], ParentInformation, FlowrCriteriaReturn<Criteria>>;
+    /**
+     * Short form of {@link get} with only the
+     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
+     * `get({line, column})`.
+     */
+    readonly loc: (line?: number, column?: number) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
+     * `get({name, line})`.
+     */
+    readonly varInLine: (name: string, line: number) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
+     * `get({name})`.
+     */
+    readonly var: (name: string) => FlowrSearchBuilder<"get">;
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
+     * `get({id})`.
+     */
+    readonly id: (id: NodeId) => FlowrSearchBuilder<"get">;
+};
+export type FlowrSearchBuilderType<Generator extends GeneratorNames = GeneratorNames, Transformers extends TransformerNames[] = TransformerNames[], Info = ParentInformation, ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> = FlowrSearchBuilder<Generator, Transformers, Info, ElementType>;
+type GetElements<F> = F extends FlowrSearchElements<infer Info, infer Elements> ? Elements extends FlowrSearchElement<Info>[] ? Elements : never : never;
+/**
+ * The search query is a combination of a generator and a list of transformers
+ * and allows this view to pass such queries in a serialized form.
+ *
+ * @typeParam Transformers - The list of transformers that are applied to the generator's output.
+ */
+export interface FlowrSearch<Info = ParentInformation, _Generator extends GeneratorNames = GeneratorNames, _Transformers extends readonly TransformerNames[] = readonly TransformerNames[], _ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> {
+    readonly generator: FlowrSearchGeneratorNode;
+    readonly search: readonly FlowrSearchTransformerNode[];
+}
+type FlowrSearchBuilderOut<Generator extends GeneratorNames, Transformers extends TransformerNames[], Info, Transformer extends TransformerNames> = FlowrSearchBuilder<Generator, [...Transformers, Transformer], Info, GetOutputOfTransformer<Transformer>>;
+/**
+ * Allows you to construct a search query from a {@link FlowrSearchGeneratorNode}.
+ * Please use the {@link Q} object to create an object of this class!
+ * In the end, you _can_ freeze the search by calling {@link FlowrSearchBuilder#build},
+ * however, the search executors may do that for you.
+ *
+ * @see {@link FlowrSearchGenerator}
+ * @see {@link FlowrSearch}
+ * @see {@link FlowrSearchLike}
+ */
+export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transformers extends TransformerNames[] = [], Info = ParentInformation, ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> {
+    private readonly generator;
+    private readonly search;
+    constructor(generator: FlowrSearchGeneratorNode);
+    /**
+     * only returns the elements that match the given filter.
+     */
+    filter(filter: FlowrFilterExpression): FlowrSearchBuilderOut<Generator, Transformers, Info, 'filter'>;
+    /**
+     * first either returns the first element of the search or nothing, if no elements are present.
+     */
+    first(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'first'>;
+    /**
+     * last either returns the last element of the search or nothing, if no elements are present.
+     */
+    last(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'last'>;
+    /**
+     * index returns the element at the given index if it exists
+     */
+    index<Idx extends number>(index: Idx): FlowrSearchBuilderOut<Generator, Transformers, Info, 'index'>;
+    /**
+     * tail returns all elements of the search except the first one.
+     */
+    tail(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'tail'>;
+    /**
+     * take returns the first `count` elements of the search.
+     */
+    take<Count extends number>(count: Count): FlowrSearchBuilderOut<Generator, Transformers, Info, 'take'>;
+    /**
+     * skip returns all elements of the search except the first `count` ones.
+     */
+    skip<Count extends number>(count: Count): FlowrSearchBuilderOut<Generator, Transformers, Info, 'skip'>;
+    /**
+     * select returns only the elements at the given indices.
+     */
+    select<Select extends number[]>(...select: Select): FlowrSearchBuilderOut<Generator, Transformers, Info, 'select'>;
+    /**
+     * merge combines the search results with those of another search.
+     */
+    merge<Generator2 extends GeneratorNames, Transformers2 extends TransformerNames[], OtherElementType extends FlowrSearchElements<Info, FlowrSearchElement<Info>[]>>(other: FlowrSearchBuilder<Generator2, Transformers2, Info, OtherElementType>): FlowrSearchBuilder<Generator, Transformers, Info, FlowrSearchElements<Info, [...GetElements<ElementType>, ...GetElements<OtherElementType>]>>;
+    /**
+     * Construct the final search (this may happen automatically with most search handlers).
+     *
+     * @param shouldOptimize - This may optimize the search.
+     */
+    build(shouldOptimize?: boolean): FlowrSearch<Info, Generator, Transformers, ElementType>;
+}
+/**
+ * This type summarizes all types that can be used in places in which the API expects you to provide a search query.
+ * @see {@link FlowrSearch}
+ */
+export type FlowrSearchLike = FlowrSearch | FlowrSearchBuilderType;
+export type SearchOutput<Search> = Search extends FlowrSearch ? Search : Search extends FlowrSearchBuilderType<infer Generator, infer Transformers, infer Info, infer Elements> ? FlowrSearch<Info, Generator, Transformers, Elements> : never;
+/**
+ * Freezes any accepted {@link FlowrSearchLike} into a {@link FlowrSearch}.
+ */
+export declare function getFlowrSearch<Search extends FlowrSearchLike>(search: Search, optimizeIfBuild?: boolean): SearchOutput<Search>;
+export {};

package/search/flowr-search-builder.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrSearchBuilder = exports.Q = exports.FlowrSearchGenerator = void 0;
+exports.getFlowrSearch = getFlowrSearch;
+const search_optimizer_1 = require("./search-optimizer/search-optimizer");
+const assert_1 = require("../util/assert");
+/**
+ * This object holds all the methods to generate search queries.
+ * For compatibility, please use the {@link Q} identifier object to access these methods.
+ */
+exports.FlowrSearchGenerator = {
+    /**
+     * Initialize a search query with the given elements.
+     * <b>This is not intended to serialize well</b> wrt. the nodes,
+     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
+     */
+    from(from) {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'from', args: { from } });
+    },
+    /**
+     * Returns all elements (nodes/dataflow vertices) from the given data.
+     */
+    all() {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'all', args: undefined });
+    },
+    /**
+     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
+     * You may pass a negative line number to count from the back.
+     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
+     */
+    get(filter) {
+        (0, assert_1.guard)(!filter.nameIsRegex || filter.name, 'If nameIsRegex is set, a name should be provided');
+        (0, assert_1.guard)(!filter.line || filter.line != 0, 'If line is set, it must be different from 0 as there is no 0 line');
+        (0, assert_1.guard)(!filter.column || filter.column > 0, 'If column is set, it must be greater than 0, but was ' + filter.column);
+        return new FlowrSearchBuilder({ type: 'generator', name: 'get', args: { filter } });
+    },
+    /**
+     * Returns all elements that match the given {@link SlicingCriteria|criteria}
+     * (e.g., `criterion('2@x', '3@<-')`,
+     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
+     * This will throw an error, if any criteria cannot be resolved to an id.
+     */
+    criterion(...criterion) {
+        (0, assert_1.guard)(criterion.length > 0, 'At least one criterion must be provided');
+        return new FlowrSearchBuilder({ type: 'generator', name: 'criterion', args: { criterion } });
+    },
+    /**
+     * Short form of {@link get} with only the
+     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
+     * `get({line, column})`.
+     */
+    loc(line, column) {
+        return exports.FlowrSearchGenerator.get({ line, column });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
+     * `get({name, line})`.
+     */
+    varInLine(name, line) {
+        return exports.FlowrSearchGenerator.get({ name, line });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
+     * `get({name})`.
+     */
+    var(name) {
+        return exports.FlowrSearchGenerator.get({ name });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
+     * `get({id})`.
+     */
+    id(id) {
+        return exports.FlowrSearchGenerator.get({ id });
+    }
+};
+/**
+ * This is the root object to use for creating searches.
+ * See the {@link FlowrSearchGenerator} for the available methods.
+ * After the query is generated,
+ * you can use what is provided by the {@link FlowrSearchBuilder} to further refine the search.
+ */
+exports.Q = exports.FlowrSearchGenerator;
+/**
+ * Allows you to construct a search query from a {@link FlowrSearchGeneratorNode}.
+ * Please use the {@link Q} object to create an object of this class!
+ * In the end, you _can_ freeze the search by calling {@link FlowrSearchBuilder#build},
+ * however, the search executors may do that for you.
+ *
+ * @see {@link FlowrSearchGenerator}
+ * @see {@link FlowrSearch}
+ * @see {@link FlowrSearchLike}
+ */
+class FlowrSearchBuilder {
+    generator;
+    search = [];
+    constructor(generator) {
+        this.generator = generator;
+    }
+    /**
+     * only returns the elements that match the given filter.
+     */
+    filter(filter) {
+        this.search.push({ type: 'transformer', name: 'filter', args: { filter: filter } });
+        return this;
+    }
+    /**
+     * first either returns the first element of the search or nothing, if no elements are present.
+     */
+    first() {
+        this.search.push({ type: 'transformer', name: 'first', args: undefined });
+        return this;
+    }
+    /**
+     * last either returns the last element of the search or nothing, if no elements are present.
+     */
+    last() {
+        this.search.push({ type: 'transformer', name: 'last', args: undefined });
+        return this;
+    }
+    /**
+     * index returns the element at the given index if it exists
+     */
+    index(index) {
+        (0, assert_1.guard)(index >= 0, 'Index must be greater or equal to 0, but was ' + index);
+        this.search.push({ type: 'transformer', name: 'index', args: { index } });
+        return this;
+    }
+    /**
+     * tail returns all elements of the search except the first one.
+     */
+    tail() {
+        this.search.push({ type: 'transformer', name: 'tail', args: undefined });
+        return this;
+    }
+    /**
+     * take returns the first `count` elements of the search.
+     */
+    take(count) {
+        (0, assert_1.guard)(count >= 0, 'Count must be greater or equal to 0, but was ' + count);
+        this.search.push({ type: 'transformer', name: 'take', args: { count } });
+        return this;
+    }
+    /**
+     * skip returns all elements of the search except the first `count` ones.
+     */
+    skip(count) {
+        (0, assert_1.guard)(count >= 0, 'Count must be greater or equal to 0, but was ' + count);
+        this.search.push({ type: 'transformer', name: 'skip', args: { count } });
+        return this;
+    }
+    /**
+     * select returns only the elements at the given indices.
+     */
+    select(...select) {
+        (0, assert_1.guard)(select.length > 0, 'At least one index must be provided');
+        (0, assert_1.guard)(select.every(i => i >= 0), () => 'All indices must be greater or equal to 0, but were ' + JSON.stringify(select));
+        this.search.push({ type: 'transformer', name: 'select', args: { select } });
+        return this;
+    }
+    /**
+     * merge combines the search results with those of another search.
+     */
+    merge(other /* | FlowrSearch<Info, Generator2, Transformers2, OtherElementType> */
+    // @ts-expect-error -- this works when merging, there is no info disparity
+    ) {
+        this.search.push({ type: 'transformer', name: 'merge', args: { generator: other.generator, search: other.search } });
+        return this;
+    }
+    /**
+     * Construct the final search (this may happen automatically with most search handlers).
+     *
+     * @param shouldOptimize - This may optimize the search.
+     */
+    build(shouldOptimize = true) {
+        return shouldOptimize ? (0, search_optimizer_1.optimize)(this.generator, this.search) : {
+            generator: this.generator,
+            search: this.search
+        };
+    }
+}
+exports.FlowrSearchBuilder = FlowrSearchBuilder;
+/**
+ * Freezes any accepted {@link FlowrSearchLike} into a {@link FlowrSearch}.
+ */
+function getFlowrSearch(search, optimizeIfBuild = true) {
+    if (search instanceof FlowrSearchBuilder) {
+        return search.build(optimizeIfBuild);
+    }
+    return search;
+}
+//# sourceMappingURL=flowr-search-builder.js.map

package/search/flowr-search-executor.d.ts

@@ -0,0 +1,9 @@
+import type { FlowrSearch, FlowrSearchLike, SearchOutput } from './flowr-search-builder';
+import type { FlowrSearchElements, FlowrSearchInput } from './flowr-search';
+import type { Pipeline } from '../core/steps/pipeline/pipeline';
+type GetSearchElements<S> = S extends FlowrSearch<infer _, infer _, infer _, infer Elements> ? Elements extends FlowrSearchElements<infer _, infer E> ? E : never : never;
+/**
+ * Run a search with the given search query and data.
+ */
+export declare function runSearch<S extends FlowrSearchLike, P extends Pipeline>(search: S, data: FlowrSearchInput<P>): GetSearchElements<SearchOutput<S>>;
+export {};

package/search/flowr-search-executor.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSearch = runSearch;
+const flowr_search_builder_1 = require("./flowr-search-builder");
+const search_generators_1 = require("./search-executor/search-generators");
+const search_transformer_1 = require("./search-executor/search-transformer");
+/**
+ * Run a search with the given search query and data.
+ */
+function runSearch(search, data) {
+    const s = (0, flowr_search_builder_1.getFlowrSearch)(search);
+    return s.search.reduce((acc, transformer) => (0, search_transformer_1.getTransformer)(transformer.name)(data, acc, transformer.args), 
+    /* support multiple arguments may be abstracted away in search frontend */
+    (0, search_generators_1.getGenerator)(s.generator.name)(data, s.generator.args)).getElements();
+}
+//# sourceMappingURL=flowr-search-executor.js.map