1 | // Type definitions for @babel/core 7.20
|
2 | // Project: https://github.com/babel/babel/tree/master/packages/babel-core, https://babeljs.io
|
3 | // Definitions by: Troy Gerwien <https://github.com/yortus>
|
4 | // Marvin Hagemeister <https://github.com/marvinhagemeister>
|
5 | // Melvin Groenhoff <https://github.com/mgroenhoff>
|
6 | // Jessica Franco <https://github.com/Jessidhia>
|
7 | // Ifiok Jr. <https://github.com/ifiokjr>
|
8 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
9 | // Minimum TypeScript Version: 3.4
|
10 |
|
11 | import { GeneratorOptions } from '@babel/generator';
|
12 | import { ParserOptions } from '@babel/parser';
|
13 | import template from '@babel/template';
|
14 | import traverse, { Hub, NodePath, Scope, Visitor } from '@babel/traverse';
|
15 | import * as t from '@babel/types';
|
16 |
|
17 | export { ParserOptions, GeneratorOptions, t as types, template, traverse, NodePath, Visitor };
|
18 |
|
19 | export type Node = t.Node;
|
20 | export type ParseResult = ReturnType<typeof import('@babel/parser').parse>;
|
21 | export const version: string;
|
22 | export const DEFAULT_EXTENSIONS: ['.js', '.jsx', '.es6', '.es', '.mjs'];
|
23 |
|
24 | /**
|
25 | * Source map standard format as to revision 3
|
26 | * @see {@link https://sourcemaps.info/spec.html}
|
27 | * @see {@link https://github.com/mozilla/source-map/blob/HEAD/source-map.d.ts}
|
28 | */
|
29 | interface InputSourceMap {
|
30 | version: number;
|
31 | sources: string[];
|
32 | names: string[];
|
33 | sourceRoot?: string | undefined;
|
34 | sourcesContent?: string[] | undefined;
|
35 | mappings: string;
|
36 | file: string;
|
37 | }
|
38 |
|
39 | export interface TransformOptions {
|
40 | /**
|
41 | * Specify which assumptions it can make about your code, to better optimize the compilation result. **NOTE**: This replaces the various `loose` options in plugins in favor of
|
42 | * top-level options that can apply to multiple plugins
|
43 | *
|
44 | * @see https://babeljs.io/docs/en/assumptions
|
45 | */
|
46 | assumptions?: { [name: string]: boolean } | null | undefined;
|
47 |
|
48 | /**
|
49 | * Include the AST in the returned object
|
50 | *
|
51 | * Default: `false`
|
52 | */
|
53 | ast?: boolean | null | undefined;
|
54 |
|
55 | /**
|
56 | * Attach a comment after all non-user injected code
|
57 | *
|
58 | * Default: `null`
|
59 | */
|
60 | auxiliaryCommentAfter?: string | null | undefined;
|
61 |
|
62 | /**
|
63 | * Attach a comment before all non-user injected code
|
64 | *
|
65 | * Default: `null`
|
66 | */
|
67 | auxiliaryCommentBefore?: string | null | undefined;
|
68 |
|
69 | /**
|
70 | * Specify the "root" folder that defines the location to search for "babel.config.js", and the default folder to allow `.babelrc` files inside of.
|
71 | *
|
72 | * Default: `"."`
|
73 | */
|
74 | root?: string | null | undefined;
|
75 |
|
76 | /**
|
77 | * This option, combined with the "root" value, defines how Babel chooses its project root.
|
78 | * The different modes define different ways that Babel can process the "root" value to get
|
79 | * the final project root.
|
80 | *
|
81 | * @see https://babeljs.io/docs/en/next/options#rootmode
|
82 | */
|
83 | rootMode?: 'root' | 'upward' | 'upward-optional' | undefined;
|
84 |
|
85 | /**
|
86 | * The config file to load Babel's config from. Defaults to searching for "babel.config.js" inside the "root" folder. `false` will disable searching for config files.
|
87 | *
|
88 | * Default: `undefined`
|
89 | */
|
90 | configFile?: string | boolean | null | undefined;
|
91 |
|
92 | /**
|
93 | * Specify whether or not to use .babelrc and
|
94 | * .babelignore files.
|
95 | *
|
96 | * Default: `true`
|
97 | */
|
98 | babelrc?: boolean | null | undefined;
|
99 |
|
100 | /**
|
101 | * Specify which packages should be search for .babelrc files when they are being compiled. `true` to always search, or a path string or an array of paths to packages to search
|
102 | * inside of. Defaults to only searching the "root" package.
|
103 | *
|
104 | * Default: `(root)`
|
105 | */
|
106 | babelrcRoots?: boolean | MatchPattern | MatchPattern[] | null | undefined;
|
107 |
|
108 | /**
|
109 | * Toggles whether or not browserslist config sources are used, which includes searching for any browserslist files or referencing the browserslist key inside package.json.
|
110 | * This is useful for projects that use a browserslist config for files that won't be compiled with Babel.
|
111 | *
|
112 | * If a string is specified, it must represent the path of a browserslist configuration file. Relative paths are resolved relative to the configuration file which specifies
|
113 | * this option, or to `cwd` when it's passed as part of the programmatic options.
|
114 | *
|
115 | * Default: `true`
|
116 | */
|
117 | browserslistConfigFile?: boolean | null | undefined;
|
118 |
|
119 | /**
|
120 | * The Browserslist environment to use.
|
121 | *
|
122 | * Default: `undefined`
|
123 | */
|
124 | browserslistEnv?: string | null | undefined;
|
125 |
|
126 | /**
|
127 | * By default `babel.transformFromAst` will clone the input AST to avoid mutations.
|
128 | * Specifying `cloneInputAst: false` can improve parsing performance if the input AST is not used elsewhere.
|
129 | *
|
130 | * Default: `true`
|
131 | */
|
132 | cloneInputAst?: boolean | null | undefined;
|
133 |
|
134 | /**
|
135 | * Defaults to environment variable `BABEL_ENV` if set, or else `NODE_ENV` if set, or else it defaults to `"development"`
|
136 | *
|
137 | * Default: env vars
|
138 | */
|
139 | envName?: string | undefined;
|
140 |
|
141 | /**
|
142 | * If any of patterns match, the current configuration object is considered inactive and is ignored during config processing.
|
143 | */
|
144 | exclude?: MatchPattern | MatchPattern[] | undefined;
|
145 |
|
146 | /**
|
147 | * Enable code generation
|
148 | *
|
149 | * Default: `true`
|
150 | */
|
151 | code?: boolean | null | undefined;
|
152 |
|
153 | /**
|
154 | * Output comments in generated output
|
155 | *
|
156 | * Default: `true`
|
157 | */
|
158 | comments?: boolean | null | undefined;
|
159 |
|
160 | /**
|
161 | * Do not include superfluous whitespace characters and line terminators. When set to `"auto"` compact is set to `true` on input sizes of >500KB
|
162 | *
|
163 | * Default: `"auto"`
|
164 | */
|
165 | compact?: boolean | 'auto' | null | undefined;
|
166 |
|
167 | /**
|
168 | * The working directory that Babel's programmatic options are loaded relative to.
|
169 | *
|
170 | * Default: `"."`
|
171 | */
|
172 | cwd?: string | null | undefined;
|
173 |
|
174 | /**
|
175 | * Utilities may pass a caller object to identify themselves to Babel and
|
176 | * pass capability-related flags for use by configs, presets and plugins.
|
177 | *
|
178 | * @see https://babeljs.io/docs/en/next/options#caller
|
179 | */
|
180 | caller?: TransformCaller | undefined;
|
181 |
|
182 | /**
|
183 | * This is an object of keys that represent different environments. For example, you may have: `{ env: { production: { \/* specific options *\/ } } }`
|
184 | * which will use those options when the `envName` is `production`
|
185 | *
|
186 | * Default: `{}`
|
187 | */
|
188 | env?: { [index: string]: TransformOptions | null | undefined } | null | undefined;
|
189 |
|
190 | /**
|
191 | * A path to a `.babelrc` file to extend
|
192 | *
|
193 | * Default: `null`
|
194 | */
|
195 | extends?: string | null | undefined;
|
196 |
|
197 | /**
|
198 | * Filename for use in errors etc
|
199 | *
|
200 | * Default: `"unknown"`
|
201 | */
|
202 | filename?: string | null | undefined;
|
203 |
|
204 | /**
|
205 | * Filename relative to `sourceRoot`
|
206 | *
|
207 | * Default: `(filename)`
|
208 | */
|
209 | filenameRelative?: string | null | undefined;
|
210 |
|
211 | /**
|
212 | * An object containing the options to be passed down to the babel code generator, @babel/generator
|
213 | *
|
214 | * Default: `{}`
|
215 | */
|
216 | generatorOpts?: GeneratorOptions | null | undefined;
|
217 |
|
218 | /**
|
219 | * Specify a custom callback to generate a module id with. Called as `getModuleId(moduleName)`. If falsy value is returned then the generated module id is used
|
220 | *
|
221 | * Default: `null`
|
222 | */
|
223 | getModuleId?: ((moduleName: string) => string | null | undefined) | null | undefined;
|
224 |
|
225 | /**
|
226 | * ANSI highlight syntax error code frames
|
227 | *
|
228 | * Default: `true`
|
229 | */
|
230 | highlightCode?: boolean | null | undefined;
|
231 |
|
232 | /**
|
233 | * Opposite to the `only` option. `ignore` is disregarded if `only` is specified
|
234 | *
|
235 | * Default: `null`
|
236 | */
|
237 | ignore?: MatchPattern[] | null | undefined;
|
238 |
|
239 | /**
|
240 | * This option is a synonym for "test"
|
241 | */
|
242 | include?: MatchPattern | MatchPattern[] | undefined;
|
243 |
|
244 | /**
|
245 | * A source map object that the output source map will be based on
|
246 | *
|
247 | * Default: `null`
|
248 | */
|
249 | inputSourceMap?: InputSourceMap | null | undefined;
|
250 |
|
251 | /**
|
252 | * Should the output be minified (not printing last semicolons in blocks, printing literal string values instead of escaped ones, stripping `()` from `new` when safe)
|
253 | *
|
254 | * Default: `false`
|
255 | */
|
256 | minified?: boolean | null | undefined;
|
257 |
|
258 | /**
|
259 | * Specify a custom name for module ids
|
260 | *
|
261 | * Default: `null`
|
262 | */
|
263 | moduleId?: string | null | undefined;
|
264 |
|
265 | /**
|
266 | * If truthy, insert an explicit id for modules. By default, all modules are anonymous. (Not available for `common` modules)
|
267 | *
|
268 | * Default: `false`
|
269 | */
|
270 | moduleIds?: boolean | null | undefined;
|
271 |
|
272 | /**
|
273 | * Optional prefix for the AMD module formatter that will be prepend to the filename on module definitions
|
274 | *
|
275 | * Default: `(sourceRoot)`
|
276 | */
|
277 | moduleRoot?: string | null | undefined;
|
278 |
|
279 | /**
|
280 | * A glob, regex, or mixed array of both, matching paths to **only** compile. Can also be an array of arrays containing paths to explicitly match. When attempting to compile
|
281 | * a non-matching file it's returned verbatim
|
282 | *
|
283 | * Default: `null`
|
284 | */
|
285 | only?: MatchPattern[] | null | undefined;
|
286 |
|
287 | /**
|
288 | * Allows users to provide an array of options that will be merged into the current configuration one at a time.
|
289 | * This feature is best used alongside the "test"/"include"/"exclude" options to provide conditions for which an override should apply
|
290 | */
|
291 | overrides?: TransformOptions[] | undefined;
|
292 |
|
293 | /**
|
294 | * An object containing the options to be passed down to the babel parser, @babel/parser
|
295 | *
|
296 | * Default: `{}`
|
297 | */
|
298 | parserOpts?: ParserOptions | null | undefined;
|
299 |
|
300 | /**
|
301 | * List of plugins to load and use
|
302 | *
|
303 | * Default: `[]`
|
304 | */
|
305 | plugins?: PluginItem[] | null | undefined;
|
306 |
|
307 | /**
|
308 | * List of presets (a set of plugins) to load and use
|
309 | *
|
310 | * Default: `[]`
|
311 | */
|
312 | presets?: PluginItem[] | null | undefined;
|
313 |
|
314 | /**
|
315 | * Retain line numbers. This will lead to wacky code but is handy for scenarios where you can't use source maps. (**NOTE**: This will not retain the columns)
|
316 | *
|
317 | * Default: `false`
|
318 | */
|
319 | retainLines?: boolean | null | undefined;
|
320 |
|
321 | /**
|
322 | * An optional callback that controls whether a comment should be output or not. Called as `shouldPrintComment(commentContents)`. **NOTE**: This overrides the `comment` option when used
|
323 | *
|
324 | * Default: `null`
|
325 | */
|
326 | shouldPrintComment?: ((commentContents: string) => boolean) | null | undefined;
|
327 |
|
328 | /**
|
329 | * Set `sources[0]` on returned source map
|
330 | *
|
331 | * Default: `(filenameRelative)`
|
332 | */
|
333 | sourceFileName?: string | null | undefined;
|
334 |
|
335 | /**
|
336 | * If truthy, adds a `map` property to returned output. If set to `"inline"`, a comment with a sourceMappingURL directive is added to the bottom of the returned code. If set to `"both"`
|
337 | * then a `map` property is returned as well as a source map comment appended. **This does not emit sourcemap files by itself!**
|
338 | *
|
339 | * Default: `false`
|
340 | */
|
341 | sourceMaps?: boolean | 'inline' | 'both' | null | undefined;
|
342 |
|
343 | /**
|
344 | * The root from which all sources are relative
|
345 | *
|
346 | * Default: `(moduleRoot)`
|
347 | */
|
348 | sourceRoot?: string | null | undefined;
|
349 |
|
350 | /**
|
351 | * Indicate the mode the code should be parsed in. Can be one of "script", "module", or "unambiguous". `"unambiguous"` will make Babel attempt to guess, based on the presence of ES6
|
352 | * `import` or `export` statements. Files with ES6 `import`s and `export`s are considered `"module"` and are otherwise `"script"`.
|
353 | *
|
354 | * Default: `("module")`
|
355 | */
|
356 | sourceType?: 'script' | 'module' | 'unambiguous' | null | undefined;
|
357 |
|
358 | /**
|
359 | * If all patterns fail to match, the current configuration object is considered inactive and is ignored during config processing.
|
360 | */
|
361 | test?: MatchPattern | MatchPattern[] | undefined;
|
362 |
|
363 | /**
|
364 | * Describes the environments you support/target for your project.
|
365 | * This can either be a [browserslist-compatible](https://github.com/ai/browserslist) query (with [caveats](https://babeljs.io/docs/en/babel-preset-env#ineffective-browserslist-queries))
|
366 | *
|
367 | * Default: `{}`
|
368 | */
|
369 | targets?:
|
370 | | string
|
371 | | string[]
|
372 | | {
|
373 | esmodules?: boolean;
|
374 | node?: Omit<string, 'current'> | 'current' | true;
|
375 | safari?: Omit<string, 'tp'> | 'tp';
|
376 | browsers?: string | string[];
|
377 | android?: string;
|
378 | chrome?: string;
|
379 | deno?: string;
|
380 | edge?: string;
|
381 | electron?: string;
|
382 | firefox?: string;
|
383 | ie?: string;
|
384 | ios?: string;
|
385 | opera?: string;
|
386 | rhino?: string;
|
387 | samsung?: string;
|
388 | };
|
389 |
|
390 | /**
|
391 | * An optional callback that can be used to wrap visitor methods. **NOTE**: This is useful for things like introspection, and not really needed for implementing anything. Called as
|
392 | * `wrapPluginVisitorMethod(pluginAlias, visitorType, callback)`.
|
393 | */
|
394 | wrapPluginVisitorMethod?:
|
395 | | ((
|
396 | pluginAlias: string,
|
397 | visitorType: 'enter' | 'exit',
|
398 | callback: (path: NodePath, state: any) => void,
|
399 | ) => (path: NodePath, state: any) => void)
|
400 | | null
|
401 | | undefined;
|
402 | }
|
403 |
|
404 | export interface TransformCaller {
|
405 | // the only required property
|
406 | name: string;
|
407 | // e.g. set to true by `babel-loader` and false by `babel-jest`
|
408 | supportsStaticESM?: boolean | undefined;
|
409 | supportsDynamicImport?: boolean | undefined;
|
410 | supportsExportNamespaceFrom?: boolean | undefined;
|
411 | supportsTopLevelAwait?: boolean | undefined;
|
412 | // augment this with a "declare module '@babel/core' { ... }" if you need more keys
|
413 | }
|
414 |
|
415 | export type FileResultCallback = (err: Error | null, result: BabelFileResult | null) => any;
|
416 |
|
417 | export interface MatchPatternContext {
|
418 | envName: string;
|
419 | dirname: string;
|
420 | caller: TransformCaller | undefined;
|
421 | }
|
422 | export type MatchPattern = string | RegExp | ((filename: string | undefined, context: MatchPatternContext) => boolean);
|
423 |
|
424 | /**
|
425 | * Transforms the passed in code. Calling a callback with an object with the generated code, source map, and AST.
|
426 | */
|
427 | export function transform(code: string, callback: FileResultCallback): void;
|
428 |
|
429 | /**
|
430 | * Transforms the passed in code. Calling a callback with an object with the generated code, source map, and AST.
|
431 | */
|
432 | export function transform(code: string, opts: TransformOptions | undefined, callback: FileResultCallback): void;
|
433 |
|
434 | /**
|
435 | * Here for backward-compatibility. Ideally use `transformSync` if you want a synchronous API.
|
436 | */
|
437 | export function transform(code: string, opts?: TransformOptions): BabelFileResult | null;
|
438 |
|
439 | /**
|
440 | * Transforms the passed in code. Returning an object with the generated code, source map, and AST.
|
441 | */
|
442 | export function transformSync(code: string, opts?: TransformOptions): BabelFileResult | null;
|
443 |
|
444 | /**
|
445 | * Transforms the passed in code. Calling a callback with an object with the generated code, source map, and AST.
|
446 | */
|
447 | export function transformAsync(code: string, opts?: TransformOptions): Promise<BabelFileResult | null>;
|
448 |
|
449 | /**
|
450 | * Asynchronously transforms the entire contents of a file.
|
451 | */
|
452 | export function transformFile(filename: string, callback: FileResultCallback): void;
|
453 |
|
454 | /**
|
455 | * Asynchronously transforms the entire contents of a file.
|
456 | */
|
457 | export function transformFile(filename: string, opts: TransformOptions | undefined, callback: FileResultCallback): void;
|
458 |
|
459 | /**
|
460 | * Synchronous version of `babel.transformFile`. Returns the transformed contents of the `filename`.
|
461 | */
|
462 | export function transformFileSync(filename: string, opts?: TransformOptions): BabelFileResult | null;
|
463 |
|
464 | /**
|
465 | * Asynchronously transforms the entire contents of a file.
|
466 | */
|
467 | export function transformFileAsync(filename: string, opts?: TransformOptions): Promise<BabelFileResult | null>;
|
468 |
|
469 | /**
|
470 | * Given an AST, transform it.
|
471 | */
|
472 | export function transformFromAst(ast: Node, code: string | undefined, callback: FileResultCallback): void;
|
473 |
|
474 | /**
|
475 | * Given an AST, transform it.
|
476 | */
|
477 | export function transformFromAst(
|
478 | ast: Node,
|
479 | code: string | undefined,
|
480 | opts: TransformOptions | undefined,
|
481 | callback: FileResultCallback,
|
482 | ): void;
|
483 |
|
484 | /**
|
485 | * Here for backward-compatibility. Ideally use ".transformSync" if you want a synchronous API.
|
486 | */
|
487 | export function transformFromAstSync(ast: Node, code?: string, opts?: TransformOptions): BabelFileResult | null;
|
488 |
|
489 | /**
|
490 | * Given an AST, transform it.
|
491 | */
|
492 | export function transformFromAstAsync(
|
493 | ast: Node,
|
494 | code?: string,
|
495 | opts?: TransformOptions,
|
496 | ): Promise<BabelFileResult | null>;
|
497 |
|
498 | // A babel plugin is a simple function which must return an object matching
|
499 | // the following interface. Babel will throw if it finds unknown properties.
|
500 | // The list of allowed plugin keys is here:
|
501 | // https://github.com/babel/babel/blob/4e50b2d9d9c376cee7a2cbf56553fe5b982ea53c/packages/babel-core/src/config/option-manager.js#L71
|
502 | export interface PluginObj<S = PluginPass> {
|
503 | name?: string | undefined;
|
504 | manipulateOptions?(opts: any, parserOpts: any): void;
|
505 | pre?(this: S, file: BabelFile): void;
|
506 | visitor: Visitor<S>;
|
507 | post?(this: S, file: BabelFile): void;
|
508 | inherits?: any;
|
509 | }
|
510 |
|
511 | export interface BabelFile {
|
512 | ast: t.File;
|
513 | opts: TransformOptions;
|
514 | hub: Hub;
|
515 | metadata: object;
|
516 | path: NodePath<t.Program>;
|
517 | scope: Scope;
|
518 | inputMap: object | null;
|
519 | code: string;
|
520 | }
|
521 |
|
522 | export interface PluginPass {
|
523 | file: BabelFile;
|
524 | key: string;
|
525 | opts: object;
|
526 | cwd: string;
|
527 | filename: string | undefined;
|
528 | get(key: unknown): any;
|
529 | set(key: unknown, value: unknown): void;
|
530 | [key: string]: unknown;
|
531 | }
|
532 |
|
533 | export interface BabelFileResult {
|
534 | ast?: t.File | null | undefined;
|
535 | code?: string | null | undefined;
|
536 | ignored?: boolean | undefined;
|
537 | map?:
|
538 | | {
|
539 | version: number;
|
540 | sources: string[];
|
541 | names: string[];
|
542 | sourceRoot?: string | undefined;
|
543 | sourcesContent?: string[] | undefined;
|
544 | mappings: string;
|
545 | file: string;
|
546 | }
|
547 | | null
|
548 | | undefined;
|
549 | metadata?: BabelFileMetadata | undefined;
|
550 | }
|
551 |
|
552 | export interface BabelFileMetadata {
|
553 | usedHelpers: string[];
|
554 | marked: Array<{
|
555 | type: string;
|
556 | message: string;
|
557 | loc: object;
|
558 | }>;
|
559 | modules: BabelFileModulesMetadata;
|
560 | }
|
561 |
|
562 | export interface BabelFileModulesMetadata {
|
563 | imports: object[];
|
564 | exports: {
|
565 | exported: object[];
|
566 | specifiers: object[];
|
567 | };
|
568 | }
|
569 |
|
570 | export type FileParseCallback = (err: Error | null, result: ParseResult | null) => any;
|
571 |
|
572 | /**
|
573 | * Given some code, parse it using Babel's standard behavior.
|
574 | * Referenced presets and plugins will be loaded such that optional syntax plugins are automatically enabled.
|
575 | */
|
576 | export function parse(code: string, callback: FileParseCallback): void;
|
577 |
|
578 | /**
|
579 | * Given some code, parse it using Babel's standard behavior.
|
580 | * Referenced presets and plugins will be loaded such that optional syntax plugins are automatically enabled.
|
581 | */
|
582 | export function parse(code: string, options: TransformOptions | undefined, callback: FileParseCallback): void;
|
583 |
|
584 | /**
|
585 | * Given some code, parse it using Babel's standard behavior.
|
586 | * Referenced presets and plugins will be loaded such that optional syntax plugins are automatically enabled.
|
587 | */
|
588 | export function parse(code: string, options?: TransformOptions): ParseResult | null;
|
589 |
|
590 | /**
|
591 | * Given some code, parse it using Babel's standard behavior.
|
592 | * Referenced presets and plugins will be loaded such that optional syntax plugins are automatically enabled.
|
593 | */
|
594 | export function parseSync(code: string, options?: TransformOptions): ParseResult | null;
|
595 |
|
596 | /**
|
597 | * Given some code, parse it using Babel's standard behavior.
|
598 | * Referenced presets and plugins will be loaded such that optional syntax plugins are automatically enabled.
|
599 | */
|
600 | export function parseAsync(code: string, options?: TransformOptions): Promise<ParseResult | null>;
|
601 |
|
602 | /**
|
603 | * Resolve Babel's options fully, resulting in an options object where:
|
604 | *
|
605 | * * opts.plugins is a full list of Plugin instances.
|
606 | * * opts.presets is empty and all presets are flattened into opts.
|
607 | * * It can be safely passed back to Babel. Fields like babelrc have been set to false so that later calls to Babel
|
608 | * will not make a second attempt to load config files.
|
609 | *
|
610 | * Plugin instances aren't meant to be manipulated directly, but often callers will serialize this opts to JSON to
|
611 | * use it as a cache key representing the options Babel has received. Caching on this isn't 100% guaranteed to
|
612 | * invalidate properly, but it is the best we have at the moment.
|
613 | */
|
614 | export function loadOptions(options?: TransformOptions): object | null;
|
615 |
|
616 | /**
|
617 | * To allow systems to easily manipulate and validate a user's config, this function resolves the plugins and
|
618 | * presets and proceeds no further. The expectation is that callers will take the config's .options, manipulate it
|
619 | * as then see fit and pass it back to Babel again.
|
620 | *
|
621 | * * `babelrc: string | void` - The path of the `.babelrc` file, if there was one.
|
622 | * * `babelignore: string | void` - The path of the `.babelignore` file, if there was one.
|
623 | * * `options: ValidatedOptions` - The partially resolved options, which can be manipulated and passed back
|
624 | * to Babel again.
|
625 | * * `plugins: Array<ConfigItem>` - See below.
|
626 | * * `presets: Array<ConfigItem>` - See below.
|
627 | * * It can be safely passed back to Babel. Fields like `babelrc` have been set to false so that later calls to
|
628 | * Babel will not make a second attempt to load config files.
|
629 | *
|
630 | * `ConfigItem` instances expose properties to introspect the values, but each item should be treated as
|
631 | * immutable. If changes are desired, the item should be removed from the list and replaced with either a normal
|
632 | * Babel config value, or with a replacement item created by `babel.createConfigItem`. See that function for
|
633 | * information about `ConfigItem` fields.
|
634 | */
|
635 | export function loadPartialConfig(options?: TransformOptions): Readonly<PartialConfig> | null;
|
636 | export function loadPartialConfigAsync(options?: TransformOptions): Promise<Readonly<PartialConfig> | null>;
|
637 |
|
638 | export interface PartialConfig {
|
639 | options: TransformOptions;
|
640 | babelrc?: string | undefined;
|
641 | babelignore?: string | undefined;
|
642 | config?: string | undefined;
|
643 | hasFilesystemConfig: () => boolean;
|
644 | }
|
645 |
|
646 | export interface ConfigItem {
|
647 | /**
|
648 | * The name that the user gave the plugin instance, e.g. `plugins: [ ['env', {}, 'my-env'] ]`
|
649 | */
|
650 | name?: string | undefined;
|
651 |
|
652 | /**
|
653 | * The resolved value of the plugin.
|
654 | */
|
655 | value: object | ((...args: any[]) => any);
|
656 |
|
657 | /**
|
658 | * The options object passed to the plugin.
|
659 | */
|
660 | options?: object | false | undefined;
|
661 |
|
662 | /**
|
663 | * The path that the options are relative to.
|
664 | */
|
665 | dirname: string;
|
666 |
|
667 | /**
|
668 | * Information about the plugin's file, if Babel knows it.
|
669 | * *
|
670 | */
|
671 | file?:
|
672 | | {
|
673 | /**
|
674 | * The file that the user requested, e.g. `"@babel/env"`
|
675 | */
|
676 | request: string;
|
677 |
|
678 | /**
|
679 | * The full path of the resolved file, e.g. `"/tmp/node_modules/@babel/preset-env/lib/index.js"`
|
680 | */
|
681 | resolved: string;
|
682 | }
|
683 | | null
|
684 | | undefined;
|
685 | }
|
686 |
|
687 | export type PluginOptions = object | undefined | false;
|
688 |
|
689 | export type PluginTarget = string | object | ((...args: any[]) => any);
|
690 |
|
691 | export type PluginItem =
|
692 | | ConfigItem
|
693 | | PluginObj<any>
|
694 | | PluginTarget
|
695 | | [PluginTarget, PluginOptions]
|
696 | | [PluginTarget, PluginOptions, string | undefined];
|
697 |
|
698 | export function resolvePlugin(name: string, dirname: string): string | null;
|
699 | export function resolvePreset(name: string, dirname: string): string | null;
|
700 |
|
701 | export interface CreateConfigItemOptions {
|
702 | dirname?: string | undefined;
|
703 | type?: 'preset' | 'plugin' | undefined;
|
704 | }
|
705 |
|
706 | /**
|
707 | * Allows build tooling to create and cache config items up front. If this function is called multiple times for a
|
708 | * given plugin, Babel will call the plugin's function itself multiple times. If you have a clear set of expected
|
709 | * plugins and presets to inject, pre-constructing the config items would be recommended.
|
710 | */
|
711 | export function createConfigItem(
|
712 | value: PluginTarget | [PluginTarget, PluginOptions] | [PluginTarget, PluginOptions, string | undefined],
|
713 | options?: CreateConfigItemOptions,
|
714 | ): ConfigItem;
|
715 |
|
716 | // NOTE: the documentation says the ConfigAPI also exposes @babel/core's exports, but it actually doesn't
|
717 | /**
|
718 | * @see https://babeljs.io/docs/en/next/config-files#config-function-api
|
719 | */
|
720 | export interface ConfigAPI {
|
721 | /**
|
722 | * The version string for the Babel version that is loading the config file.
|
723 | *
|
724 | * @see https://babeljs.io/docs/en/next/config-files#apiversion
|
725 | */
|
726 | version: string;
|
727 | /**
|
728 | * @see https://babeljs.io/docs/en/next/config-files#apicache
|
729 | */
|
730 | cache: SimpleCacheConfigurator;
|
731 | /**
|
732 | * @see https://babeljs.io/docs/en/next/config-files#apienv
|
733 | */
|
734 | env: EnvFunction;
|
735 | // undocumented; currently hardcoded to return 'false'
|
736 | // async(): boolean
|
737 | /**
|
738 | * This API is used as a way to access the `caller` data that has been passed to Babel.
|
739 | * Since many instances of Babel may be running in the same process with different `caller` values,
|
740 | * this API is designed to automatically configure `api.cache`, the same way `api.env()` does.
|
741 | *
|
742 | * The `caller` value is available as the first parameter of the callback function.
|
743 | * It is best used with something like this to toggle configuration behavior
|
744 | * based on a specific environment:
|
745 | *
|
746 | * @example
|
747 | * function isBabelRegister(caller?: { name: string }) {
|
748 | * return !!(caller && caller.name === "@babel/register")
|
749 | * }
|
750 | * api.caller(isBabelRegister)
|
751 | *
|
752 | * @see https://babeljs.io/docs/en/next/config-files#apicallercb
|
753 | */
|
754 | caller<T extends SimpleCacheKey>(callerCallback: (caller: TransformOptions['caller']) => T): T;
|
755 | /**
|
756 | * While `api.version` can be useful in general, it's sometimes nice to just declare your version.
|
757 | * This API exposes a simple way to do that with:
|
758 | *
|
759 | * @example
|
760 | * api.assertVersion(7) // major version only
|
761 | * api.assertVersion("^7.2")
|
762 | *
|
763 | * @see https://babeljs.io/docs/en/next/config-files#apiassertversionrange
|
764 | */
|
765 | assertVersion(versionRange: number | string): boolean;
|
766 | // NOTE: this is an undocumented reexport from "@babel/parser" but it's missing from its types
|
767 | // tokTypes: typeof tokTypes
|
768 | }
|
769 |
|
770 | /**
|
771 | * JS configs are great because they can compute a config on the fly,
|
772 | * but the downside there is that it makes caching harder.
|
773 | * Babel wants to avoid re-executing the config function every time a file is compiled,
|
774 | * because then it would also need to re-execute any plugin and preset functions
|
775 | * referenced in that config.
|
776 | *
|
777 | * To avoid this, Babel expects users of config functions to tell it how to manage caching
|
778 | * within a config file.
|
779 | *
|
780 | * @see https://babeljs.io/docs/en/next/config-files#apicache
|
781 | */
|
782 | export interface SimpleCacheConfigurator {
|
783 | // there is an undocumented call signature that is a shorthand for forever()/never()/using().
|
784 | // (ever: boolean): void
|
785 | // <T extends SimpleCacheKey>(callback: CacheCallback<T>): T
|
786 | /**
|
787 | * Permacache the computed config and never call the function again.
|
788 | */
|
789 | forever(): void;
|
790 | /**
|
791 | * Do not cache this config, and re-execute the function every time.
|
792 | */
|
793 | never(): void;
|
794 | /**
|
795 | * Any time the using callback returns a value other than the one that was expected,
|
796 | * the overall config function will be called again and a new entry will be added to the cache.
|
797 | *
|
798 | * @example
|
799 | * api.cache.using(() => process.env.NODE_ENV)
|
800 | */
|
801 | using<T extends SimpleCacheKey>(callback: SimpleCacheCallback<T>): T;
|
802 | /**
|
803 | * Any time the using callback returns a value other than the one that was expected,
|
804 | * the overall config function will be called again and all entries in the cache will
|
805 | * be replaced with the result.
|
806 | *
|
807 | * @example
|
808 | * api.cache.invalidate(() => process.env.NODE_ENV)
|
809 | */
|
810 | invalidate<T extends SimpleCacheKey>(callback: SimpleCacheCallback<T>): T;
|
811 | }
|
812 |
|
813 | // https://github.com/babel/babel/blob/v7.3.3/packages/babel-core/src/config/caching.js#L231
|
814 | export type SimpleCacheKey = string | boolean | number | null | undefined;
|
815 | export type SimpleCacheCallback<T extends SimpleCacheKey> = () => T;
|
816 |
|
817 | /**
|
818 | * Since `NODE_ENV` is a fairly common way to toggle behavior, Babel also includes an API function
|
819 | * meant specifically for that. This API is used as a quick way to check the `"envName"` that Babel
|
820 | * was loaded with, which takes `NODE_ENV` into account if no other overriding environment is set.
|
821 | *
|
822 | * @see https://babeljs.io/docs/en/next/config-files#apienv
|
823 | */
|
824 | export interface EnvFunction {
|
825 | /**
|
826 | * @returns the current `envName` string
|
827 | */
|
828 | (): string;
|
829 | /**
|
830 | * @returns `true` if the `envName` is `===` any of the given strings
|
831 | */
|
832 | (envName: string | ReadonlyArray<string>): boolean;
|
833 | // the official documentation is misleading for this one...
|
834 | // this just passes the callback to `cache.using` but with an additional argument.
|
835 | // it returns its result instead of necessarily returning a boolean.
|
836 | <T extends SimpleCacheKey>(envCallback: (envName: NonNullable<TransformOptions['envName']>) => T): T;
|
837 | }
|
838 |
|
839 | export type ConfigFunction = (api: ConfigAPI) => TransformOptions;
|
840 |
|
841 | export as namespace babel;
|
842 |
|
\ | No newline at end of file |