enable tscheck on sources

Author: JLHwung

src/Error.js

@@ -1,5 +1,14 @@
+// @ts-check
 const STRIP_FILENAME_RE = /^[^:]+: /;
 
+/**
+ * @typedef { Error & { hideStack?: boolean, codeFrame?: string } } BabelLoaderError
+ */
+/**
+ * Format the error for display.
+ * @param {BabelLoaderError} err
+ * @returns {BabelLoaderError}
+ */
 const format = err => {
   if (err instanceof SyntaxError) {
     err.name = "SyntaxError";
@@ -17,6 +26,9 @@ const format = err => {
 };
 
 class LoaderError extends Error {
+  /**
+   * @param {BabelLoaderError} err
+   */
   constructor(err) {
     super();
 

src/cache.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Filesystem Cache
  *
@@ -17,6 +18,27 @@ const { sync: findUpSync } = require("find-up");
 const { env } = process;
 const transform = require("./transform");
 const serialize = require("./serialize");
+/**
+ * @typedef {object} FileSystemInfoEntry
+ * @property {number} safeTime
+ * @property {number} timestamp
+ */
+/**
+ * @typedef {object} WebpackLogger
+ * @property {function(string): void} debug
+ * @property {function(string): void} info
+ * @property {function(string): void} warn
+ * @property {function(string): void} error
+ */
+/**
+ * @typedef {object} WebpackHash
+ * @property {(data: string | Buffer, inputEncoding?: string) => WebpackHash} update
+ * @property {(encoding?: string) => string | Buffer} digest
+ */
+
+/**
+ * @type {string | null}
+ */
 let defaultCacheDirectory = null;
 
 const gunzip = promisify(zlib.gunzip);
@@ -35,8 +57,8 @@ const findRootPackageJSON = () => {
  * Read the contents from the compressed file.
  *
  * @async
- * @params {String} filename
- * @params {Boolean} compress
+ * @param {string} filename
+ * @param {boolean} compress
  */
 const read = async function (filename, compress) {
   const data = await readFile(filename + (compress ? ".gz" : ""));
@@ -47,11 +69,10 @@ const read = async function (filename, compress) {
 
 /**
  * Write contents into a compressed file.
- *
  * @async
- * @params {String} filename
- * @params {Boolean} compress
- * @params {String} result
+ * @param {string} filename
+ * @param {boolean} compress
+ * @param {any} result
  */
 const write = async function (filename, compress, result) {
   const content = JSON.stringify(result);
@@ -62,18 +83,24 @@ const write = async function (filename, compress, result) {
 
 /**
  * Build the filename for the cached file
- *
- * @params {String} source  File source code
- * @params {Object} options Options used
- *
- * @return {String}
+ * @param {string} source File source code
+ * @param {string} identifier Unique identifier to bust cache
+ * @param {Object} options Options used
+ * @param {WebpackHash} hash Hash function returned by `LoaderContext.utils.createHash`
+ * @return {string}
  */
 const filename = function (source, identifier, options, hash) {
   hash.update(serialize([options, source, identifier]));
 
   return hash.digest("hex") + ".json";
 };
 
+/**
+ * Add timestamps to external dependencies.
+ * @async
+ * @param {import("./transform").TransformResult["externalDependencies"]} externalDependencies
+ * @param {(filename: string) => Promise<FileSystemInfoEntry>} getFileTimestamp
+ */
 const addTimestamps = async function (externalDependencies, getFileTimestamp) {
   for (const depAndEmptyTimestamp of externalDependencies) {
     try {
@@ -86,6 +113,13 @@ const addTimestamps = async function (externalDependencies, getFileTimestamp) {
   }
 };
 
+/**
+ * Check if any external dependencies have been modified.
+ * @async
+ * @param {import("./transform").TransformResult["externalDependencies"]} externalDepsWithTimestamp
+ * @param {(filename: string) => Promise<FileSystemInfoEntry>} getFileTimestamp
+ * @returns {Promise<boolean>}
+ */
 const areExternalDependenciesModified = async function (
   externalDepsWithTimestamp,
   getFileTimestamp,
@@ -107,9 +141,18 @@ const areExternalDependenciesModified = async function (
 
 /**
  * Handle the cache
- *
- * @params {String} directory
- * @params {Object} params
+ * @async
+ * @param {string} directory
+ * @param {Object} params
+ * @param {string} params.source The source code to transform.
+ * @param {import(".").NormalizedOptions} [params.options] Options used for transformation.
+ * @param {string} params.cacheIdentifier Unique identifier to bust cache.
+ * @param {string} [params.cacheDirectory] Directory to store cached files.
+ * @param {boolean} [params.cacheCompression] Whether to compress cached files.
+ * @param {WebpackHash} params.hash Hash function to use for the cache filename.
+ * @param {(filename: string) => Promise<FileSystemInfoEntry>} params.getFileTimestamp - Function to get file timestamps.
+ * @param {WebpackLogger} params.logger
+ * @returns {Promise<null | import("./transform").TransformResult>}
  */
 const handleCache = async function (directory, params) {
   const {
@@ -170,6 +213,10 @@ const handleCache = async function (directory, params) {
   // return it to the user asap and write it in cache
   logger.debug(`applying Babel transform`);
   const result = await transform(source, options);
+  if (!result) {
+    logger.debug(`no result from Babel transform, skipping cache write`);
+    return null;
+  }
   await addTimestamps(result.externalDependencies, getFileTimestamp);
 
   try {
@@ -189,14 +236,17 @@ const handleCache = async function (directory, params) {
 
 /**
  * Retrieve file from cache, or create a new one for future reads
- *
  * @async
- * @param  {Object}   params
- * @param  {String}   params.cacheDirectory   Directory to store cached files
- * @param  {String}   params.cacheIdentifier  Unique identifier to bust cache
- * @param  {Boolean}  params.cacheCompression Whether compressing cached files
- * @param  {String}   params.source   Original contents of the file to be cached
- * @param  {Object}   params.options  Options to be given to the transform fn
+ * @param {object} params
+ * @param {string} params.cacheDirectory Directory to store cached files.
+ * @param {string} params.cacheIdentifier Unique identifier to bust cache.
+ * @param {boolean} params.cacheCompression Whether compressing cached files.
+ * @param {string} params.source Original contents of the file to be cached.
+ * @param {import(".").NormalizedOptions} params.options Options to be given to the transform function.
+ * @param {function} params.transform Transform function to apply to the file.
+ * @param {WebpackHash} params.hash Hash function to use for the cache filename.
+ * @param {function(string): Promise<FileSystemInfoEntry>} params.getFileTimestamp Function to get file timestamps.
+ * @param {WebpackLogger} params.logger Logger instance.
  *
  * @example
  *
@@ -212,7 +262,7 @@ const handleCache = async function (directory, params) {
  *   });
  */
 
-module.exports = async function (params) {
+module.exports = async function cache(params) {
   let directory;
 
   if (typeof params.cacheDirectory === "string") {
@@ -225,13 +275,23 @@ module.exports = async function (params) {
   return await handleCache(directory, params);
 };
 
+/**
+ * Find the cache directory for babel-loader.
+ * @param {string} name "babel-loader"
+ * @returns {string}
+ */
 function findCacheDir(name) {
   if (env.CACHE_DIR && !["true", "false", "1", "0"].includes(env.CACHE_DIR)) {
     return path.join(env.CACHE_DIR, name);
   }
-  const rootPkgJSONPath = path.dirname(findRootPackageJSON());
+  const rootPkgJSONPath = findRootPackageJSON();
   if (rootPkgJSONPath) {
-    return path.join(rootPkgJSONPath, "node_modules", ".cache", name);
+    return path.join(
+      path.dirname(rootPkgJSONPath),
+      "node_modules",
+      ".cache",
+      name,
+    );
   }
   return os.tmpdir();
 }

src/index.js

@@ -1,3 +1,37 @@
+// @ts-check
+/**
+ * @typedef {object} LoaderOnlyOptions
+ * @property {string} [cacheDirectory] Directory to store cached files.
+ * @property {string} [cacheIdentifier] Unique identifier to bust cache.
+ * @property {boolean} [cacheCompression] Whether to compress cached files.
+ * @property {string} [customize] The absolute path of a file that exports a BabelLoaderWrapper.
+ * @property {Array<string>} [metadataSubscribers] Names of subscribers registered in the loader context.
+ */
+
+/**
+ * @typedef {import("webpack").LoaderContext<LoaderOptions>} BabelLoaderContext
+ * @typedef {string} BabelLoaderSource Parameters<import("webpack").LoaderDefinitionFunction>[0]
+ * @typedef {string} BabelLoaderInputSourceMap Parameters<import("webpack").LoaderDefinitionFunction>[1]
+ *
+ * @todo Consider exporting these types from @babel/core
+ * @typedef {Awaited<ReturnType<import("@babel/core").loadPartialConfigAsync>>} PartialConfig
+ * @typedef {PartialConfig['options']} NormalizedOptions
+ */
+
+/**
+ * @typedef {(babel: typeof import("@babel/core")) => BabelOverrideHooks} BabelLoaderWrapper
+ * @typedef {object} BabelOverrideHooks
+ * @property {(this: BabelLoaderContext, loaderOptions: LoaderOptions, params: { source: BabelLoaderSource, map: BabelLoaderInputSourceMap }) => Promise<{ custom: any, loader: LoaderOptions }>} customOptions
+ * @property {(this: BabelLoaderContext, config: PartialConfig, params: { source: BabelLoaderSource, map: BabelLoaderInputSourceMap, customOptions: any }) => Promise<PartialConfig['options']>} config
+ * @property {(this: BabelLoaderContext, result: import("./transform").TransformResult, params: { source: BabelLoaderSource, map: BabelLoaderInputSourceMap, customOptions: any, config: PartialConfig, options: PartialConfig['options'] }) => Promise<import("./transform").TransformResult>} result
+ */
+/**
+ * @typedef {import("@babel/core").InputOptions & LoaderOnlyOptions} LoaderOptions
+ */
+
+/**
+ * @type {import("@babel/core")}
+ */
 let babel;
 try {
   babel = require("@babel/core");
@@ -23,38 +57,66 @@ const { version } = require("../package.json");
 const cache = require("./cache");
 const transform = require("./transform");
 const injectCaller = require("./injectCaller");
-const schema = require("./schema");
+const schema = require("./schema.json");
 
 const { isAbsolute } = require("path");
 const { promisify } = require("util");
 
+/**
+ * Invoke a metadata subscriber registered in the loader context.
+ * @param {string} subscriber
+ * @param {unknown} metadata
+ * @param {import("webpack").LoaderContext<LoaderOptions>} context
+ */
 function subscribe(subscriber, metadata, context) {
+  // @ts-expect-error subscriber is a custom function
   if (context[subscriber]) {
+    // @ts-expect-error subscriber is a custom function
     context[subscriber](metadata);
   }
 }
 
 module.exports = makeLoader();
 module.exports.custom = makeLoader;
 
+/**
+ * @param {BabelLoaderWrapper} [callback]
+ */
 function makeLoader(callback) {
   const overrides = callback ? callback(babel) : undefined;
 
-  return function (source, inputSourceMap) {
+  /**
+   * @this {BabelLoaderContext}
+   * @param {BabelLoaderSource} source
+   * @param {BabelLoaderInputSourceMap} inputSourceMap
+   */
+  const webpackLoader = function (source, inputSourceMap) {
     // Make the loader async
     const callback = this.async();
 
     loader.call(this, source, inputSourceMap, overrides).then(
+      // @ts-expect-error (FixMe): Argument of type 'string | EncodedSourceMap' is not assignable to parameter of type 'string | Buffer<ArrayBufferLike>'.
       args => callback(null, ...args),
       err => callback(err),
     );
   };
+
+  return webpackLoader;
 }
 
+/**
+ * Babel loader
+ * @this {BabelLoaderContext}
+ * @param {BabelLoaderSource} source The source code to transform
+ * @param {BabelLoaderInputSourceMap} inputSourceMap
+ * @param {BabelOverrideHooks} overrides
+ * @returns
+ */
 async function loader(source, inputSourceMap, overrides) {
   const filename = this.resourcePath;
   const logger = this.getLogger("babel-loader");
 
+  // @ts-expect-error TS does not treat schema.json/properties/cacheDirectory/type as a constant string literal
   let loaderOptions = this.getOptions(schema);
 
   if (loaderOptions.customize != null) {
@@ -72,6 +134,7 @@ async function loader(source, inputSourceMap, overrides) {
     }
 
     logger.debug(`loading customize override: '${loaderOptions.customize}'`);
+
     let override = require(loaderOptions.customize);
     if (override.__esModule) override = override.default;
 
@@ -182,12 +245,21 @@ async function loader(source, inputSourceMap, overrides) {
       metadataSubscribers = [],
     } = loaderOptions;
 
+    /**
+     * @type {import("./transform").TransformResult}
+     */
     let result;
     if (cacheDirectory) {
       logger.debug("cache is enabled");
-      const getFileTimestamp = promisify((path, cb) => {
-        this._compilation.fileSystemInfo.getFileTimestamp(path, cb);
-      });
+      const getFileTimestamp = promisify(
+        /**
+         * @param {string} path
+         * @param {(err: import("webpack").WebpackError | null, fileTimestamp: import("./cache").FileSystemInfoEntry) => void} cb
+         */
+        (path, cb) => {
+          this._compilation.fileSystemInfo.getFileTimestamp(path, cb);
+        },
+      );
       const hash = this.utils.createHash(
         this._compilation.outputOptions.hashFunction,
       );

src/injectCaller.js

@@ -1,5 +1,13 @@
+// @ts-check
+/**
+ * Inject babel-loader caller information into the Babel options.
+ * @param {import("@babel/core").InputOptions} opts
+ * @param {string} target
+ * @returns {import("@babel/core").InputOptions}
+ */
 module.exports = function injectCaller(opts, target) {
-  return Object.assign({}, opts, {
+  return {
+    ...opts,
     caller: Object.assign(
       {
         name: "babel-loader",
@@ -19,5 +27,5 @@ module.exports = function injectCaller(opts, target) {
       },
       opts.caller,
     ),
-  });
+  };
 };