babel-loader 10.0.0 → 10.1.1

package/README.md

@@ -15,7 +15,7 @@
 
 <h1 align="center">Babel Loader</h1>
 
-This package allows transpiling JavaScript files using [Babel](https://github.com/babel/babel) and [webpack](https://github.com/webpack/webpack).
+This package allows transpiling JavaScript files using [Babel](https://github.com/babel/babel) together with [webpack](https://github.com/webpack/webpack) or [Rspack](https://github.com/web-infra-dev/rspack).
 
 **Note**: Issues with the output should be reported on the Babel [Issues](https://github.com/babel/babel/issues) tracker.
 

package/lib/Error.js

@@ -1,4 +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";
@@ -12,6 +22,9 @@ const format = err => {
   return err;
 };
 class LoaderError extends Error {
+  /**
+   * @param {BabelLoaderError} err
+   */
   constructor(err) {
     super();
     const {

package/lib/cache.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Filesystem Cache
  *
@@ -26,6 +27,27 @@ const {
 } = 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);
 const gzip = promisify(zlib.gzip);
@@ -34,8 +56,8 @@ const gzip = promisify(zlib.gzip);
  * 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" : ""));
@@ -45,11 +67,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);
@@ -59,16 +80,23 @@ 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 {
@@ -82,6 +110,14 @@ 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) {
   for (const depAndTimestamp of externalDepsWithTimestamp) {
     const [dep, timestamp] = depAndTimestamp;
@@ -100,9 +136,18 @@ const areExternalDependenciesModified = async function (externalDepsWithTimestam
 
 /**
  * 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 {
@@ -127,7 +172,7 @@ const handleCache = async function (directory, params) {
     }
     logger.debug(`discarded cache file '${file}' due to changes in external dependencies`);
   } catch {
-    // conitnue if cache can't be read
+    // continue if cache can't be read
     logger.debug(`discarded cache as it can not be read`);
   }
   const fallback = typeof cacheDirectory !== "string" && directory !== os.tmpdir();
@@ -150,6 +195,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 {
     logger.debug(`writing result to cache file '${file}'`);
@@ -166,14 +215,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
  *
@@ -189,7 +241,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") {
     directory = params.cacheDirectory;
@@ -199,13 +251,19 @@ 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(findUpSync("package.json"));
+  const rootPkgJSONPath = findUpSync("package.json");
   if (rootPkgJSONPath) {
-    return path.join(rootPkgJSONPath, "node_modules", ".cache", name);
+    return path.join(path.dirname(rootPkgJSONPath), "node_modules", ".cache", name);
   }
   return os.tmpdir();
 }

package/lib/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");
@@ -19,31 +53,64 @@ const {
 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(args => callback(null, ...args), err => callback(err));
+    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) {
     if (!isAbsolute(loaderOptions.customize)) {
@@ -133,10 +200,19 @@ async function loader(source, inputSourceMap, overrides) {
       cacheCompression = true,
       metadataSubscribers = []
     } = loaderOptions;
+
+    /**
+     * @type {import("./transform").TransformResult}
+     */
     let result;
     if (cacheDirectory) {
       logger.debug("cache is enabled");
-      const getFileTimestamp = promisify((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);

package/lib/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",
       // Provide plugins with insight into webpack target.
@@ -13,5 +21,5 @@ module.exports = function injectCaller(opts, target) {
       // flag isn't enabled.
       supportsTopLevelAwait: true
     }, opts.caller)
-  });
+  };
 };

package/lib/serialize.js

@@ -1,3 +1,4 @@
+// @ts-check
 var objToString = Object.prototype.toString;
 var objKeys = Object.getOwnPropertyNames;
 
@@ -5,7 +6,7 @@ var objKeys = Object.getOwnPropertyNames;
  * A custom Babel options serializer
  *
  * Intentional deviation from JSON.stringify:
- * 1. Object properties are sorted before seralizing
+ * 1. Object properties are sorted before serializing
  * 2. The output is NOT a valid JSON: e.g.
  *    The output does not enquote strings, which means a JSON-like string '{"a":1}'
  *    will share the same result with an JS object { a: 1 }. This is not an issue
@@ -13,8 +14,8 @@ var objKeys = Object.getOwnPropertyNames;
  * 3. Only 20% slower than the native JSON.stringify on V8
  *
  * This function is a fork from https://github.com/nickyout/fast-stable-stringify
- * @param {*} val Babel options
- * @param {*} isArrayProp
+ * @param {unknown} val Babel options
+ * @param {boolean} isArrayProp
  * @returns serialized Babel options
  */
 function serialize(val, isArrayProp) {
@@ -29,17 +30,22 @@ function serialize(val, isArrayProp) {
     case "object":
       if (val === null) {
         return null;
+        // @ts-expect-error
       } else if (val.toJSON && typeof val.toJSON === "function") {
+        // @ts-expect-error toJSON has been checked above
         return serialize(val.toJSON(), isArrayProp);
       } else {
         toStr = objToString.call(val);
         if (toStr === "[object Array]") {
           str = "[";
+          // @ts-expect-error val is an array
           max = val.length - 1;
           for (i = 0; i < max; i++) {
+            // @ts-expect-error val is an array
             str += serialize(val[i], true) + ",";
           }
           if (max > -1) {
+            // @ts-expect-error val is an array
             str += serialize(val[i], true);
           }
           return str + "]";
@@ -51,6 +57,7 @@ function serialize(val, isArrayProp) {
           i = 0;
           while (i < max) {
             key = keys[i];
+            // @ts-expect-error key must index val
             propVal = serialize(val[key], false);
             if (propVal !== undefined) {
               if (str) {
@@ -71,9 +78,15 @@ function serialize(val, isArrayProp) {
     case "string":
       return val;
     default:
+      // @ts-expect-error val must be a number because of the toJSON check above
       return isFinite(val) ? val : null;
   }
 }
+
+/**
+ * @param {unknown} val
+ * @returns {string | undefined}
+ */
 module.exports = function (val) {
   var returnVal = serialize(val, false);
   if (returnVal !== undefined) {

package/lib/transform.js

@@ -1,13 +1,31 @@
+// @ts-check
 const babel = require("@babel/core");
 const {
   promisify
 } = require("util");
 const LoaderError = require("./Error");
-const transform = promisify(babel.transform);
-module.exports = async function (source, options) {
+const babelTransform = babel.transformAsync ?? promisify(babel.transform);
+/**
+ * @typedef {Object} AmendedTransformResult
+ * @property {[string, number?][]} externalDependencies
+ */
+/**
+ * @typedef {Omit<import("@babel/core").FileResult, "externalDependencies" | "options"> & AmendedTransformResult} TransformResult
+ */
+/**
+ * Transform the source code using Babel.
+ * @async
+ * @param {string} source The source code to transform.
+ * @param {import("@babel/core").InputOptions} options The Babel options.
+ * @returns {Promise<null | TransformResult>} The transformed result or null if no transformation is needed.
+ */
+module.exports = async function transform(source, options) {
+  /**
+   * @type {import("@babel/core").FileResult}
+   */
   let result;
   try {
-    result = await transform(source, options);
+    result = await babelTransform(source, options);
   } catch (err) {
     throw err.message && err.codeFrame ? new LoaderError(err) : err;
   }
@@ -36,7 +54,12 @@ module.exports = async function (source, options) {
     metadata,
     sourceType,
     // Convert it from a Set to an Array to make it JSON-serializable.
-    externalDependencies: Array.from(externalDependencies || [], dep => [dep]).sort()
+    externalDependencies: Array.from(externalDependencies || [],
+    /**
+     * @param {string} dep
+     * @returns {[string, number?]}
+     */
+    dep => [dep]).sort()
   };
 };
 module.exports.version = babel.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-loader",
-  "version": "10.0.0",
+  "version": "10.1.1",
   "description": "babel module loader for webpack",
   "files": [
     "lib"
@@ -13,14 +13,24 @@
     "find-up": "^5.0.0"
   },
   "peerDependencies": {
-    "@babel/core": "^7.12.0",
+    "@babel/core": "^7.12.0 || ^8.0.0-beta.1",
+    "@rspack/core": "^1.0.0 || ^2.0.0-0",
     "webpack": ">=5.61.0"
   },
+  "peerDependenciesMeta": {
+    "@rspack/core": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@babel/cli": "^7.23.0",
-    "@babel/core": "^7.23.3",
-    "@babel/eslint-parser": "^7.23.3",
-    "@babel/preset-env": "^7.23.3",
+    "@babel/cli": "^8.0.0-beta.1",
+    "@babel/core": "^8.0.0-beta.1",
+    "@babel/eslint-parser": "^8.0.0-beta.1",
+    "@babel/preset-env": "^8.0.0-beta.1",
+    "@rspack/core": "^1.7.5",
     "c8": "^10.1.2",
     "eslint": "^9.6.0",
     "eslint-config-prettier": "^9.1.0",
@@ -29,6 +39,7 @@
     "husky": "^9.1.5",
     "lint-staged": "^15.2.9",
     "prettier": "^3.0.0",
+    "typescript": "^5.8.3",
     "webpack": "^5.93.0"
   },
   "scripts": {
@@ -38,7 +49,7 @@
     "lint": "eslint src test",
     "precommit": "lint-staged",
     "prepublish": "yarn run clean && yarn run build",
-    "preversion": "yarn run test",
+    "preversion": "yarn tsc && yarn run test",
     "test": "yarn run lint && yarn run build --source-maps && c8 yarn run test-only",
     "test-only": "node --test test/**/*.test.js"
   },