docs: update transformer documentation to include async transforms (#…

…11716)
jestjs · Aug 27, 2021 · 98f10e6 · 98f10e6
1 parent e065bd8
commit 98f10e6
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 12 deletions.
diff --git a/docs/CodeTransformation.md b/docs/CodeTransformation.md
@@ -22,29 +22,80 @@ 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<OptionType = unknown> {
+interface SyncTransformer<OptionType = unknown> {
   /**
    * 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) => Transformer;
+  createTransformer?: (options?: OptionType) => SyncTransformer<OptionType>;
 
   getCacheKey?: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => string;
 
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
   process: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => TransformedSource;
+
+  processAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
 }
 
+interface AsyncTransformer<OptionType = unknown> {
+  /**
+   * 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<OptionType>;
+
+  getCacheKey?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => string;
+
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
+  process?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => TransformedSource;
+
+  processAsync: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
+}
+
+type Transformer<OptionType = unknown> =
+  | SyncTransformer<OptionType>
+  | AsyncTransformer<OptionType>;
+
 interface TransformOptions<OptionType> {
   /**
    * 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
@@ -69,6 +69,12 @@ export interface TransformOptions<OptionType = unknown>
 }
 
 export interface SyncTransformer<OptionType = unknown> {
+  /**
+   * 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<OptionType>;
 
@@ -98,6 +104,12 @@ export interface SyncTransformer<OptionType = unknown> {
 }
 
 export interface AsyncTransformer<OptionType = unknown> {
+  /**
+   * 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<OptionType>;
 

diff --git a/website/versioned_docs/version-27.0/CodeTransformation.md b/website/versioned_docs/version-27.0/CodeTransformation.md
@@ -22,29 +22,80 @@ 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<OptionType = unknown> {
+interface SyncTransformer<OptionType = unknown> {
   /**
    * 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) => Transformer;
+  createTransformer?: (options?: OptionType) => SyncTransformer<OptionType>;
 
   getCacheKey?: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => string;
 
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
   process: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => TransformedSource;
+
+  processAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
 }
 
+interface AsyncTransformer<OptionType = unknown> {
+  /**
+   * 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<OptionType>;
+
+  getCacheKey?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => string;
+
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
+  process?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => TransformedSource;
+
+  processAsync: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
+}
+
+type Transformer<OptionType = unknown> =
+  | SyncTransformer<OptionType>
+  | AsyncTransformer<OptionType>;
+
 interface TransformOptions<OptionType> {
   /**
    * 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
@@ -22,29 +22,80 @@ 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<OptionType = unknown> {
+interface SyncTransformer<OptionType = unknown> {
   /**
    * 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) => Transformer;
+  createTransformer?: (options?: OptionType) => SyncTransformer<OptionType>;
 
   getCacheKey?: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => string;
 
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
   process: (
     sourceText: string,
-    sourcePath: string,
+    sourcePath: Config.Path,
     options: TransformOptions<OptionType>,
   ) => TransformedSource;
+
+  processAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
 }
 
+interface AsyncTransformer<OptionType = unknown> {
+  /**
+   * 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<OptionType>;
+
+  getCacheKey?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => string;
+
+  getCacheKeyAsync?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<string>;
+
+  process?: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => TransformedSource;
+
+  processAsync: (
+    sourceText: string,
+    sourcePath: Config.Path,
+    options: TransformOptions<OptionType>,
+  ) => Promise<TransformedSource>;
+}
+
+type Transformer<OptionType = unknown> =
+  | SyncTransformer<OptionType>
+  | AsyncTransformer<OptionType>;
+
 interface TransformOptions<OptionType> {
   /**
    * If a transformer does module resolution and reads files, it should populate `cacheFS` so that