@boundaries/elements 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,5 +1,3 @@
1
- import { NotUndefined } from 'object-hash';
2
-
3
1
  /**
4
2
  * Type representing a micromatch pattern, which can be a string or an array of strings.
5
3
  */
@@ -15,11 +13,19 @@ type ConfigOptions = {
15
13
  * When enabled, it supports using "${...}" syntax in templates.
16
14
  **/
17
15
  legacyTemplates?: boolean;
16
+ /** Whether to enable caching */
17
+ cache?: boolean;
18
18
  };
19
- type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates"> & {
19
+ type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates" | "cache"> & {
20
20
  /** Whether to enable legacy template support */
21
21
  legacyTemplates: boolean;
22
+ /** Cache configuration options */
23
+ cache: boolean;
22
24
  };
25
+ /** Options for descriptors */
26
+ type DescriptorOptionsNormalized = Pick<ConfigOptionsNormalized, "includePaths" | "ignorePaths" | "cache">;
27
+ /** Options for element matchers */
28
+ type MatchersOptionsNormalized = Pick<ConfigOptionsNormalized, "legacyTemplates">;
23
29
 
24
30
  /**
25
31
  * Map of the modes to interpret the pattern in an ElementDescriptor.
@@ -116,7 +122,20 @@ type ElementDescriptors = ElementDescriptor[];
116
122
  /**
117
123
  * Serialized cache of element descriptions.
118
124
  */
119
- type ElementsDescriptorSerializedCache = Record<string, ElementDescription>;
125
+ type DescriptionsSerializedCache = Record<string, ElementDescription>;
126
+ /**
127
+ * Serialized cache of file elements.
128
+ */
129
+ type FileElementsSerializedCache = Record<string, FileElement>;
130
+ /**
131
+ * Serialized cache for ElementsDescriptor class.
132
+ */
133
+ type ElementsDescriptorSerializedCache = {
134
+ /** Serialized descriptions cache */
135
+ descriptions: DescriptionsSerializedCache;
136
+ /** Serialized files cache */
137
+ files: FileElementsSerializedCache;
138
+ };
120
139
  /**
121
140
  * Captured values from an element path.
122
141
  */
@@ -393,12 +412,15 @@ declare function isCoreDependencyElement(value: unknown): value is CoreDependenc
393
412
 
394
413
  declare const DEPENDENCY_KIND_TYPE: "type";
395
414
  declare const DEPENDENCY_KIND_VALUE: "value";
415
+ declare const DEPENDENCY_KIND_TYPEOF: "typeof";
396
416
  /** Map of the kinds of dependency, either a type dependency or a value dependency */
397
417
  declare const DEPENDENCY_KINDS_MAP: {
398
418
  /** Type import, e.g., `import type { X } from 'module'` */
399
419
  readonly TYPE: "type";
400
420
  /** Value import, e.g., `import { X } from 'module'` */
401
421
  readonly VALUE: "value";
422
+ /** typeof import, e.g. `type ModuleType = typeof import("./my_module");` */
423
+ readonly TYPE_OF: "typeof";
402
424
  };
403
425
  /** Kind of dependency, either a type dependency or a value dependency */
404
426
  type DependencyKind = (typeof DEPENDENCY_KINDS_MAP)[keyof typeof DEPENDENCY_KINDS_MAP];
@@ -527,52 +549,6 @@ type DescriptorsSerializedCache = {
527
549
  dependencies: DependenciesDescriptorSerializedCache;
528
550
  };
529
551
 
