@eagleoutice/flowr 2.2.15 → 2.3.0

package/search/flowr-search-filters.js

@@ -1,22 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowrFilterCombinator = exports.FlowrFilters = exports.ValidFlowrFiltersReverse = exports.ValidFlowrFilters = exports.FlowrFilter = void 0;
+exports.testFunctionsIgnoringPackage = testFunctionsIgnoringPackage;
 exports.binaryTreeToString = binaryTreeToString;
 exports.isBinaryTree = isBinaryTree;
 exports.evalFilter = evalFilter;
 const type_1 = require("../r-bridge/lang-4.x/ast/model/type");
 const vertex_1 = require("../dataflow/graph/vertex");
+const search_enrichers_1 = require("./search-executor/search-enrichers");
 var FlowrFilter;
 (function (FlowrFilter) {
+    /**
+     * Drops search elements that represent empty arguments. Specifically, all nodes that are arguments and have an undefined name are skipped.
+     * This filter does not accept any arguments.
+     */
     FlowrFilter["DropEmptyArguments"] = "drop-empty-arguments";
+    /**
+     * Only returns search elements whose enrichments' JSON representations match a given test regular expression.
+     * This filter accepts {@link MatchesEnrichmentArgs}, which includes the enrichment to match for, as well as the regular expression to test the enrichment's (non-pretty-printed) JSON representation for.
+     * To test for included function names in an enrichment like {@link Enrichment.CallTargets}, the helper function {@link testFunctionsIgnoringPackage} can be used.
+     */
+    FlowrFilter["MatchesEnrichment"] = "matches-enrichment";
 })(FlowrFilter || (exports.FlowrFilter = FlowrFilter = {}));
 exports.ValidFlowrFilters = new Set(Object.values(FlowrFilter));
 exports.ValidFlowrFiltersReverse = Object.fromEntries(Object.entries(FlowrFilter).map(([k, v]) => [v, k]));
 exports.FlowrFilters = {
-    [FlowrFilter.DropEmptyArguments]: (n) => {
-        return n.type !== type_1.RType.Argument || n.name !== undefined;
-    }
+    [FlowrFilter.DropEmptyArguments]: ((e, _args) => {
+        return e.node.type !== type_1.RType.Argument || e.node.name !== undefined;
+    }),
+    [FlowrFilter.MatchesEnrichment]: ((e, args) => {
+        const content = JSON.stringify((0, search_enrichers_1.enrichmentContent)(e, args.enrichment));
+        return content !== undefined && args.test.test(content);
+    })
 };
+function testFunctionsIgnoringPackage(functions) {
+    return new RegExp(`"(.+:::?)?(${functions.join('|')})"`);
+}
 /**
  * @see {@link FlowrFilterCombinator.is}
  * @see {@link evalFilter}
@@ -28,8 +47,17 @@ class FlowrFilterCombinator {
         this.tree = this.unpack(init);
     }
     static is(value) {
-        if (typeof value === 'object') {
-            return new this(value);
+        if (typeof value === 'string' && exports.ValidFlowrFilters.has(value)) {
+            return new this({ type: 'special', value: value });
+        }
+        else if (typeof value === 'object') {
+            const name = value?.name;
+            if (name && exports.ValidFlowrFilters.has(name)) {
+                return new this({ type: 'special', value: value });
+            }
+            else {
+                return new this(value);
+            }
         }
         else if (type_1.ValidRTypes.has(value)) {
             return new this({ type: 'r-type', value: value });
@@ -37,9 +65,6 @@ class FlowrFilterCombinator {
         else if (vertex_1.ValidVertexTypes.has(value)) {
             return new this({ type: 'vertex-type', value: value });
         }
-        else if (exports.ValidFlowrFilters.has(value)) {
-            return new this({ type: 'special', value: value });
-        }
         else {
             throw new Error(`Invalid filter value: ${value}`);
         }
@@ -97,7 +122,7 @@ const typeToSymbol = {
 };
 function treeToStringImpl(tree, depth) {
     if (tree.type === 'r-type' || tree.type === 'vertex-type' || tree.type === 'special') {
-        return tree.value;
+        return typeof tree.value === 'string' ? tree.value : `${tree.value.name}@${JSON.stringify(tree.value.args)}`;
     }
     if (tree.type === 'not') {
         return `${typeToSymbol[tree.type]}${treeToStringImpl(tree.operand, depth)}`;
@@ -114,14 +139,16 @@ const evalVisit = {
     or: ({ left, right }, data) => evalTree(left, data) || evalTree(right, data),
     xor: ({ left, right }, data) => evalTree(left, data) !== evalTree(right, data),
     not: ({ operand }, data) => !evalTree(operand, data),
-    'r-type': ({ value }, { node }) => node.type === value,
-    'vertex-type': ({ value }, { dataflow: { graph }, node }) => graph.getVertex(node.info.id)?.tag === value,
-    'special': ({ value }, { node }) => {
-        const getHandler = exports.FlowrFilters[value];
+    'r-type': ({ value }, { element }) => element.node.type === value,
+    'vertex-type': ({ value }, { dataflow: { graph }, element }) => graph.getVertex(element.node.info.id)?.tag === value,
+    'special': ({ value }, { element }) => {
+        const name = typeof value === 'string' ? value : value.name;
+        const args = typeof value === 'string' ? undefined : value.args;
+        const getHandler = exports.FlowrFilters[name];
         if (getHandler) {
-            return getHandler(node);
+            return getHandler(element, args);
         }
-        throw new Error(`Special filter not implemented: ${value}`);
+        throw new Error(`Couldn't find special filter with name ${name}`);
     }
 };
 function evalTree(tree, data) {

package/search/flowr-search.d.ts

@@ -5,6 +5,8 @@ import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { DataflowInformation } from '../dataflow/info';
 import type { BaseQueryResult } from '../queries/base-query-format';
 import type { Query } from '../queries/query';
+import type { FlowrConfigOptions } from '../config';
+import type { MarkOptional } from 'ts-essentials';
 /**
  * Yes, for now we do technically not need a wrapper around the RNode, but this allows us to attach caches etc.
  * just for the respective search.
@@ -16,6 +18,7 @@ export interface FlowrSearchElementFromQuery<Info> extends FlowrSearchElement<In
     readonly query: Query['type'];
     readonly queryResult: BaseQueryResult;
 }
+export type FlowrSearchElementMaybeFromQuery<Info> = MarkOptional<FlowrSearchElementFromQuery<Info>, 'query' | 'queryResult'>;
 export interface FlowrSearchNodeBase<Type extends string, Name extends string, Args extends Record<string, unknown> | undefined> {
     readonly type: Type;
     readonly name: Name;
@@ -49,6 +52,7 @@ export interface FlowrSearchGetFilter extends Record<string, unknown> {
 type MinimumInputForFlowrSearch<P extends Pipeline> = PipelineStepOutputWithName<P, 'normalize'> extends NormalizedAst ? (PipelineStepOutputWithName<P, 'dataflow'> extends DataflowInformation ? PipelineOutput<P> & {
     normalize: NormalizedAst;
     dataflow: DataflowInformation;
+    config: FlowrConfigOptions;
 } : never) : never;
 /** we allow any pipeline, which provides us with a 'normalize' and 'dataflow' step */
 export type FlowrSearchInput<P extends Pipeline> = MinimumInputForFlowrSearch<P>;

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

@@ -17,7 +17,7 @@ export interface EnrichmentData<EnrichmentContent extends MergeableRecord, Enric
     /**
      * A function that is applied to each element of the search to enrich it with additional data.
      */
-    readonly enrich: (e: FlowrSearchElement<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: EnrichmentArguments | undefined) => EnrichmentContent;
+    readonly enrich: (e: FlowrSearchElement<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: EnrichmentArguments | undefined, previousValue: EnrichmentContent | undefined) => EnrichmentContent;
     /**
      * The mapping function used by the {@link Mapper.Enrichment} mapper.
      */
@@ -52,14 +52,18 @@ export declare const Enrichments: {
         enrich: (e: FlowrSearchElement<ParentInformation>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
             normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
             dataflow: import("../../dataflow/info").DataflowInformation;
-        }) => CallTargetsContent;
+            config: import("../../config").FlowrConfigOptions;
+        }, args: {
+            onlyBuiltin?: boolean;
+        } | undefined, prev: CallTargetsContent | undefined) => CallTargetsContent;
         mapper: ({ targets }: CallTargetsContent) => FlowrSearchElement<ParentInformation>[];
     };
     readonly "last-call": {
         enrich: (e: FlowrSearchElement<ParentInformation>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
             normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
             dataflow: import("../../dataflow/info").DataflowInformation;
-        }, args: Omit<LinkToLastCall<string | RegExp>, "type">[] | undefined) => LastCallContent;
+            config: import("../../config").FlowrConfigOptions;
+        }, args: Omit<LinkToLastCall<string | RegExp>, "type">[] | undefined, prev: LastCallContent | undefined) => LastCallContent;
         mapper: ({ linkedIds }: LastCallContent) => FlowrSearchElement<ParentInformation>[];
     };
 };

