89f4897a0c55ea075fb343d716bc184c27a9ed7f63913189cc16b3c061ef65373bc303068c51c1e5bf15a151de540b7126e60790d11fc74cade73fc13e6de1 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564
  1. interface ResolveOptions {
  2. /**
  3. * A URL, path or array of URLs/paths to resolve against.
  4. */
  5. url?: string | URL | (string | URL)[];
  6. /**
  7. * File extensions to consider when resolving modules.
  8. */
  9. extensions?: string[];
  10. /**
  11. * Conditions to consider when resolving package exports.
  12. */
  13. conditions?: string[];
  14. }
  15. /**
  16. * Synchronously resolves a module path based on the options provided.
  17. *
  18. * @param {string} id - The identifier or path of the module to resolve.
  19. * @param {ResolveOptions} [options] - Options to resolve the module. See {@link ResolveOptions}.
  20. * @returns {string} The resolved URL as a string.
  21. */
  22. declare function resolveSync(id: string, options?: ResolveOptions): string;
  23. /**
  24. * Asynchronously resolves a module path based on the given options.
  25. *
  26. * @param {string} id - The identifier or path of the module to resolve.
  27. * @param {ResolveOptions} [options] - Options for resolving the module. See {@link ResolveOptions}.
  28. * @returns {Promise<string>} A promise to resolve the URL as a string.
  29. */
  30. declare function resolve(id: string, options?: ResolveOptions): Promise<string>;
  31. /**
  32. * Synchronously resolves a module path to a local file path based on the given options.
  33. *
  34. * @param {string} id - The identifier or path of the module to resolve.
  35. * @param {ResolveOptions} [options] - Options to resolve the module. See {@link ResolveOptions}.
  36. * @returns {string} The resolved file path.
  37. */
  38. declare function resolvePathSync(id: string, options?: ResolveOptions): string;
  39. /**
  40. * Asynchronously resolves a module path to a local file path based on the options provided.
  41. *
  42. * @param {string} id - The identifier or path of the module to resolve.
  43. * @param {ResolveOptions} [options] - Options for resolving the module. See {@link ResolveOptions}.
  44. * @returns {Promise<string>} A promise to resolve to the file path.
  45. */
  46. declare function resolvePath(id: string, options?: ResolveOptions): Promise<string>;
  47. /**
  48. * Creates a resolver function with default options that can be used to resolve module identifiers.
  49. *
  50. * @param {ResolveOptions} [defaults] - Default options to use for all resolutions. See {@link ResolveOptions}.
  51. * @returns {Function} A resolver function that takes an identifier and an optional URL, and resolves the identifier using the default options and the given URL.
  52. */
  53. declare function createResolve(defaults?: ResolveOptions): (id: string, url?: ResolveOptions["url"]) => Promise<string>;
  54. /**
  55. * Parses a node module path to extract the directory, name, and subpath.
  56. *
  57. * @param {string} path - The path to parse.
  58. * @returns {Object} An object containing the directory, module name, and subpath of the node module.
  59. */
  60. declare function parseNodeModulePath(path: string): {
  61. dir?: undefined;
  62. name?: undefined;
  63. subpath?: undefined;
  64. } | {
  65. dir: string;
  66. name: string;
  67. subpath: string | undefined;
  68. };
  69. /**
  70. * Attempts to reverse engineer a subpath export within a node module.
  71. *
  72. * @param {string} path - The path within the node module.
  73. * @returns {Promise<string | undefined>} A promise that resolves to the detected subpath or undefined if not found.
  74. */
  75. declare function lookupNodeModuleSubpath(path: string): Promise<string | undefined>;
  76. /**
  77. * Represents a general structure for ECMAScript module imports.
  78. */
  79. interface ESMImport {
  80. /**
  81. * Specifies the type of import: "static" for static imports and "dynamic" for dynamic imports.
  82. */
  83. type: "static" | "dynamic";
  84. /**
  85. * The full import declaration code snippet as a string.
  86. */
  87. code: string;
  88. /**
  89. * The starting position (index) of the import declaration in the source code.
  90. */
  91. start: number;
  92. /**
  93. * The end position (index) of the import declaration in the source code.
  94. */
  95. end: number;
  96. }
  97. /**
  98. * Represents a static import declaration in an ECMAScript module.
  99. * Extends {@link ESMImport}.
  100. */
  101. interface StaticImport extends ESMImport {
  102. /**
  103. * Indicates the type of import, specifically a static import.
  104. */
  105. type: "static";
  106. /**
  107. * Contains the entire import statement as a string, excluding the module specifier.
  108. */
  109. imports: string;
  110. /**
  111. * The module specifier from which imports are being brought in.
  112. */
  113. specifier: string;
  114. }
  115. /**
  116. * Represents a parsed static import declaration with detailed components of the import.
  117. * Extends {@link StaticImport}.
  118. */
  119. interface ParsedStaticImport extends StaticImport {
  120. /**
  121. * The default import name, if any.
  122. * @optional
  123. */
  124. defaultImport?: string;
  125. /**
  126. * The namespace import name, if any, using the `* as` syntax.
  127. * @optional
  128. */
  129. namespacedImport?: string;
  130. /**
  131. * An object representing named imports, with their local aliases if specified.
  132. * Each property key is the original name and its value is the alias.
  133. * @optional
  134. */
  135. namedImports?: {
  136. [name: string]: string;
  137. };
  138. }
  139. /**
  140. * Represents a dynamic import declaration that is loaded at runtime.
  141. * Extends {@link ESMImport}.
  142. */
  143. interface DynamicImport extends ESMImport {
  144. /**
  145. * Indicates that this is a dynamic import.
  146. */
  147. type: "dynamic";
  148. /**
  149. * The expression or path to be dynamically imported, typically a module path or URL.
  150. */
  151. expression: string;
  152. }
  153. /**
  154. * Represents a type-specific import, primarily used for importing types in TypeScript.
  155. * Extends {@link ESMImport} but omits the 'type' to redefine it specifically for type imports.
  156. */
  157. interface TypeImport extends Omit<ESMImport, "type"> {
  158. /**
  159. * Specifies that this is a type import.
  160. */
  161. type: "type";
  162. /**
  163. * Contains the entire type import statement as a string, excluding the module specifier.
  164. */
  165. imports: string;
  166. /**
  167. * The module specifier from which to import types.
  168. */
  169. specifier: string;
  170. }
  171. /**
  172. * Represents a general structure for ECMAScript module exports.
  173. */
  174. interface ESMExport {
  175. /**
  176. * Optional explicit type for complex scenarios, often used internally.
  177. * @optional
  178. */
  179. _type?: "declaration" | "named" | "default" | "star";
  180. /**
  181. * The type of export (declaration, named, default or star).
  182. */
  183. type: "declaration" | "named" | "default" | "star";
  184. /**
  185. * The specific type of declaration being exported, if applicable.
  186. * @optional
  187. */
  188. declarationType?: "let" | "var" | "const" | "enum" | "const enum" | "class" | "function" | "async function";
  189. /**
  190. * The full code snippet of the export statement.
  191. */
  192. code: string;
  193. /**
  194. * The starting position (index) of the export declaration in the source code.
  195. */
  196. start: number;
  197. /**
  198. * The end position (index) of the export declaration in the source code.
  199. */
  200. end: number;
  201. /**
  202. * The name of the variable, function or class being exported, if given explicitly.
  203. * @optional
  204. */
  205. name?: string;
  206. /**
  207. * The name used for default exports when a specific identifier isn't given.
  208. * @optional
  209. */
  210. defaultName?: string;
  211. /**
  212. * An array of names to export, applicable to named and destructured exports.
  213. */
  214. names: string[];
  215. /**
  216. * The module specifier, if any, from which exports are being re-exported.
  217. * @optional
  218. */
  219. specifier?: string;
  220. }
  221. /**
  222. * Represents a declaration export within an ECMAScript module.
  223. * Extends {@link ESMExport}.
  224. */
  225. interface DeclarationExport extends ESMExport {
  226. /**
  227. * Indicates that this export is a declaration export.
  228. */
  229. type: "declaration";
  230. /**
  231. * The declaration string, such as 'let', 'const', 'class', etc., describing what is being exported.
  232. */
  233. declaration: string;
  234. /**
  235. * The name of the declaration to be exported.
  236. */
  237. name: string;
  238. }
  239. /**
  240. * Represents a named export within an ECMAScript module.
  241. * Extends {@link ESMExport}.
  242. */
  243. interface NamedExport extends ESMExport {
  244. /**
  245. * Specifies that this export is a named export.
  246. */
  247. type: "named";
  248. /**
  249. * The export string, containing all exported identifiers.
  250. */
  251. exports: string;
  252. /**
  253. * An array of names to export.
  254. */
  255. names: string[];
  256. /**
  257. * The module specifier, if any, from which exports are being re-exported.
  258. * @optional
  259. */
  260. specifier?: string;
  261. }
  262. /**
  263. * Represents a standard export within an ECMAScript module.
  264. * Extends {@link ESMExport}.
  265. */
  266. interface DefaultExport extends ESMExport {
  267. /**
  268. * Specifies that this export is a standard export.
  269. */
  270. type: "default";
  271. }
  272. /**
  273. * Regular expression to match static import statements in JavaScript/TypeScript code.
  274. * @example `import { foo, bar as baz } from 'module'`
  275. */
  276. declare const ESM_STATIC_IMPORT_RE: RegExp;
  277. /**
  278. * Regular expression to match dynamic import statements in JavaScript/TypeScript code.
  279. * @example `import('module')`
  280. */
  281. declare const DYNAMIC_IMPORT_RE: RegExp;
  282. /**
  283. * Regular expression to match various types of export declarations including variables, functions, and classes.
  284. * @example `export const num = 1, str = 'hello'; export class Example {}`
  285. */
  286. declare const EXPORT_DECAL_RE: RegExp;
  287. /**
  288. * Regular expression to match export declarations specifically for types, interfaces, and type aliases in TypeScript.
  289. * @example `export type Result = { success: boolean; }; export interface User { name: string; age: number; };`
  290. */
  291. declare const EXPORT_DECAL_TYPE_RE: RegExp;
  292. /**
  293. * Finds all static import statements within the given code string.
  294. * @param {string} code - The source code to search for static imports.
  295. * @returns {StaticImport[]} An array of {@link StaticImport} objects representing each static import found.
  296. */
  297. declare function findStaticImports(code: string): StaticImport[];
  298. /**
  299. * Searches for dynamic import statements in the given source code.
  300. * @param {string} code - The source to search for dynamic imports in.
  301. * @returns {DynamicImport[]} An array of {@link DynamicImport} objects representing each dynamic import found.
  302. */
  303. declare function findDynamicImports(code: string): DynamicImport[];
  304. /**
  305. * Identifies and returns all type import statements in the given source code.
  306. * This function is specifically targeted at type imports used in TypeScript.
  307. * @param {string} code - The source code to search for type imports.
  308. * @returns {TypeImport[]} An array of {@link TypeImport} objects representing each type import found.
  309. */
  310. declare function findTypeImports(code: string): TypeImport[];
  311. /**
  312. * Parses a static import or type import to extract detailed import elements such as default, namespace and named imports.
  313. * @param {StaticImport | TypeImport} matched - The matched import statement to parse. See {@link StaticImport} and {@link TypeImport}.
  314. * @returns {ParsedStaticImport} A structured object representing the parsed static import. See {@link ParsedStaticImport}.
  315. */
  316. declare function parseStaticImport(matched: StaticImport | TypeImport): ParsedStaticImport;
  317. /**
  318. * Parses a static import or type import to extract detailed import elements such as default, namespace and named imports.
  319. * @param {StaticImport | TypeImport} matched - The matched import statement to parse. See {@link StaticImport} and {@link TypeImport}.
  320. * @returns {ParsedStaticImport} A structured object representing the parsed static import. See {@link ParsedStaticImport}.
  321. */
  322. declare function parseTypeImport(matched: TypeImport | StaticImport): ParsedStaticImport;
  323. /**
  324. * Identifies all export statements in the supplied source code and categorises them into different types such as declarations, named, default and star exports.
  325. * This function processes the code to capture different forms of export statements and normalise their representation for further processing.
  326. *
  327. * @param {string} code - The source code containing the export statements to be analysed.
  328. * @returns {ESMExport[]} An array of {@link ESMExport} objects representing each export found, properly categorised and structured.
  329. */
  330. declare function findExports(code: string): ESMExport[];
  331. /**
  332. * Searches specifically for type-related exports in TypeScript code, such as exported interfaces, types, and declarations prefixed with 'declare'.
  333. * This function uses specialised regular expressions to identify type exports and normalises them for consistency.
  334. *
  335. * @param {string} code - The TypeScript source code to search for type exports.
  336. * @returns {ESMExport[]} An array of {@link ESMExport} objects representing each type export found.
  337. */
  338. declare function findTypeExports(code: string): ESMExport[];
  339. /**
  340. * Extracts and returns a list of all export names from the given source.
  341. * This function uses {@link findExports} to retrieve all types of exports and consolidates their names into a single array.
  342. *
  343. * @param {string} code - The source code to search for export names.
  344. * @returns {string[]} An array containing the names of all exports found in the code.
  345. */
  346. declare function findExportNames(code: string): string[];
  347. /**
  348. * Asynchronously resolves and returns all export names from a module specified by its module identifier.
  349. * This function recursively resolves all explicitly named and asterisked (* as) exports to fully enumerate the exported identifiers.
  350. *
  351. * @param {string} id - The module identifier to resolve.
  352. * @param {ResolveOptions} [options] - Optional settings for resolving the module path, such as the base URL.
  353. * @returns {Promise<string[]>} A promise that resolves to an array of export names from the module.
  354. */
  355. declare function resolveModuleExportNames(id: string, options?: ResolveOptions): Promise<string[]>;
  356. /**
  357. * Represents the context of a CommonJS environment, providing node-like module resolution capabilities within a module.
  358. */
  359. interface CommonjsContext {
  360. /**
  361. * The absolute path to the current module file.
  362. */
  363. __filename: string;
  364. /**
  365. * The directory name of the current module.
  366. */
  367. __dirname: string;
  368. /**
  369. * A function to require modules as in CommonJS.
  370. */
  371. require: NodeRequire;
  372. }
  373. /**
  374. * Creates a CommonJS context for a given module URL, enabling `require`, `__filename` and `__dirname` support similar to Node.js.
  375. * This function dynamically generates a `require` function that is context-aware and bound to the location of the given module URL.
  376. *
  377. * @param {string} url - The URL of the module file to create a context for.
  378. * @returns {CommonjsContext} A context object containing `__filename`, `__dirname` and a custom `require` function. See {@link CommonjsContext}.
  379. */
  380. declare function createCommonJS(url: string): CommonjsContext;
  381. declare function interopDefault(sourceModule: any, opts?: {
  382. preferNamespace?: boolean;
  383. }): any;
  384. /**
  385. * Options for evaluating or transforming modules, extending resolution options with optional URL specifications.
  386. */
  387. interface EvaluateOptions extends ResolveOptions {
  388. /**
  389. * The URL of the module, which can be specified to override the URL resolved from the module identifier.
  390. * @optional
  391. */
  392. url?: string;
  393. }
  394. /**
  395. * Loads a module by resolving its identifier to a URL, fetching the module's code and evaluating it.
  396. *
  397. * @param {string} id - The identifier of the module to load.
  398. * @param {EvaluateOptions} options - Optional parameters to resolve and load the module. See {@link EvaluateOptions}.
  399. * @returns {Promise<any>} A promise to resolve to the evaluated module.
  400. * });
  401. */
  402. declare function loadModule(id: string, options?: EvaluateOptions): Promise<any>;
  403. /**
  404. * Evaluates JavaScript code as a module using a dynamic import from a data URL.
  405. *
  406. * @param {string} code - The code of the module to evaluate.
  407. * @param {EvaluateOptions} options - Includes the original URL of the module for better error mapping. See {@link EvaluateOptions}.
  408. * @returns {Promise<any>} A promise that resolves to the evaluated module or throws an error if the evaluation fails.
  409. */
  410. declare function evalModule(code: string, options?: EvaluateOptions): Promise<any>;
  411. /**
  412. * Transform module code to handle specific scenarios, such as converting JSON to a module or rewriting import.meta.url.
  413. *
  414. * @param {string} code - The code of the module to transform.
  415. * @param {EvaluateOptions} options - Options to control how the code is transformed. See {@link EvaluateOptions}.
  416. * @returns {Promise<string>} A promise that resolves to the transformed code.
  417. */
  418. declare function transformModule(code: string, options?: EvaluateOptions): Promise<string>;
  419. /**
  420. * Resolves all import URLs found within the provided code to their absolute URLs, based on the given options.
  421. *
  422. * @param {string} code - The code containing the import directives to resolve.
  423. * @param {EvaluateOptions} [options] - Options to use for resolving imports. See {@link EvaluateOptions}.
  424. * @returns {Promise<string>} A promise that resolves to the code, replacing import URLs with resolved URLs.
  425. */
  426. declare function resolveImports(code: string, options?: EvaluateOptions): Promise<string>;
  427. /**
  428. * Options for detecting syntax within a code string.
  429. */
  430. type DetectSyntaxOptions = {
  431. /**
  432. * Indicates whether comments should be stripped from the code before syntax checking.
  433. * @default false
  434. */
  435. stripComments?: boolean;
  436. };
  437. /**
  438. * Determines if a given code string contains ECMAScript module syntax.
  439. *
  440. * @param {string} code - The source code to analyse.
  441. * @param {DetectSyntaxOptions} opts - See {@link DetectSyntaxOptions}.
  442. * @returns {boolean} `true` if the code contains ESM syntax, otherwise `false`.
  443. */
  444. declare function hasESMSyntax(code: string, opts?: DetectSyntaxOptions): boolean;
  445. /**
  446. * Determines if a given string of code contains CommonJS syntax.
  447. *
  448. * @param {string} code - The source code to analyse.
  449. * @param {DetectSyntaxOptions} opts - See {@link DetectSyntaxOptions}.
  450. * @returns {boolean} `true` if the code contains CommonJS syntax, `false` otherwise.
  451. */
  452. declare function hasCJSSyntax(code: string, opts?: DetectSyntaxOptions): boolean;
  453. /**
  454. * Analyses the supplied code to determine if it contains ECMAScript module syntax, CommonJS syntax, or both.
  455. *
  456. * @param {string} code - The source code to analyse.
  457. * @param {DetectSyntaxOptions} opts - See {@link DetectSyntaxOptions}.
  458. * @returns {object} An object indicating the presence of ESM syntax (`hasESM`), CJS syntax (`hasCJS`) and whether both syntaxes are present (`isMixed`).
  459. */
  460. declare function detectSyntax(code: string, opts?: DetectSyntaxOptions): {
  461. hasESM: boolean;
  462. hasCJS: boolean;
  463. isMixed: boolean;
  464. };
  465. interface ValidNodeImportOptions extends ResolveOptions {
  466. /**
  467. * The contents of the import, which may be analyzed to see if it contains
  468. * CJS or ESM syntax as a last step in checking whether it is a valid import.
  469. */
  470. code?: string;
  471. /**
  472. * Protocols that are allowed as valid node imports.
  473. *
  474. * @default ['node', 'file', 'data']
  475. *
  476. */
  477. allowedProtocols?: Array<string>;
  478. /**
  479. * Whether to strip comments from the code before checking for ESM syntax.
  480. *
  481. * @default false
  482. */
  483. stripComments?: boolean;
  484. }
  485. /**
  486. * Validates whether a given identifier represents a valid node import, based on its protocol, file extension, and optionally its contents.
  487. *
  488. * @param {string} id - The identifier or URL of the import to validate.
  489. * @param {ValidNodeImportOptions} _options - Options for resolving and validating the import. See {@link ValidNodeImportOptions}.
  490. * @returns {Promise<boolean>} A promise that resolves to `true` if the import is valid, otherwise `false`.
  491. */
  492. declare function isValidNodeImport(id: string, _options?: ValidNodeImportOptions): Promise<boolean>;
  493. /**
  494. * Converts a file URL to a local file system path with normalized slashes.
  495. *
  496. * @param {string | URL} id - The file URL or local path to convert.
  497. * @returns {string} A normalized file system path.
  498. */
  499. declare function fileURLToPath(id: string | URL): string;
  500. /**
  501. * Converts a local file system path to a file URL.
  502. *
  503. * @param {string | URL} id - The file system path to convert.
  504. * @returns {string} The resulting file URL as a string.
  505. */
  506. declare function pathToFileURL(id: string | URL): string;
  507. /**
  508. * Sanitises a component of a URI by replacing invalid characters.
  509. *
  510. * @param {string} name - The URI component to sanitise.
  511. * @param {string} [replacement="_"] - The string to replace invalid characters with.
  512. * @returns {string} The sanitised URI component.
  513. */
  514. declare function sanitizeURIComponent(name?: string, replacement?: string): string;
  515. /**
  516. * Cleans a file path string by sanitising each component of the path.
  517. *
  518. * @param {string} filePath - The file path to sanitise.
  519. * @returns {string} The sanitised file path.
  520. */
  521. declare function sanitizeFilePath(filePath?: string): string;
  522. /**
  523. * Normalises a module identifier to ensure it has a protocol if missing, handling built-in modules and file paths.
  524. *
  525. * @param {string} id - The identifier to normalise.
  526. * @returns {string} The normalised identifier with the appropriate protocol.
  527. */
  528. declare function normalizeid(id: string): string;
  529. /**
  530. * Loads the contents of a file from a URL into a string.
  531. *
  532. * @param {string} url - The URL of the file to load.
  533. * @returns {Promise<string>} A promise that resolves to the content of the file.
  534. */
  535. declare function loadURL(url: string): Promise<string>;
  536. /**
  537. * Converts a string of code into a data URL that can be used for dynamic imports.
  538. *
  539. * @param {string} code - The string of code to convert.
  540. * @returns {string} The data URL containing the encoded code.
  541. */
  542. declare function toDataURL(code: string): string;
  543. /**
  544. * Checks if a module identifier matches a Node.js built-in module.
  545. *
  546. * @param {string} id - The identifier to check.
  547. * @returns {boolean} `true` if the identifier is a built-in module, otherwise `false`.
  548. */
  549. declare function isNodeBuiltin(id?: string): boolean;
  550. /**
  551. * Extracts the protocol portion of a given identifier string.
  552. *
  553. * @param {string} id - The identifier from which to extract the log.
  554. * @returns {string | undefined} The protocol part of the identifier, or undefined if no protocol is present.
  555. */
  556. declare function getProtocol(id: string): string | undefined;
  557. export { DYNAMIC_IMPORT_RE, ESM_STATIC_IMPORT_RE, EXPORT_DECAL_RE, EXPORT_DECAL_TYPE_RE, createCommonJS, createResolve, detectSyntax, evalModule, fileURLToPath, findDynamicImports, findExportNames, findExports, findStaticImports, findTypeExports, findTypeImports, getProtocol, hasCJSSyntax, hasESMSyntax, interopDefault, isNodeBuiltin, isValidNodeImport, loadModule, loadURL, lookupNodeModuleSubpath, normalizeid, parseNodeModulePath, parseStaticImport, parseTypeImport, pathToFileURL, resolve, resolveImports, resolveModuleExportNames, resolvePath, resolvePathSync, resolveSync, sanitizeFilePath, sanitizeURIComponent, toDataURL, transformModule };
  558. export type { CommonjsContext, DeclarationExport, DefaultExport, DetectSyntaxOptions, DynamicImport, ESMExport, ESMImport, EvaluateOptions, NamedExport, ParsedStaticImport, ResolveOptions, StaticImport, TypeImport, ValidNodeImportOptions };