530
- /**
531
- * Class with methods to describe elements and dependencies between them.
532
- */
533
- declare class Descriptors {
534
- private readonly _elementsDescriptor;
535
- private readonly _dependenciesDescriptor;
536
- /** Creates a new DescriptorsManager instance
537
- * @param elementDescriptors The element descriptors.
538
- * @param configOptions The configuration options.
539
- */
540
- constructor(elementDescriptors: ElementDescriptors, configOptions?: ConfigOptions);
541
- /**
542
- * Serializes the elements and dependencies cache to a plain object.
543
- * @returns The serialized elements and dependencies cache.
544
- */
545
- serializeCache(): DescriptorsSerializedCache;
546
- /**
547
- * Sets the elements and dependencies cache from a serialized object.
548
- * @param serializedCache The serialized elements and dependencies cache.
549
- */
550
- setCacheFromSerialized(serializedCache: DescriptorsSerializedCache): void;
551
- /**
552
- * Clears all caches.
553
- */
554
- clearCache(): void;
555
- /**
556
- * Describes an element given its file path.
557
- * @param filePath The path of the file to describe.
558
- * @returns The description of the element.
559
- */
560
- describeElement(filePath?: string): FileElement;
561
- /**
562
- * Describes a dependency element given its dependency source and file path.
563
- * @param dependencySource The source of the dependency.
564
- * @param filePath The path of the file being the dependency, if known.
565
- * @returns The description of the dependency element.
566
- */
567
- describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
568
- /**
569
- * Describes elements in a dependency relationship, and provides additional information about the dependency itself.
570
- * @param options The options for describing the elements and the dependency details.
571
- * @returns The description of the dependency between the elements.
572
- */
573
- describeDependency(options: DescribeDependencyOptions): DependencyDescription;
574
- }
575
-
576
552
  /**
577
553
  * Result of matching an element selector against an element.
578
554
  */
@@ -592,10 +568,18 @@ type ElementsMatcherSerializedCache = Record<string, ElementSelectorData | null>
592
568
  * Serialized cache of dependencies matcher.
593
569
  */
594
570
  type DependenciesMatcherSerializedCache = Record<string, DependencyMatchResult>;
571
+ /**
572
+ * Serialized cache of matcher descriptors.
573
+ */
595
574
  type MatcherSerializedCache = {
596
575
  descriptors: DescriptorsSerializedCache;
597
- elementsMatcher: ElementsMatcherSerializedCache;
598
- dependenciesMatcher: DependenciesMatcherSerializedCache;
576
+ };
577
+ /**
578
+ * Serialized cache of micromatch matcher.
579
+ */
580
+ type MicromatchSerializedCache = {
581
+ matchingResults: Record<string, boolean>;
582
+ captures: Record<string, string[] | null>;
599
583
  };
600
584
  /**
601
585
  * Elements that can return a match when using an element selector.
@@ -784,6 +768,63 @@ type ExternalLibrarySelectors = ExternalLibrariesSelector;
784
768
  */
785
769
  type ExternalLibrariesSelector = ExternalLibrarySelector | ExternalLibrarySelector[];
786
770
 
771
+ /**
772
+ * Micromatch wrapper class with caching capabilities.
773
+ */
774
+ declare class Micromatch {
775
+ /**
776
+ * Cache for micromatch matching results
777
+ */
778
+ private readonly _matchingResultsCache;
779
+ /**
780
+ * Cache for micromatch captures
781
+ */
782
+ private readonly _capturesCache;
783
+ /**
784
+ * Cache for micromatch makeRe results
785
+ */
786
+ private readonly _makeReCache;
787
+ /**
788
+ * Creates an instance of Micromatch class.
789
+ * @param cache Whether to use caching or not.
790
+ */
791
+ constructor(cache: boolean);
792
+ /**
793
+ * Clears all caches.
794
+ */
795
+ clearCache(): void;
796
+ /**
797
+ * Serializes the current cache state.
798
+ * @returns The serialized cache data.
799
+ */
800
+ serializeCache(): MicromatchSerializedCache;
801
+ /**
802
+ * Restores the cache state from serialized data.
803
+ * @param serializedCache The serialized cache data.
804
+ */
805
+ setFromSerialized(serializedCache: MicromatchSerializedCache): void;
806
+ /**
807
+ * Optimized micromatch match with caching.
808
+ * @param value The value to match.
809
+ * @param pattern The pattern to match against.
810
+ * @returns True if the value matches the pattern, false otherwise.
811
+ */
812
+ isMatch(value: string, pattern: string | string[]): boolean;
813
+ /**
814
+ * Optimized micromatch capture with caching.
815
+ * @param pattern The pattern to match against.
816
+ * @param target The target string to test.
817
+ * @returns Captured groups or null if no match.
818
+ */
819
+ capture(pattern: string, target: string): string[] | null;
820
+ /**
821
+ * Optimized micromatch makeRe with caching.
822
+ * @param pattern The pattern to convert to RegExp.
823
+ * @returns The RegExp instance.
824
+ */
825
+ makeRe(pattern: string): RegExp;
826
+ }
827
+
787
828
  /**
788
829
  * Normalizes an ElementsSelector into an array of ElementSelectorData.
789
830
  * @param elementsSelector The elements selector, in any supported format.
@@ -795,22 +836,37 @@ declare function normalizeElementsSelector(elementsSelector: DependencyElementsS
795
836
  * Base matcher class to determine if elements or dependencies match a given selector.
796
837
  */
