fix(types): allow async loader to return void (#11511)

* fix(types): allow async loader to return void

* Update packages/rspack/src/config/adapterRuleUse.ts

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: chenjiahan

packages/rspack/etc/core.api.md

@@ -4323,14 +4323,14 @@ export interface LoaderContext<OptionsType = {}> {
 // @public (undocumented)
 type LoaderContextCallback = (err?: Error | null, content?: string | Buffer, sourceMap?: string | SourceMap, additionalData?: AdditionalData) => void;
 
-// @public (undocumented)
+// @public
 export type LoaderDefinition<OptionsType = {}, ContextAdditions = {}> = LoaderDefinitionFunction<OptionsType, ContextAdditions> & {
     raw?: false;
     pitch?: PitchLoaderDefinitionFunction;
 };
 
 // @public (undocumented)
-export type LoaderDefinitionFunction<OptionsType = {}, ContextAdditions = {}> = (this: LoaderContext<OptionsType> & ContextAdditions, content: string, sourceMap?: string | SourceMap, additionalData?: AdditionalData) => string | void | Buffer | Promise<string | Buffer>;
+export type LoaderDefinitionFunction<OptionsType = {}, ContextAdditions = {}> = (this: LoaderContext<OptionsType> & ContextAdditions, content: string, sourceMap?: string | SourceMap, additionalData?: AdditionalData) => string | void | Buffer | Promise<string | Buffer | void>;
 
 // @public (undocumented)
 interface LoaderExperiments {
@@ -5565,7 +5565,7 @@ type Performance_2 = false | {
 export { Performance_2 as Performance }
 
 // @public (undocumented)
-export type PitchLoaderDefinitionFunction<OptionsType = {}, ContextAdditions = {}> = (this: LoaderContext<OptionsType> & ContextAdditions, remainingRequest: string, previousRequest: string, data: object) => string | void | Buffer | Promise<string | Buffer>;
+export type PitchLoaderDefinitionFunction<OptionsType = {}, ContextAdditions = {}> = (this: LoaderContext<OptionsType> & ContextAdditions, remainingRequest: string, previousRequest: string, data: object) => string | void | Buffer | Promise<string | Buffer | void>;
 
 // @public (undocumented)
 type Plugin_2 = RspackPluginInstance | RspackPluginFunction | WebpackPluginInstance | WebpackPluginFunction | Falsy;

packages/rspack/src/config/adapterRuleUse.ts

@@ -394,7 +394,7 @@ export type LoaderDefinitionFunction<
 	content: string,
 	sourceMap?: string | SourceMap,
 	additionalData?: AdditionalData
-) => string | void | Buffer | Promise<string | Buffer>;
+) => string | void | Buffer | Promise<string | Buffer | void>;
 
 export type PitchLoaderDefinitionFunction<
 	OptionsType = {},
@@ -404,8 +404,32 @@ export type PitchLoaderDefinitionFunction<
 	remainingRequest: string,
 	previousRequest: string,
 	data: object
-) => string | void | Buffer | Promise<string | Buffer>;
-
+) => string | void | Buffer | Promise<string | Buffer | void>;
+
+/**
+ * Defines a loader for Rspack.
+ * A loader is a transformer that converts various types of modules into Rspack
+ * supported types. By using different kinds of loaders, you can extend Rspack to
+ * process additional module types, including JSX, Markdown, Sass, Less, and more.
+ *
+ * @template OptionsType - The type of options that the loader accepts
+ * @template ContextAdditions - Additional properties to add to the loader context
+ *
+ * @example
+ * ```ts
+ * import type { LoaderDefinition } from '@rspack/core';
+ *
+ * type MyLoaderOptions = {
+ *   foo: string;
+ * };
+ *
+ * const myLoader: LoaderDefinition<MyLoaderOptions> = function(source) {
+ *   return someOperation(source);
+ * };
+ *
+ * export default myLoader;
+ * ```
+ */
 export type LoaderDefinition<
 	OptionsType = {},
 	ContextAdditions = {}

website/docs/en/api/loader-api/types.mdx

@@ -92,23 +92,42 @@ ESM loader and CommonJS loader have the same functionality, but use different mo
 
 ## Write with TypeScript
 
-If you write Rspack loader using TypeScript, you can import `LoaderContext` to add types to the loader:
+If you write Rspack loader using TypeScript, you can use `LoaderDefinition` to provide complete type definitions for your loader.
 
 ```ts title="my-loader.ts"
-import type { LoaderContext } from '@rspack/core';
+import type { LoaderDefinition } from '@rspack/core';
 
 // Declare the type of loader options
 type MyLoaderOptions = {
   foo: string;
 };
 
+const myLoader: LoaderDefinition<MyLoaderOptions> = function (source) {
+  const options = this.getOptions();
+  console.log(options); // { foo: 'bar' }
+  // Transform the source code
+  return `// Processed by my-loader\n${source}`;
+};
+
+export default myLoader;
+```
+
+Alternatively, you can import `LoaderContext` to add types to the loader context:
+
+```ts title="my-loader.ts"
+import type { LoaderContext } from '@rspack/core';
+
+type MyLoaderOptions = {
+  foo: string;
+};
+
 export default function myLoader(
   this: LoaderContext<MyLoaderOptions>,
   source: string,
 ) {
   const options = this.getOptions();
   console.log(options); // { foo: 'bar' }
-  return source;
+  return `// Processed by my-loader\n${source}`;
 }
 ```
 

website/docs/zh/api/loader-api/types.mdx

@@ -92,23 +92,42 @@ ESM loader 和 CommonJS loader 的功能完全相同，只是使用了不同的
 
 ## 使用 TypeScript 编写
 
-如果你使用 TypeScript 来编写 Rspack loader，可以引入 `LoaderContext` 来为 loader 添加类型：
+如果你使用 TypeScript 编写 Rspack loader，可以使用 `LoaderDefinition` 为你的 loader 提供完整的类型定义。
 
 ```ts title="my-loader.ts"
-import type { LoaderContext } from '@rspack/core';
+import type { LoaderDefinition } from '@rspack/core';
 
 // 声明 loader 选项的类型
 type MyLoaderOptions = {
   foo: string;
 };
 
+const myLoader: LoaderDefinition<MyLoaderOptions> = function (source) {
+  const options = this.getOptions();
+  console.log(options); // { foo: 'bar' }
+  // Transform the source code
+  return `// Processed by my-loader\n${source}`;
+};
+
+export default myLoader;
+```
+
+或者，你也可以导入 `LoaderContext` 为 loader 上下文添加类型：
+
+```ts title="my-loader.ts"
+import type { LoaderContext } from '@rspack/core';
+
+type MyLoaderOptions = {
+  foo: string;
+};
+
 export default function myLoader(
   this: LoaderContext<MyLoaderOptions>,
   source: string,
 ) {
   const options = this.getOptions();
   console.log(options); // { foo: 'bar' }
-  return source;
+  return `// Processed by my-loader\n${source}`;
 }
 ```