From 98f10e698ae986c19fef2d8117be2341bcfb8f7f Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Fri, 27 Aug 2021 06:13:45 -0700 Subject: [PATCH] docs: update transformer documentation to include async transforms (#11716) --- docs/CodeTransformation.md | 59 +++++++++++++++++-- packages/jest-transform/src/types.ts | 12 ++++ .../version-27.0/CodeTransformation.md | 59 +++++++++++++++++-- .../version-27.1/CodeTransformation.md | 59 +++++++++++++++++-- 4 files changed, 177 insertions(+), 12 deletions(-) diff --git a/docs/CodeTransformation.md b/docs/CodeTransformation.md index a6982041f338..a7a71094f728 100644 --- a/docs/CodeTransformation.md +++ b/docs/CodeTransformation.md @@ -22,7 +22,7 @@ If you override the `transform` configuration option `babel-jest` will no longer You can write you own transformer. The API of a transformer is as follows: ```ts -interface Transformer { +interface SyncTransformer { /** * Indicates if the transformer is capabale of instrumenting the code for code coverage. * @@ -30,21 +30,72 @@ interface Transformer { * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. */ canInstrument?: boolean; - createTransformer?: (options?: OptionType) => Transformer; + createTransformer?: (options?: OptionType) => SyncTransformer; getCacheKey?: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => string; + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + process: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => TransformedSource; + + processAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; } +interface AsyncTransformer { + /** + * Indicates if the transformer is capabale of instrumenting the code for code coverage. + * + * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented. + * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. + */ + canInstrument?: boolean; + createTransformer?: (options?: OptionType) => AsyncTransformer; + + getCacheKey?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => string; + + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + + process?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => TransformedSource; + + processAsync: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; +} + +type Transformer = + | SyncTransformer + | AsyncTransformer; + interface TransformOptions { /** * If a transformer does module resolution and reads files, it should populate `cacheFS` so that diff --git a/packages/jest-transform/src/types.ts b/packages/jest-transform/src/types.ts index fa18c2ec4196..cc6f2e3995a4 100644 --- a/packages/jest-transform/src/types.ts +++ b/packages/jest-transform/src/types.ts @@ -69,6 +69,12 @@ export interface TransformOptions } export interface SyncTransformer { + /** + * Indicates if the transformer is capabale of instrumenting the code for code coverage. + * + * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented. + * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. + */ canInstrument?: boolean; createTransformer?: (options?: OptionType) => SyncTransformer; @@ -98,6 +104,12 @@ export interface SyncTransformer { } export interface AsyncTransformer { + /** + * Indicates if the transformer is capabale of instrumenting the code for code coverage. + * + * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented. + * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. + */ canInstrument?: boolean; createTransformer?: (options?: OptionType) => AsyncTransformer; diff --git a/website/versioned_docs/version-27.0/CodeTransformation.md b/website/versioned_docs/version-27.0/CodeTransformation.md index a6982041f338..a7a71094f728 100644 --- a/website/versioned_docs/version-27.0/CodeTransformation.md +++ b/website/versioned_docs/version-27.0/CodeTransformation.md @@ -22,7 +22,7 @@ If you override the `transform` configuration option `babel-jest` will no longer You can write you own transformer. The API of a transformer is as follows: ```ts -interface Transformer { +interface SyncTransformer { /** * Indicates if the transformer is capabale of instrumenting the code for code coverage. * @@ -30,21 +30,72 @@ interface Transformer { * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. */ canInstrument?: boolean; - createTransformer?: (options?: OptionType) => Transformer; + createTransformer?: (options?: OptionType) => SyncTransformer; getCacheKey?: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => string; + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + process: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => TransformedSource; + + processAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; } +interface AsyncTransformer { + /** + * Indicates if the transformer is capabale of instrumenting the code for code coverage. + * + * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented. + * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. + */ + canInstrument?: boolean; + createTransformer?: (options?: OptionType) => AsyncTransformer; + + getCacheKey?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => string; + + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + + process?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => TransformedSource; + + processAsync: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; +} + +type Transformer = + | SyncTransformer + | AsyncTransformer; + interface TransformOptions { /** * If a transformer does module resolution and reads files, it should populate `cacheFS` so that diff --git a/website/versioned_docs/version-27.1/CodeTransformation.md b/website/versioned_docs/version-27.1/CodeTransformation.md index a6982041f338..a7a71094f728 100644 --- a/website/versioned_docs/version-27.1/CodeTransformation.md +++ b/website/versioned_docs/version-27.1/CodeTransformation.md @@ -22,7 +22,7 @@ If you override the `transform` configuration option `babel-jest` will no longer You can write you own transformer. The API of a transformer is as follows: ```ts -interface Transformer { +interface SyncTransformer { /** * Indicates if the transformer is capabale of instrumenting the code for code coverage. * @@ -30,21 +30,72 @@ interface Transformer { * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. */ canInstrument?: boolean; - createTransformer?: (options?: OptionType) => Transformer; + createTransformer?: (options?: OptionType) => SyncTransformer; getCacheKey?: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => string; + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + process: ( sourceText: string, - sourcePath: string, + sourcePath: Config.Path, options: TransformOptions, ) => TransformedSource; + + processAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; } +interface AsyncTransformer { + /** + * Indicates if the transformer is capabale of instrumenting the code for code coverage. + * + * If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented. + * If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel. + */ + canInstrument?: boolean; + createTransformer?: (options?: OptionType) => AsyncTransformer; + + getCacheKey?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => string; + + getCacheKeyAsync?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; + + process?: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => TransformedSource; + + processAsync: ( + sourceText: string, + sourcePath: Config.Path, + options: TransformOptions, + ) => Promise; +} + +type Transformer = + | SyncTransformer + | AsyncTransformer; + interface TransformOptions { /** * If a transformer does module resolution and reads files, it should populate `cacheFS` so that