797
838
  declare class BaseElementsMatcher {
839
+ /**
840
+ * Option to use legacy templates with ${} syntax.
841
+ */
798
842
  protected readonly _legacyTemplates: boolean;
843
+ /**
844
+ * Micromatch instance for matching.
845
+ */
846
+ protected micromatch: Micromatch;
799
847
  /**
800
848
  * Creates a new BaseElementsMatcher.
801
849
  * @param config Configuration options for the matcher.
850
+ * @param globalCache Global cache instance.
802
851
  */
803
- constructor(config: ConfigOptionsNormalized);
852
+ constructor(config: MatchersOptionsNormalized, micromatch: Micromatch);
804
853
  /**
805
854
  * Converts a template with ${} to Handlebars {{}} templates for backwards compatibility.
806
855
  * @param template The template to convert.
807
856
  * @returns The converted template.
808
857
  */
809
858
  private _getBackwardsCompatibleTemplate;
859
+ /**
860
+ * Determines if a template contains Handlebars syntax.
861
+ * @param template The template to check.
862
+ * @returns True if the template contains Handlebars syntax, false otherwise.
863
+ */
864
+ private _isHandlebarsTemplate;
810
865
  /**
811
866
  * Returns a rendered template using the provided template data.
867
+ * Optimized version with template caching for better performance.
812
868
  * @param template The template to render.
813
- * @param extraTemplateData The data to use for replace in the template.
869
+ * @param templateData The data to use for replace in the template.
814
870
  * @returns The rendered template.
815
871
  */
816
872
  private _getRenderedTemplate;
@@ -823,11 +879,20 @@ declare class BaseElementsMatcher {
823
879
  protected getRenderedTemplates(template: MicromatchPattern, templateData: TemplateData): MicromatchPattern;
824
880
  /**
825
881
  * Returns whether the given value matches the micromatch pattern, converting non-string values to strings.
882
+ * Optimized version with caching for better performance.
826
883
  * @param value The value to check.
827
884
  * @param pattern The micromatch pattern to match against.
828
885
  * @returns Whether the value matches the pattern.
829
886
  */
830
887
  protected isMicromatchMatch(value: unknown, pattern: MicromatchPattern): boolean;
888
+ /**
889
+ * Returns whether the given value matches the micromatch pattern after rendering it as a template.
890
+ * @param pattern The micromatch pattern to render and match against.
891
+ * @param templateData The data to use for rendering the pattern as a template.
892
+ * @param value The value to check.
893
+ * @returns Whether the value matches the rendered pattern.
894
+ */
895
+ protected isTemplateMicromatchMatch(pattern: MicromatchPattern, templateData: TemplateData, value?: unknown): boolean;
831
896
  /**
832
897
  * Whether the given element key matches the selector key as booleans.
833
898
  * @param param0 The parameters object.
@@ -876,28 +941,15 @@ declare class BaseElementsMatcher {
876
941
  * Matcher class to determine if elements match a given selector.
877
942
  */
878
943
  declare class ElementsMatcher extends BaseElementsMatcher {
879
- /**
880
- * Cache to store previously described elements.
881
- */
882
- private readonly _cache;
944
+ /** Whether the cache is enabled or not */
945
+ private readonly _cacheIsEnabled;
883
946
  /**
884
947
  * Creates a new ElementsSelectorMatcher.
948
+ * @param config Configuration options for the matcher.
949
+ * @param micromatch Micromatch instance for matching.
950
+ * @param globalCache Global cache instance.
885
951
  */
886
- constructor(config: ConfigOptionsNormalized);
887
- /**
888
- * Serializes the cache to a plain object.
889
- * @returns The serialized cache.
890
- */
891
- serializeCache(): ElementsMatcherSerializedCache;
892
- /**
893
- * Sets the cache from a serialized object.
894
- * @param serializedCache The serialized cache.
895
- */
896
- setCacheFromSerialized(serializedCache: ElementsMatcherSerializedCache): void;
897
- /**
898
- * Clears the cache.
899
- */
900
- clearCache(): void;
952
+ constructor(config: MatchersOptionsNormalized, micromatch: Micromatch);
901
953
  /**
902
954
  * Whether the given element type matches the selector type.
903
955
  * @param element The element to check.
@@ -1016,32 +1068,18 @@ declare class ElementsMatcher extends BaseElementsMatcher {
1016
1068
  * Matcher class to determine if dependencies match a given dependencies selector.
1017
1069
  */
1018
1070
  declare class DependenciesMatcher extends BaseElementsMatcher {
1019
- /**
1020
- * Cache to store previously described dependencies.
1021
- */
1022
- private readonly _cache;
1023
1071
  /**
1024
1072
  * Elements matcher to use for matching elements within dependencies.
1025
1073
  */
1026
1074
  private readonly _elementsMatcher;
1027
1075
  /**
1028
1076
  * Creates a new DependenciesMatcher.
1077
+ * @param elementsMatcher Elements matcher to use for matching elements within dependencies.
1078
+ * @param config Configuration options for the matcher.
1079
+ * @param micromatch Micromatch instance for matching.
1080
+ * @param globalCache Global cache instance.
1029
1081
  */
1030
- constructor(elementsMatcher: ElementsMatcher, config: ConfigOptionsNormalized);
1031
- /**
1032
- * Serializes the cache to a plain object.
1033
- * @returns The serialized cache.
1034
- */
1035
- serializeCache(): DependenciesMatcherSerializedCache;
1036
- /**
1037
- * Sets the cache from a serialized object.
1038
- * @param serializedCache The serialized cache.
1039
- */
1040
- setCacheFromSerialized(serializedCache: DependenciesMatcherSerializedCache): void;
1041
- /**
1042
- * Clears the cache.
1043
- */
1044
- clearCache(): void;
1082
+ constructor(elementsMatcher: ElementsMatcher, config: MatchersOptionsNormalized, micromatch: Micromatch);
1045
1083
  /**
1046
1084
  * Normalizes selector into DependencySelectorNormalized format, containing arrays of selectors data.
1047
1085
  * @param selector The dependency selector to normalize.
@@ -1226,9 +1264,12 @@ declare class Matcher {
1226
1264
  /**
1227
1265
  * Constructor for the Matcher class.
1228
1266
  * @param descriptors Element descriptors to use for matching.
1267
+ * @param elementsMatcher Elements matcher instance.
1268
+ * @param dependenciesMatcher Dependencies matcher instance.
1229
1269
  * @param config Configuration options.
1270
+ * @param globalCache Global cache instance.
1230
1271
  */
1231
- constructor(descriptors: ElementDescriptors, config: ConfigOptionsNormalized);
1272
+ constructor(descriptors: ElementDescriptors, elementsMatcher: ElementsMatcher, dependenciesMatcher: DependenciesMatcher, config: DescriptorOptionsNormalized, micromatch: Micromatch);
1232
1273
  /**
1233
1274
  * Determines if an element matches a given selector.
1234
1275
  * @param filePath The file path of the element
@@ -1268,7 +1309,7 @@ declare class Matcher {
1268
1309
  * @param options Extra options for matching
1269
1310
  * @returns The matching dependency result or null if no match is found
1270
1311
  */
1271
- private _isDependencySelectorMatching;
1312
+ private _getDependencySelectorMatching;
1272
1313
  /**
1273
1314
  * Determines the selector matching for a dependency or element.
1274
1315
  * @param descriptorOptions The file path or dependency options to describe the element or dependency
@@ -1311,21 +1352,66 @@ declare class Matcher {
1311
1352
  */
1312
1353
  clearCache(): void;
1313
1354
  /**
1314
- * Serializes the descriptors and elements matchers cache to a plain object.
1355
+ * Serializes the descriptors matchers cache to a plain object.
1315
1356
  * @returns The serialized cache
1316
1357
  */
1317
1358
  serializeCache(): MatcherSerializedCache;
1318
1359
  /**
1319
- * Sets the descriptors and elements matchers cache from a serialized object.
1360
+ * Sets the descriptors matchers cache from a serialized object.
1320
1361
  * @param serializedCache The serialized cache
1321
1362
  */
1322
1363
  setCacheFromSerialized(serializedCache: {
1323
1364
  descriptors: ReturnType<Descriptors["serializeCache"]>;
1324
- elementsMatcher: ReturnType<ElementsMatcher["serializeCache"]>;
1325
- dependenciesMatcher: ReturnType<DependenciesMatcher["serializeCache"]>;
1326
1365
  }): void;
1327
1366
  }
1328
1367
 
1368
+ /**
1369
+ * Class with methods to describe elements and dependencies between them.
1370
+ */
1371
+ declare class Descriptors {
1372
+ private readonly _elementsDescriptor;
1373
+ private readonly _dependenciesDescriptor;
1374
+ /** Creates a new DescriptorsManager instance
1375
+ * @param elementDescriptors The element descriptors.
1376
+ * @param configOptions The configuration options.
1377
+ * @param micromatch The Micromatch instance.
1378
+ */
1379
+ constructor(elementDescriptors: ElementDescriptors, config: DescriptorOptionsNormalized, micromatch: Micromatch);
1380
+ /**
1381
+ * Serializes the elements and dependencies cache to a plain object.
1382
+ * @returns The serialized elements and dependencies cache.
1383
+ */
1384
+ serializeCache(): DescriptorsSerializedCache;
1385
+ /**
1386
+ * Sets the elements and dependencies cache from a serialized object.
1387
+ * @param serializedCache The serialized elements and dependencies cache.
1388
+ */
1389
+ setCacheFromSerialized(serializedCache: DescriptorsSerializedCache): void;
1390
+ /**
1391
+ * Clears all caches.
1392
+ */
1393
+ clearCache(): void;
1394
+ /**
1395
+ * Describes an element given its file path.
1396
+ * @param filePath The path of the file to describe.
1397
+ * @returns The description of the element.
1398
+ */
1399
+ describeElement(filePath?: string): FileElement;
1400
+ /**
1401
+ * Describes a dependency element given its dependency source and file path.
1402
+ * @param dependencySource The source of the dependency.
1403
+ * @param filePath The path of the file being the dependency, if known.
1404
+ * @returns The description of the dependency element.
1405
+ */
1406
+ describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
1407
+ /**
1408
+ * Describes elements in a dependency relationship, and provides additional information about the dependency itself.
1409
+ * @param options The options for describing the elements and the dependency details.
1410
+ * @returns The description of the dependency between the elements.
1411
+ */
1412
+ describeDependency(options: DescribeDependencyOptions): DependencyDescription;
1413
+ }
1414
+
1329
1415
  /**
1330
1416
  * Serialized cache for Elements class.
1331
1417
  */
@@ -1336,10 +1422,7 @@ type ElementsSerializedCache = {
1336
1422
  elementDescriptors: ElementDescriptors;
1337
1423
  cache: MatcherSerializedCache;
1338
1424
  }>;
1339
- /** Cache for ElementsMatcher */
1340
- elementsMatcher: ElementsMatcherSerializedCache;
1341
- /** Cache for DependenciesMatcher */
1342
- dependenciesMatcher: DependenciesMatcherSerializedCache;
1425
+ micromatch: MicromatchSerializedCache;
1343
1426
  };
1344
1427
 
1345
1428
  /**
@@ -1351,10 +1434,9 @@ declare class Elements {
1351
1434
  private readonly _globalConfigOptions;
1352
1435
  /** Cache manager for Matcher instances, unique for each different configuration */
1353
1436
  private readonly _matchersCache;
1354
- /** Matcher for element selectors */
1355
- private readonly _elementsMatcher;
1356
- /** Matcher for dependency selectors */
1357
- private readonly _dependenciesMatcher;
1437
+ /** Micromatch instances for pattern matching */
1438
+ private readonly _micromatchWithCache;
1439
+ private readonly _micromatchWithoutCache;
1358
1440
  /**
1359
1441
  * Creates a new Elements instance
1360
1442
  * @param configOptions The global configuration options for Elements. Can be overridden when getting a descriptor.
@@ -1378,10 +1460,10 @@ declare class Elements {
1378
1460
  * Gets a Matcher instance for the given configuration options.
1379
1461
  * It uses caching to return the same instance for the same configuration options. If no options are provided, the global configuration options are used.
1380
1462
  * @param elementDescriptors The element descriptors to use.
1381
- * @param configOptions Optional configuration options to override the global ones.
1463
+ * @param config Optional configuration options to override the global ones.
1382
1464
  * @returns A matcher instance, unique for each different configuration.
1383
1465
  */
1384
- getMatcher(elementDescriptors: ElementDescriptors, configOptions?: ConfigOptions): Matcher;
1466
+ getMatcher(elementDescriptors: ElementDescriptors, config?: ConfigOptions): Matcher;
1385
1467
  }
1386
1468
 
1387
1469
  /**
@@ -1392,7 +1474,7 @@ declare class ElementsDescriptor {
1392
1474
  /**
1393
1475
  * Cache to store previously described elements.
1394
1476
  */
1395
- private readonly _elementsCache;
1477
+ private readonly _descriptionsCache;
1396
1478
  /**
1397
1479
  * Cache to store previously described files.
1398
1480
  */
@@ -1405,12 +1487,16 @@ declare class ElementsDescriptor {
1405
1487
  * Element descriptors used by this descriptor.
1406
1488
  */
1407
1489
  private readonly _elementDescriptors;
1490
+ /** Micromatch instance for path matching */
1491
+ private readonly _micromatch;
1408
1492
  /**
1409
1493
  * The configuration options for this descriptor.
1410
1494
  * @param elementDescriptors The element descriptors.
1411
1495
  * @param configOptions The configuration options.
1496
+ * @param globalCache The global cache for various caching needs.
1497
+ * @param micromatch The micromatch instance for path matching.
1412
1498
  */
1413
- constructor(elementDescriptors: ElementDescriptors, configOptions?: ConfigOptions);
1499
+ constructor(elementDescriptors: ElementDescriptors, configOptions: DescriptorOptionsNormalized, micromatch: Micromatch);
1414
1500
  /**
1415
1501
  * Serializes the elements cache to a plain object.
1416
1502
  * @returns The serialized elements cache.
@@ -1457,7 +1543,7 @@ declare class ElementsDescriptor {
1457
1543
  * @param dependencySource The source of the dependency to check.
1458
1544
  * @returns The base source of the external module. (e.g., for "@scope/package/submodule", it returns "@scope/package")
1459
1545
  */
1460
- private _getExternalModuleBaseSource;
1546
+ private _getExternalOrCoreModuleBaseSource;
1461
1547
  /**
1462
1548
  * Determines if an element is external based on its file path and dependency source.
1463
1549
  * Files inside "node_modules" are considered external.
@@ -1470,7 +1556,9 @@ declare class ElementsDescriptor {
1470
1556
  private _isExternalDependency;
1471
1557
  /**
1472
1558
  * Determines if a given path is included based on the configuration.
1559
+ * Uses caching for better performance on repeated calls.
1473
1560
  * @param elementPath The element path to check.
1561
+ * @param includeExternal Whether to include external files.
1474
1562
  * @returns True if the path is included, false otherwise.
1475
1563
  */
1476
1564
  private _pathIsIncluded;
@@ -1496,10 +1584,7 @@ declare class ElementsDescriptor {
1496
1584
  */
1497
1585
  private _fileDescriptorMatch;
1498
1586
  /**
1499
- * Retrieves the description of an element given its path.
1500
- * It does not identify external files. Files not matching any element are considered unknown.
1501
- * If a file in node_modules does a match, it is considered local as well.
1502
- * @param includeExternal Whether to include external files (inside node_modules) in the matching process.
1587
+ * Retrieves the description of a local file given its path.
1503
1588
  * @param elementPath The path of the element to describe.
1504
1589
  * @returns The description of the element.
1505
1590
  */
@@ -1512,12 +1597,12 @@ declare class ElementsDescriptor {
1512
1597
  */
1513
1598
  private _describeFile;
1514
1599
  /**
1515
- * Describes a dependency element given the file element and dependency source, by completing the file description.
1516
- * @param element The file element to complete the description for.
1600
+ * Returns an external or core dependency element given its dependency source and file path.
1517
1601
  * @param dependencySource The source of the dependency.
1518
- * @returns The description of the dependency element.
1602
+ * @param filePath The resolved file path of the dependency, if known.
1603
+ * @returns The external or core dependency element, or null if it is a local dependency.
1519
1604
  */
1520
- private _describeDependencyElement;
1605
+ private _getExternalOrCoreDependencyElement;
1521
1606
  /**
1522
1607
  * Describes an element given its file path and dependency source, if any.
1523
1608
  * @param filePath The path of the file to describe.
@@ -1552,11 +1637,16 @@ declare class DependenciesDescriptor {
1552
1637
  * Elements descriptor instance.
1553
1638
  */
1554
1639
  private readonly _elementsDescriptor;
1640
+ /**
1641
+ * Configuration options.
1642
+ */
1643
+ private readonly _config;
1555
1644
  /**
1556
1645
  * Creates a new DependenciesDescriptor instance.
1557
1646
  * @param elementsDescriptor The elements descriptor instance.
1647
+ * @param config The configuration options.
1558
1648
  */
1559
- constructor(elementsDescriptor: ElementsDescriptor);
1649
+ constructor(elementsDescriptor: ElementsDescriptor, config: DescriptorOptionsNormalized);
1560
1650
  /**
1561
1651
  * Serializes the elements cache to a plain object.
1562
1652
  * @returns The serialized elements cache.
@@ -1635,6 +1725,9 @@ declare class DependenciesDescriptor {
1635
1725
  describeDependency({ from, to, source, kind, nodeKind, specifiers, }: DescribeDependencyOptions): DependencyDescription;
1636
1726
  }
1637
1727
 
1728
+ type ObjectCacheKey = Record<string, unknown>;
1729
+ type NotUndefined = object | string | number | boolean | NotUndefined[];
1730
+
1638
1731
  /**
1639
1732
  * Generic cache manager class. Enables caching of values based on complex keys.
1640
1733
  */
@@ -1647,36 +1740,36 @@ declare class CacheManager<CacheKey extends NotUndefined, CachedValue> {
1647
1740
  * Creates a new CacheManager instance
1648
1741
  */
1649
1742
  constructor();
1743
+ /**
1744
+ * Generates a string key from the given cache key. Has to be implemented for non-string keys.
1745
+ * @param key The cache key to generate from
1746
+ * @returns The generated string key
1747
+ */
1748
+ protected generateKey(key: CacheKey): string;
1650
1749
  /**
1651
1750
  * Generates a hashed key for the given cache key
1652
1751
  * @param key The cache key to hash
1653
1752
  * @returns The hashed key as a string
1654
1753
  */
1655
- private _getHashedKey;
1754
+ getKey(key: CacheKey): string;
1656
1755
  /**
1657
- * Retrieves a value from the cache based on the given key
1658
- * @param key The cache key to retrieve
1756
+ * Retrieves a value from the cache based on the given hashed key
1757
+ * @param hashedKey The hashed key to retrieve
1659
1758
  * @returns The cached value or undefined if not found
1660
1759
  */
1661
- get(key: CacheKey): CachedValue | undefined;
1760
+ get(hashedKey: string): CachedValue | undefined;
1662
1761
  /**
1663
- * Stores a value in the cache
1664
- * @param key The cache key to store
1762
+ * Stores a value in the cache with a given hashed key
1763
+ * @param hashedKey The hashed key to store
1665
1764
  * @param value The value to cache
1666
1765
  */
1667
- set(key: CacheKey, value: CachedValue): void;
1668
- /**
1669
- * Restores a value in the cache from a given already hashed key
1670
- * @param key The hashed key to restore
1671
- * @param value The value to restore
1672
- */
1673
- restore(key: string, value: CachedValue): void;
1766
+ set(hashedKey: string, value: CachedValue): void;
1674
1767
  /**
1675
- * Checks if a value exists in the cache
1676
- * @param key The cache key to check
1768
+ * Checks if a value exists in the cache based on the given hashed key
1769
+ * @param hashedKey The hashed key to check
1677
1770
  * @returns True if the value exists, false otherwise
1678
1771
  */
1679
- has(key: CacheKey): boolean;
1772
+ has(hashedKey: string): boolean;
1680
1773
  /**
1681
1774
  * Retrieves all cached values
1682
1775
  * @returns A map of all cached values
@@ -1698,4 +1791,4 @@ declare class CacheManager<CacheKey extends NotUndefined, CachedValue> {
1698
1791
  setFromSerialized(serializedCache: Record<string, CachedValue>): void;
1699
1792
  }
1700
1793
 
1701
- export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MicromatchPattern, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };
1794
+ export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_TYPEOF, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, type DescriptionsSerializedCache, type DescriptorOptionsNormalized, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type FileElementsSerializedCache, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };