diff --git a/types/babel__core/babel__core-tests.ts b/types/babel__core/babel__core-tests.ts index ba51ac21be..b44e45c605 100644 --- a/types/babel__core/babel__core-tests.ts +++ b/types/babel__core/babel__core-tests.ts @@ -39,3 +39,59 @@ babel.transformFromAstAsync(parsedAst!, sourceCode, options).then(transformFromA const { code, map, ast } = transformFromAstAsyncResult!; const { body } = ast!.program; }); + +function checkOptions(_options: babel.TransformOptions) {} +function checkConfigFunction(_config: babel.ConfigFunction) {} + +checkOptions({ envName: 'banana' }); +// babel uses object destructuring default to provide the envName fallback so null is not allowed +// $ExpectError +checkOptions({ envName: null }); +checkOptions({ caller: { name: '@babel/register' } }); +checkOptions({ caller: { name: 'babel-jest', supportsStaticESM: false } }); +// don't add an index signature; users should augment the interface instead if they need to +// $ExpectError +checkOptions({ caller: { name: '', tomato: true } }); +checkOptions({ rootMode: 'upward-optional' }); +// $ExpectError +checkOptions({ rootMode: 'potato' }); + +// $ExpectError +checkConfigFunction(() => {}); +// you technically can do that though you probably shouldn't +checkConfigFunction(() => ({})); +checkConfigFunction(api => { + api.assertVersion(7); + api.assertVersion("^7.2"); + + api.cache.forever(); + api.cache.never(); + api.cache.using(() => true); + api.cache.using(() => 1); + api.cache.using(() => '1'); + api.cache.using(() => null); + api.cache.using(() => undefined); + // $ExpectError + api.cache.using(() => ({})); + api.cache.invalidate(() => 2); + + // $ExpectType string + api.env(); + + api.env('development'); + api.env(['production', 'test']); + // $ExpectType 42 + api.env(name => 42); + + // $ExpectType string + api.version; + + return { + shouldPrintComment(comment) { + // $ExpectType string + comment; + + return true; + } + }; +}); diff --git a/types/babel__core/index.d.ts b/types/babel__core/index.d.ts index 66501d24db..3875d40d71 100644 --- a/types/babel__core/index.d.ts +++ b/types/babel__core/index.d.ts @@ -1,8 +1,9 @@ -// Type definitions for @babel/core 7.0 +// Type definitions for @babel/core 7.1 // Project: https://github.com/babel/babel/tree/master/packages/babel-core, https://babeljs.io // Definitions by: Troy Gerwien // Marvin Hagemeister // Melvin Groenhoff +// Jessica Franco // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.9 @@ -54,6 +55,15 @@ export interface TransformOptions { */ root?: string | null; + /** + * This option, combined with the "root" value, defines how Babel chooses its project root. + * The different modes define different ways that Babel can process the "root" value to get + * the final project root. + * + * @see https://babeljs.io/docs/en/next/options#rootmode + */ + rootMode?: 'root' | 'upward' | 'upward-optional'; + /** * 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. * @@ -82,7 +92,7 @@ export interface TransformOptions { * * Default: env vars */ - envName?: string | null; + envName?: string; /** * Enable code generation @@ -112,6 +122,14 @@ export interface TransformOptions { */ cwd?: string | null; + /** + * Utilities may pass a caller object to identify themselves to Babel and + * pass capability-related flags for use by configs, presets and plugins. + * + * @see https://babeljs.io/docs/en/next/options#caller + */ + caller?: TransformCaller; + /** * This is an object of keys that represent different environments. For example, you may have: `{ env: { production: { \/* specific options *\/ } } }` * which will use those options when the `envName` is `production` @@ -284,6 +302,14 @@ export interface TransformOptions { wrapPluginVisitorMethod?: ((pluginAlias: string, visitorType: "enter" | "exit", callback: (path: NodePath, state: any) => void) => (path: NodePath, state: any) => void) | null; } +export interface TransformCaller { + // the only required property + name: string; + // e.g. set to true by `babel-loader` and false by `babel-jest` + supportsStaticESM?: boolean; + // augment this with a "declare module '@babel/core' { ... }" if you need more keys +} + export type FileResultCallback = (err: Error | null, result: BabelFileResult | null) => any; /** @@ -528,4 +554,129 @@ export interface CreateConfigItemOptions { */ export function createConfigItem(value: PluginTarget | [PluginTarget, PluginOptions] | [PluginTarget, PluginOptions, string | undefined], options?: CreateConfigItemOptions): ConfigItem; +// NOTE: the documentation says the ConfigAPI also exposes @babel/core's exports, but it actually doesn't +/** + * @see https://babeljs.io/docs/en/next/config-files#config-function-api + */ +export interface ConfigAPI { + /** + * The version string for the Babel version that is loading the config file. + * + * @see https://babeljs.io/docs/en/next/config-files#apiversion + */ + version: string; + /** + * @see https://babeljs.io/docs/en/next/config-files#apicache + */ + cache: SimpleCacheConfigurator; + /** + * @see https://babeljs.io/docs/en/next/config-files#apienv + */ + env: EnvFunction; + // undocumented; currently hardcoded to return 'false' + // async(): boolean + /** + * This API is used as a way to access the `caller` data that has been passed to Babel. + * Since many instances of Babel may be running in the same process with different `caller` values, + * this API is designed to automatically configure `api.cache`, the same way `api.env()` does. + * + * The `caller` value is available as the first parameter of the callback function. + * It is best used with something like this to toggle configuration behavior + * based on a specific environment: + * + * @example + * function isBabelRegister(caller?: { name: string }) { + * return !!(caller && caller.name === "@babel/register") + * } + * api.caller(isBabelRegister) + * + * @see https://babeljs.io/docs/en/next/config-files#apicallercb + */ + caller(callerCallback: (caller: TransformOptions['caller']) => T): T; + /** + * While `api.version` can be useful in general, it's sometimes nice to just declare your version. + * This API exposes a simple way to do that with: + * + * @example + * api.assertVersion(7) // major version only + * api.assertVersion("^7.2") + * + * @see https://babeljs.io/docs/en/next/config-files#apiassertversionrange + */ + assertVersion(versionRange: number | string): boolean; + // NOTE: this is an undocumented reexport from "@babel/parser" but it's missing from its types + // tokTypes: typeof tokTypes +} + +/** + * JS configs are great because they can compute a config on the fly, + * but the downside there is that it makes caching harder. + * Babel wants to avoid re-executing the config function every time a file is compiled, + * because then it would also need to re-execute any plugin and preset functions + * referenced in that config. + * + * To avoid this, Babel expects users of config functions to tell it how to manage caching + * within a config file. + * + * @see https://babeljs.io/docs/en/next/config-files#apicache + */ +export interface SimpleCacheConfigurator { + // there is an undocumented call signature that is a shorthand for forever()/never()/using(). + // (ever: boolean): void + // (callback: CacheCallback): T + /** + * Permacache the computed config and never call the function again. + */ + forever(): void; + /** + * Do not cache this config, and re-execute the function every time. + */ + never(): void; + /** + * Any time the using callback returns a value other than the one that was expected, + * the overall config function will be called again and a new entry will be added to the cache. + * + * @example + * api.cache.using(() => process.env.NODE_ENV) + */ + using(callback: SimpleCacheCallback): T; + /** + * Any time the using callback returns a value other than the one that was expected, + * the overall config function will be called again and all entries in the cache will + * be replaced with the result. + * + * @example + * api.cache.invalidate(() => process.env.NODE_ENV) + */ + invalidate(callback: SimpleCacheCallback): T; +} + +// https://github.com/babel/babel/blob/v7.3.3/packages/babel-core/src/config/caching.js#L231 +export type SimpleCacheKey = string | boolean | number | null | undefined; +export type SimpleCacheCallback = () => T; + +/** + * Since `NODE_ENV` is a fairly common way to toggle behavior, Babel also includes an API function + * meant specifically for that. This API is used as a quick way to check the `"envName"` that Babel + * was loaded with, which takes `NODE_ENV` into account if no other overriding environment is set. + * + * @see https://babeljs.io/docs/en/next/config-files#apienv + */ +export interface EnvFunction { + /** + * @returns the current `envName` string + */ + (): string; + /** + * @returns `true` if the `envName` is `===` any of the given strings + */ + (envName: string | ReadonlyArray): boolean; + // the official documentation is misleading for this one... + // this just passes the callback to `cache.using` but with an additional argument. + // it returns its result instead of necessarily returning a boolean. + (envCallback: (envName: NonNullable) => T): T; +} + +export type ConfigFunction = (api: ConfigAPI) => TransformOptions; + export as namespace babel; diff --git a/types/node-cache/index.d.ts b/types/node-cache/index.d.ts index 6bac061ecb..61100a574d 100644 --- a/types/node-cache/index.d.ts +++ b/types/node-cache/index.d.ts @@ -283,3 +283,4 @@ declare class NodeCache extends events.EventEmitter implements NodeCache.NodeCac } export = NodeCache; +export as namespace NodeCache;