package/search/search-executor/search-enrichers.js

@@ -24,7 +24,7 @@ var Enrichment;
  */
 exports.Enrichments = {
     [Enrichment.CallTargets]: {
-        enrich: (e, data) => {
+        enrich: (e, data, args, prev) => {
             // we don't resolve aliases here yet!
             const content = { targets: [] };
             const callVertex = data.dataflow.graph.getVertex(e.node.info.id);
@@ -32,34 +32,42 @@ exports.Enrichments = {
                 const origins = (0, dfg_get_origin_1.getOriginInDfg)(data.dataflow.graph, callVertex.id);
                 if (!origins || origins.length === 0) {
                     content.targets = [(0, node_id_1.recoverName)(callVertex.id, data.normalize.idMap)];
-                    return content;
                 }
-                // find call targets in user code (which have ids!)
-                content.targets = content.targets.concat(origins.map(o => {
-                    switch (o.type) {
-                        case 2 /* OriginType.FunctionCallOrigin */:
-                            return {
-                                node: data.normalize.idMap.get(o.id),
-                            };
-                        case 3 /* OriginType.BuiltInFunctionOrigin */:
-                            return o.fn.name;
-                        default:
-                            return undefined;
+                else {
+                    // find call targets in user code (which have ids!)
+                    content.targets = content.targets.concat(origins.map(o => {
+                        switch (o.type) {
+                            case 2 /* OriginType.FunctionCallOrigin */:
+                                return {
+                                    node: data.normalize.idMap.get(o.id),
+                                };
+                            case 3 /* OriginType.BuiltInFunctionOrigin */:
+                                return o.fn.name;
+                            default:
+                                return undefined;
+                        }
+                    }).filter(assert_1.isNotUndefined));
+                    if (content.targets.length === 0) {
+                        content.targets = [(0, node_id_1.recoverName)(callVertex.id, data.normalize.idMap)];
                     }
-                }).filter(assert_1.isNotUndefined));
-                if (content.targets.length === 0) {
-                    content.targets = [(0, node_id_1.recoverName)(callVertex.id, data.normalize.idMap)];
                 }
             }
+            // if there is a call target that is not built-in (ie a custom function), we don't want to include it here
+            if (args?.onlyBuiltin && content.targets.some(t => typeof t !== 'string')) {
+                content.targets = [];
+            }
+            if (prev) {
+                content.targets.push(...prev.targets);
+            }
             return content;
         },
         // as built-in call target enrichments are not nodes, we don't return them as part of the mapper!
         mapper: ({ targets }) => targets.map(t => t).filter(t => t.node !== undefined)
     },
     [Enrichment.LastCall]: {
-        enrich: (e, data, args) => {
+        enrich: (e, data, args, prev) => {
             (0, assert_1.guard)(args && args.length, `${Enrichment.LastCall} enrichment requires at least one argument`);
-            const content = { linkedIds: [] };
+            const content = prev ?? { linkedIds: [] };
             const vertex = data.dataflow.graph.get(e.node.info.id);
             if (vertex !== undefined && vertex[0].tag === vertex_1.VertexType.FunctionCall) {
                 const cfg = (0, extract_cfg_1.extractSimpleCfg)(data.normalize);
@@ -90,11 +98,12 @@ function enrichmentContent(e, enrichment) {
 }
 function enrich(e, data, enrichment, args) {
     const enrichmentData = exports.Enrichments[enrichment];
+    const prev = e?.enrichments;
     return {
         ...e,
         enrichments: {
-            ...e?.enrichments ?? {},
-            [enrichment]: enrichmentData.enrich(e, data, args)
+            ...prev ?? {},
+            [enrichment]: enrichmentData.enrich(e, data, args, prev?.[enrichment])
         }
     };
 }

package/search/search-executor/search-generators.js

@@ -56,7 +56,7 @@ function generateFrom(data, args) {
 }
 function generateFromQuery(data, args) {
     const nodes = new Set();
-    const result = (0, query_1.executeQueries)({ ast: data.normalize, dataflow: data.dataflow }, args.from);
+    const result = (0, query_1.executeQueries)({ ast: data.normalize, dataflow: data.dataflow, config: data.config }, args.from);
     for (const [query, content] of Object.entries(result)) {
         if (query === '.meta') {
             continue;

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

@@ -29,6 +29,7 @@ export declare const transformers: {
     readonly skip: typeof getSkip;
     readonly filter: typeof getFilter;
     readonly merge: typeof getMerge;
+    readonly unique: typeof getUnique;
     readonly select: typeof getSelect;
     readonly with: typeof getWith;
     readonly map: typeof getMap;
@@ -66,4 +67,5 @@ declare function getMerge<Elements extends FlowrSearchElement<ParentInformation>
     search: unknown[];
     generator: FlowrSearchGeneratorNode;
 }): FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>;
+declare function getUnique<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrSearchInput<Pipeline>, elements: FSE): CascadeEmpty<Elements, Elements>;
 export {};

package/search/search-executor/search-transformer.js

@@ -19,6 +19,7 @@ exports.transformers = {
     skip: getSkip,
     filter: getFilter,
     merge: getMerge,
+    unique: getUnique,
     select: getSelect,
     with: getWith,
     map: getMap
@@ -92,7 +93,7 @@ function getSkip(data, elements, { count }) {
     return elements.mutate(e => sortFully(e).slice(count));
 }
 function getFilter(data, elements, { filter }) {
-    return elements.mutate(e => e.filter(({ node }) => (0, flowr_search_filters_1.evalFilter)(filter, { node, normalize: data.normalize, dataflow: data.dataflow })));
+    return elements.mutate(e => e.filter(e => (0, flowr_search_filters_1.evalFilter)(filter, { element: e, normalize: data.normalize, dataflow: data.dataflow })));
 }
 function getWith(data, elements, { info, args }) {
     return elements.mutate(elements => elements.map(e => (0, search_enrichers_1.enrich)(e, data, info, args)));
@@ -106,4 +107,12 @@ data, elements, other) {
     const resultOther = (0, flowr_search_executor_1.runSearch)(other, data);
     return elements.addAll(resultOther);
 }
+function getUnique(data, elements) {
+    return elements.mutate(e => e.reduce((acc, cur) => {
+        if (!acc.some(el => el.node.id === cur.node.id)) {
+            acc.push(cur);
+        }
+        return acc;
+    }, []));
+}
 //# sourceMappingURL=search-transformer.js.map

package/slicing/static/static-slicer.d.ts

@@ -14,7 +14,7 @@ export declare const slicerLogger: import("tslog").Logger<import("tslog").ILogOb
  *
  * @param graph     - The dataflow graph to conduct the slicing on.
  * @param ast       - The normalized AST of the code (used to get static nesting information of the lexemes in case of control flow dependencies that may have no effect on the slicing scope).
- * @param criteria  - The criterias to slice on.
+ * @param criteria  - The criteria to slice on.
  * @param threshold - The maximum number of nodes to visit in the graph. If the threshold is reached, the slice will side with inclusion and drop its minimal guarantee. The limit ensures that the algorithm halts.
  * @param cache     - A cache to store the results of the slice. If provided, the slice may use this cache to speed up the slicing process.
  */

package/slicing/static/static-slicer.js

@@ -12,7 +12,6 @@ const parse_1 = require("../criterion/parse");
 const environment_1 = require("../../dataflow/environments/environment");
 const vertex_1 = require("../../dataflow/graph/vertex");
 const edge_1 = require("../../dataflow/graph/edge");
-const config_1 = require("../../config");
 exports.slicerLogger = log_1.log.getSubLogger({ name: 'slicer' });
 /**
  * This returns the ids to include in the static backward slice, when slicing with the given seed id's (must be at least one).
@@ -21,11 +20,11 @@ exports.slicerLogger = log_1.log.getSubLogger({ name: 'slicer' });
  *
  * @param graph     - The dataflow graph to conduct the slicing on.
  * @param ast       - The normalized AST of the code (used to get static nesting information of the lexemes in case of control flow dependencies that may have no effect on the slicing scope).
- * @param criteria  - The criterias to slice on.
+ * @param criteria  - The criteria to slice on.
  * @param threshold - The maximum number of nodes to visit in the graph. If the threshold is reached, the slice will side with inclusion and drop its minimal guarantee. The limit ensures that the algorithm halts.
  * @param cache     - A cache to store the results of the slice. If provided, the slice may use this cache to speed up the slicing process.
  */
-function staticSlicing(graph, { idMap }, criteria, threshold = (0, config_1.getConfig)().solver.slicer?.threshold ?? 75, cache) {
+function staticSlicing(graph, { idMap }, criteria, threshold = 75, cache) {
     (0, assert_1.guard)(criteria.length > 0, 'must have at least one seed id to calculate slice');
     const decodedCriteria = (0, parse_1.convertAllSlicingCriteriaToIds)(criteria, idMap);
     (0, log_1.expensiveTrace)(exports.slicerLogger, () => `calculating slice for ${decodedCriteria.length} seed criteria: ${decodedCriteria.map(s => JSON.stringify(s)).join(', ')}`);

package/statistics/statistics.d.ts

@@ -4,6 +4,7 @@ import type { PipelineOutput } from '../core/steps/pipeline/pipeline';
 import { DEFAULT_DATAFLOW_PIPELINE } from '../core/steps/pipeline/default-pipelines';
 import type { RShell } from '../r-bridge/shell';
 import type { FeatureSelection, FeatureStatistics } from './features/feature';
+import type { FlowrConfigOptions } from '../config';
 /**
  * By default, {@link extractUsageStatistics} requires a generator, but sometimes you already know all the files
  * that you want to process. This function simply reps your requests as a generator.
@@ -14,13 +15,14 @@ type DataflowResult = PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>;
  * Extract all wanted statistic information from a set of requests using the presented R session.
  *
  * @param shell     - The R session to use
+ * @param config    - The flowr config
  * @param onRequest - A callback that is called at the beginning of each request, this may be used to debug the requests.
  * @param features  - The features to extract (see {@link allFeatureNames}).
  * @param requests  - The requests to extract the features from. May generate them on demand (e.g., by traversing a folder).
  * 										If your request is statically known, you can use {@link staticRequests} to create this generator.
  * @param rootPath  - The root path to the project, this is used to relativize the file paths in the statistics.
  */
-export declare function extractUsageStatistics<T extends RParseRequestFromText | RParseRequestFromFile>(shell: RShell, onRequest: (request: T) => void, features: FeatureSelection, requests: AsyncGenerator<T>, rootPath?: string): Promise<{
+export declare function extractUsageStatistics<T extends RParseRequestFromText | RParseRequestFromFile>(shell: RShell, config: FlowrConfigOptions, onRequest: (request: T) => void, features: FeatureSelection, requests: AsyncGenerator<T>, rootPath?: string): Promise<{
     features: FeatureStatistics;
     meta: MetaStatistics;
     outputs: Map<T, DataflowResult>;

package/statistics/statistics.js

@@ -30,13 +30,14 @@ function staticRequests(...requests) {
  * Extract all wanted statistic information from a set of requests using the presented R session.
  *
  * @param shell     - The R session to use
+ * @param config    - The flowr config
  * @param onRequest - A callback that is called at the beginning of each request, this may be used to debug the requests.
  * @param features  - The features to extract (see {@link allFeatureNames}).
  * @param requests  - The requests to extract the features from. May generate them on demand (e.g., by traversing a folder).
  * 										If your request is statically known, you can use {@link staticRequests} to create this generator.
  * @param rootPath  - The root path to the project, this is used to relativize the file paths in the statistics.
  */
-async function extractUsageStatistics(shell, onRequest, features, requests, rootPath) {
+async function extractUsageStatistics(shell, config, onRequest, features, requests, rootPath) {
     let result = initializeFeatureStatistics();
     const meta = (0, meta_statistics_1.initialMetaStatistics)();
     const outputs = new Map();
@@ -46,7 +47,7 @@ async function extractUsageStatistics(shell, onRequest, features, requests, root
         const suffix = request.request === 'file' ? request.content.replace(new RegExp('^' + (rootPath ?? '')), '') : undefined;
         try {
             let output;
-            ({ stats: result, output } = await extractSingle(result, shell, request, features, suffix));
+            ({ stats: result, output } = await extractSingle(result, shell, request, features, suffix, config));
             outputs.set(request, output);
             processMetaOnSuccessful(meta, request);
             meta.numberOfNormalizedNodes.push(output.normalize.idMap.size);
@@ -80,10 +81,10 @@ function processMetaOnSuccessful(meta, request) {
     }
 }
 const parser = new xmldom_1.DOMParser();
-async function extractSingle(result, shell, request, features, suffixFilePath) {
+async function extractSingle(result, shell, request, features, suffixFilePath, config) {
     const slicerOutput = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
         request, parser: shell
-    }).allRemainingSteps();
+    }, config).allRemainingSteps();
     // retrieve parsed xml through (legacy) xmlparsedata
     const suffix = request.request === 'file' ? ', encoding="utf-8"' : '';
     shell.sendCommands(`try(flowr_parsed<-parse(${request.request}=${JSON.stringify(request.content)},keep.source=TRUE${suffix}),silent=FALSE)`, 'try(flowr_output<-xmlparsedata::xml_parse_data(flowr_parsed,includeText=TRUE,pretty=FALSE),silent=FALSE)');

package/util/containers.d.ts

@@ -13,7 +13,7 @@ export declare function getAccessOperands<OtherInfo>(args: readonly RFunctionArg
     accessArg: RArgument<OtherInfo & ParentInformation> | undefined;
 };
 /**
- * Resolves the passed name in the passed environment and returns the indicesCollection of the resolved definitions.
+ * Resolves the passed name within the passed environment and returns the indicesCollection of the resolved definitions.
  *
  * @param name - Name to resolve
  * @param environment - Environment in which name is resolved
@@ -25,9 +25,10 @@ export declare function resolveIndicesByName(name: Identifier, environment: REnv
  *
  * If no indices could be found that match the `accessArg`, the original indices are returned as overapproximation.
  *
- * @param accessedArg - The argument to resolve
- * @param accessArg - The argument which is used to filter the indices
- * @param environment - The environment in which {@link accessedArg} is resolved
+ * @param accessedArg        - The argument to resolve
+ * @param accessArg          - The argument which is used to filter the indices
+ * @param environment        - The environment in which {@link accessedArg} is resolved
+ * @param isIndexBasedAccess - Whether the access is index-based (e.g. `x[1]`) or name-based (e.g. `x$name`)
  * @returns The filtered {@link ContainerIndicesCollection} of the resolved {@link accessedArg}
  */
 export declare function resolveSingleIndex(accessedArg: {
@@ -38,8 +39,9 @@ export declare function resolveSingleIndex(accessedArg: {
 /**
  * Filters the single indices of the {@link indicesCollection} according to the lexeme of the {@link accessArg}.
  *
- * @param indicesCollection - The {@link ContainerIndicesCollection} to filter
- * @param accessArg - The argument which is used to filter {@link indicesCollection}
+ * @param indicesCollection  - The {@link ContainerIndicesCollection} to filter
+ * @param accessArg          - The argument which is used to filter {@link indicesCollection}
+ * @param isIndexBasedAccess - Whether the access is index-based (e.g. `x[1]`) or name-based (e.g. `x$name`)
  * @returns The filtered copy of {@link indicesCollection}
  */
 export declare function filterIndices(indicesCollection: ContainerIndicesCollection, accessArg: {
@@ -54,8 +56,9 @@ export declare function filterIndices(indicesCollection: ContainerIndicesCollect
  * ```
  * would result in a list with the index `credentials`, which has the subIndex `username`.
  *
- * @param accessedArg - The top level argument that is accessed
- * @param leafIndices - The index at the end of the nested access i.e. `c` in `a$b$c`.
+ * @param accessedArg         - The top level argument that is accessed
+ * @param leafIndices         - The index at the end of the nested access i.e. `c` in `a$b$c`.
+ * @param constructIdentifier - A function that constructs the identifier for the index from the argument
  * @returns The constructed nested access
  */
 export declare function constructNestedAccess<OtherInfo>(accessedArg: RAccess<OtherInfo & ParentInformation>, leafIndices: ContainerIndices, constructIdentifier: (arg: RArgument<OtherInfo & ParentInformation>) => IndexIdentifier): ContainerIndices[];
@@ -63,6 +66,6 @@ export declare function constructNestedAccess<OtherInfo>(accessedArg: RAccess<Ot
  * Adds the passed list of {@link leafSubIndices} to the leaf (sub-)indices of {@link indicesCollection}.
  *
  * @param indicesCollection - Indices where to add the sub indices.
- * @param leafSubIndices - Indices that are added to the leaf indices.
+ * @param leafSubIndices    - Indices that are added to the leaf indices.
  */
 export declare function addSubIndicesToLeafIndices(indicesCollection: ContainerIndices[], leafSubIndices: ContainerIndices[]): ContainerIndices[];

package/util/containers.js

@@ -20,7 +20,7 @@ function getAccessOperands(args) {
     return { accessedArg, accessArg };
 }
 /**
- * Resolves the passed name in the passed environment and returns the indicesCollection of the resolved definitions.
+ * Resolves the passed name within the passed environment and returns the indicesCollection of the resolved definitions.
  *
  * @param name - Name to resolve
  * @param environment - Environment in which name is resolved
@@ -35,9 +35,10 @@ function resolveIndicesByName(name, environment) {
  *
  * If no indices could be found that match the `accessArg`, the original indices are returned as overapproximation.
  *
- * @param accessedArg - The argument to resolve
- * @param accessArg - The argument which is used to filter the indices
- * @param environment - The environment in which {@link accessedArg} is resolved
+ * @param accessedArg        - The argument to resolve
+ * @param accessArg          - The argument which is used to filter the indices
+ * @param environment        - The environment in which {@link accessedArg} is resolved
+ * @param isIndexBasedAccess - Whether the access is index-based (e.g. `x[1]`) or name-based (e.g. `x$name`)
  * @returns The filtered {@link ContainerIndicesCollection} of the resolved {@link accessedArg}
  */
 function resolveSingleIndex(accessedArg, accessArg, environment, isIndexBasedAccess) {
@@ -55,8 +56,9 @@ function resolveSingleIndex(accessedArg, accessArg, environment, isIndexBasedAcc
 /**
  * Filters the single indices of the {@link indicesCollection} according to the lexeme of the {@link accessArg}.
  *
- * @param indicesCollection - The {@link ContainerIndicesCollection} to filter
- * @param accessArg - The argument which is used to filter {@link indicesCollection}
+ * @param indicesCollection  - The {@link ContainerIndicesCollection} to filter
+ * @param accessArg          - The argument which is used to filter {@link indicesCollection}
+ * @param isIndexBasedAccess - Whether the access is index-based (e.g. `x[1]`) or name-based (e.g. `x$name`)
  * @returns The filtered copy of {@link indicesCollection}
  */
 function filterIndices(indicesCollection, accessArg, isIndexBasedAccess) {
@@ -83,8 +85,9 @@ function filterIndices(indicesCollection, accessArg, isIndexBasedAccess) {
  * ```
  * would result in a list with the index `credentials`, which has the subIndex `username`.
  *
- * @param accessedArg - The top level argument that is accessed
- * @param leafIndices - The index at the end of the nested access i.e. `c` in `a$b$c`.
+ * @param accessedArg         - The top level argument that is accessed
+ * @param leafIndices         - The index at the end of the nested access i.e. `c` in `a$b$c`.
+ * @param constructIdentifier - A function that constructs the identifier for the index from the argument
  * @returns The constructed nested access
  */
 function constructNestedAccess(accessedArg, leafIndices, constructIdentifier) {
@@ -116,7 +119,7 @@ function constructNestedAccess(accessedArg, leafIndices, constructIdentifier) {
  * Adds the passed list of {@link leafSubIndices} to the leaf (sub-)indices of {@link indicesCollection}.
  *
  * @param indicesCollection - Indices where to add the sub indices.
- * @param leafSubIndices - Indices that are added to the leaf indices.
+ * @param leafSubIndices    - Indices that are added to the leaf indices.
  */
 function addSubIndicesToLeafIndices(indicesCollection, leafSubIndices) {
     const result = [];

package/util/files.d.ts

@@ -40,17 +40,23 @@ export declare function writeTableAsCsv(table: Table, file: string, sep?: string
 /**
  * Reads a file line by line and calls the given function for each line.
  * The `lineNumber` starts at `0`.
+ * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
+ *
+ * @returns Whether all lines have been successfully read (`false` if `maxLines` was reached)
  *
  * See {@link readLineByLineSync} for a synchronous version.
  */
-export declare function readLineByLine(filePath: string, onLine: (line: Buffer, lineNumber: number) => Promise<void>): Promise<void>;
+export declare function readLineByLine(filePath: string, onLine: (line: Buffer, lineNumber: number) => Promise<void>, maxLines?: number): Promise<boolean>;
 /**
  * Reads a file line by line and calls the given function for each line.
  * The `lineNumber` starts at `0`.
+ * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
+ *
+ * @returns Whether the file exists and all lines have been successfully read (`false` if `maxLines` was reached)
  *
  * See {@link readLineByLine} for an asynchronous version.
  */
-export declare function readLineByLineSync(filePath: string, onLine: (line: Buffer, lineNumber: number) => void): void;
+export declare function readLineByLineSync(filePath: string, onLine: (line: Buffer, lineNumber: number) => void, maxLines?: number): boolean;
 /**
  * Chops off the last part of the given directory path after a path separator, essentially returning the path's parent directory.
  * If an absolute path is passed, the returned path is also absolute.

package/util/files.js

@@ -124,36 +124,54 @@ function writeTableAsCsv(table, file, sep = ',', newline = '\n') {
 /**
  * Reads a file line by line and calls the given function for each line.
  * The `lineNumber` starts at `0`.
+ * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
+ *
+ * @returns Whether all lines have been successfully read (`false` if `maxLines` was reached)
  *
  * See {@link readLineByLineSync} for a synchronous version.
  */
-async function readLineByLine(filePath, onLine) {
+async function readLineByLine(filePath, onLine, maxLines = Infinity) {
+    if (!(await fs_1.default.promises.stat(filePath).catch(() => { }))?.isFile()) {
+        log_1.log.warn(`File ${filePath} does not exist`);
+        return false;
+    }
     const reader = new n_readlines_1.default(filePath);
     let line;
     let counter = 0;
     // eslint-disable-next-line no-cond-assign
     while (line = reader.next()) {
+        if (counter >= maxLines) {
+            return false;
+        }
         await onLine(line, counter++);
     }
+    return true;
 }
 /**
  * Reads a file line by line and calls the given function for each line.
  * The `lineNumber` starts at `0`.
+ * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
+ *
+ * @returns Whether the file exists and all lines have been successfully read (`false` if `maxLines` was reached)
  *
  * See {@link readLineByLine} for an asynchronous version.
  */
-function readLineByLineSync(filePath, onLine) {
-    if (!fs_1.default.existsSync(filePath)) {
+function readLineByLineSync(filePath, onLine, maxLines = Infinity) {
+    if (!fs_1.default.statSync(filePath, { throwIfNoEntry: false })?.isFile()) {
         log_1.log.warn(`File ${filePath} does not exist`);
-        return;
+        return false;
     }
     const reader = new n_readlines_1.default(filePath);
     let line;
     let counter = 0;
     // eslint-disable-next-line no-cond-assign
     while (line = reader.next()) {
+        if (counter >= maxLines) {
+            return false;
+        }
         onLine(line, counter++);
     }
+    return true;
 }
 /**
  * Chops off the last part of the given directory path after a path separator, essentially returning the path's parent directory.

package/util/objects.d.ts

@@ -1,4 +1,4 @@
-import type { DeepPartial, DeepRequired } from 'ts-essentials';
+import type { DeepPartial, DeepReadonly, DeepRequired } from 'ts-essentials';
 /**
  * checks if `item` is an object (it may be an array, ...)
  */
@@ -6,13 +6,14 @@ export declare function isObjectOrArray(item: unknown): boolean;
 export type MergeableRecord = Record<string, unknown>;
 export type MergeableArray = unknown[];
 export type Mergeable = MergeableRecord | MergeableArray;
+type OrReadonly<T> = T | Readonly<T> | DeepReadonly<T>;
 /**
  * Given two objects deeply merges them, if an object is an array it will merge the array values!
  * Guarantees some type safety by requiring objects to merge to be from the same type (allows undefined)
  */
-export declare function deepMergeObject<T extends Mergeable>(base: Required<T>, addon?: T | DeepPartial<T> | Partial<T>): Required<T>;
-export declare function deepMergeObject<T extends Mergeable>(base: DeepRequired<T>, addon?: T | DeepPartial<T> | Partial<T>): DeepRequired<T>;
-export declare function deepMergeObject<T extends Mergeable>(base: T, addon?: DeepPartial<T> | Partial<T>): T;
+export declare function deepMergeObject<T extends Mergeable>(base: Required<OrReadonly<T>>, addon?: T | DeepPartial<T> | Partial<T>): Required<T>;
+export declare function deepMergeObject<T extends Mergeable>(base: DeepRequired<OrReadonly<T>>, addon?: T | DeepPartial<T> | Partial<T>): DeepRequired<T>;
+export declare function deepMergeObject<T extends Mergeable>(base: OrReadonly<T>, addon?: DeepPartial<T> | Partial<T>): T;
 export declare function deepMergeObject(base: Mergeable, addon: Mergeable): Mergeable;
 export declare function deepMergeObject(base?: Mergeable, addon?: Mergeable): Mergeable | undefined;
 type Defined<T> = Exclude<T, undefined>;