@genapi/pipeline 4.0.0 → 4.1.0

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-PRESENT Hairyf <https://github.com/hairyf>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-PRESENT Hairyf <https://github.com/hairyf>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,60 +1,111 @@
-# @genapi/pipeline
-
-<!-- automd:badges -->
-
-[![npm version](https://img.shields.io/npm/v/@genapi/pipeline)](https://npmjs.com/package/@genapi/pipeline)
-[![npm downloads](https://img.shields.io/npm/dm/@genapi/pipeline)](https://npm.chart.dev/@genapi/pipeline)
-
-<!-- /automd -->
-
-GenAPI pipeline core: config reading, data source fetching, parsing, compilation, generation, and output. Composable for custom generation flows.
-
-## Installation
-
-```bash
-pnpm add @genapi/pipeline
-```
-
-## API
-
-<!-- automd:jsdocs src=src/index.ts -->
-
-## Pipeline
-
-### `compiler(configRead)`
-
-Compiles graphs to AST: request code and typings for each output.
-
-### `config(userConfig)`
-
-Normalizes pipeline config: output paths, responseType, baseURL (from meta), and builds ConfigRead with inputs/outputs.
-
-### `default(config, original, parser, compiler, generate, dest)`
-
-Builds a GenAPI pipeline from five steps: config → original → parser → compiler → generate → dest.
-
-### `dest(configRead)`
-
-Writes output files from configRead.outputs (code to path).
-
-### `generate(configRead)`
-
-Generates code string from AST for each output and formats with Prettier.
-
-### `original(configRead)`
-
-Fetches source: resolves uri/http/json from configRead.inputs and sets configRead.source.
-
-<!-- /automd -->
-
-## License
-
-[MIT](https://github.com/hairyf/genapi/blob/main/LICENSE)
-
-<!-- automd:with-automd -->
-
----
-
-_🤖 auto updated with [automd](https://automd.unjs.io)_
-
-<!-- /automd -->
+# @genapi/pipeline
+
+<!-- automd:badges -->
+
+[![npm version](https://img.shields.io/npm/v/@genapi/pipeline)](https://npmjs.com/package/@genapi/pipeline)
+[![npm downloads](https://img.shields.io/npm/dm/@genapi/pipeline)](https://npm.chart.dev/@genapi/pipeline)
+
+<!-- /automd -->
+
+GenAPI pipeline core: config reading, data source fetching, parsing, compilation, generation, and output. Composable for custom generation flows.
+
+## Installation
+
+```bash
+pnpm add @genapi/pipeline
+```
+
+## API
+
+<!-- automd:jsdocs src=src/index.ts -->
+
+## Pipeline
+
+### `compiler(configRead)`
+
+Compiles graphs to code string: request and typings for each output.
+
+**Example:**
+
+```ts
+compiler(configRead)
+configRead.outputs.forEach(o => console.log(o.code))
+```
+
+### `config(userConfig)`
+
+Normalizes pipeline config: output paths, responseType, baseURL, and builds ConfigRead with inputs/outputs.
+
+**Example:**
+
+```ts
+const configRead = config(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+```
+
+### `default(config, original, parser, compiler, generate, dest)`
+
+Builds a GenAPI pipeline from five steps: config → original → parser → compiler → generate → dest.
+
+**Example:**
+
+```ts
+const run = pipeline(config, original, parser, compiler, generate, dest)
+await run(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+```
+
+### `dest(configRead)`
+
+Writes output files from configRead.outputs (code to path).
+
+**Example:**
+
+```ts
+await dest(configRead)
+// Writes configRead.outputs[].code to configRead.outputs[].path
+```
+
+### `generate(configRead, options?)`
+
+Formats code for each output with Prettier.
+
+**Example:**
+
+```ts
+await generate(configRead)
+await generate(configRead, { printWidth: 100 })
+```
+
+### `original(configRead)`
+
+Fetches source: resolves uri/http/json from configRead.inputs and sets configRead.source. Transforms the source based on parser configuration (wpapi -> swagger2, swagger -> unchanged). Supports YAML source URLs (e.g. .yaml / .yml); uses confbox for parsing (same as undocs).
+
+**Example:**
+
+```ts
+await original(configRead)
+// configRead.source is set from uri/http/json; wpapi transformed to swagger2 if parser is 'wpapi'
+```
+
+### `formatTypescript(code, options?)`
+
+Formats TypeScript/JavaScript code string with Prettier.
+
+**Example:**
+
+```ts
+const formatted = await formatTypescript('const x=1')
+```
+
+<!-- /automd -->
+
+## License
+
+[MIT](https://github.com/hairyf/genapi/blob/main/LICENSE)
+
+<!-- automd:with-automd -->
+
+---
+
+_🤖 auto updated with [automd](https://automd.unjs.io)_
+
+<!-- /automd -->

package/dist/index.d.mts

@@ -3,14 +3,17 @@ import { ApiPipeline } from "@genapi/shared";
 //#region src/pipeline/index.d.ts
 /**
  * Pipeline read (input) step: turns raw config into internal config + inputs.
+ * @description First step: normalizes user config and builds ConfigRead (inputs, outputs, graphs).
  */
 type PipelineRead<Config, ConfigRead> = (config: Config) => ConfigRead | Promise<ConfigRead>;
 /**
  * Middle step that receives and returns config read; used for original, parser, compiler, generate.
+ * @description Each step may mutate configRead (e.g. set source, graphs, output.code).
  */
 type PipelineFlow<ConfigRead> = (configRead: ConfigRead) => ConfigRead | Promise<ConfigRead>;
 /**
  * Pipeline dest (output) step: writes files from config read.
+ * @description Last step: writes configRead.outputs[].code to configRead.outputs[].path.
  */
 type PipelineDest<ConfigRead> = (configRead: ApiPipeline.ConfigRead) => void | Promise<void>;
 /**
@@ -24,6 +27,11 @@ type PipelineDest<ConfigRead> = (configRead: ApiPipeline.ConfigRead) => void | P
  * @param dest - Writes output files
  * @returns A function that runs the pipeline for a given config
  * @group Pipeline
+ * @example
+ * ```ts
+ * const run = pipeline(config, original, parser, compiler, generate, dest)
+ * await run(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+ * ```
  */
 declare function pipeline<Config = ApiPipeline.Config, ConfigRead = ApiPipeline.ConfigRead>(config: PipelineRead<Config, ConfigRead>, original: PipelineFlow<ConfigRead>, parser: PipelineFlow<ConfigRead>, compiler: PipelineFlow<ConfigRead>, generate: PipelineFlow<ConfigRead>, dest: PipelineDest<ConfigRead>): ApiPipeline.Pipeline;
 declare namespace pipeline {
@@ -35,20 +43,17 @@ declare namespace pipeline {
   var dest: typeof dest;
 }
 //#endregion
-//#region src/compiler/request.d.ts
-declare function compilerTsRequestDeclaration(configRead: ApiPipeline.ConfigRead): string;
-//#endregion
-//#region src/compiler/typings.d.ts
+//#region src/compiler/scope.d.ts
 /**
- * Compiles configRead graphs to typings code string using knitwork-x.
+ * 统一编译：按 scope 从 graphs.scopes[scope] 生成一段完整 TS 代码（comments → imports → variables → functions → typings → interfaces）。
  */
-declare function compilerTsTypingsDeclaration(configRead: ApiPipeline.ConfigRead, comment?: boolean): string;
+declare function compile(configRead: ApiPipeline.ConfigRead, scope: string): string;
 //#endregion
 //#region src/compiler/index.d.ts
 /**
- * Compiles graphs to code string: request and typings for each output.
+ * Compiles each output from graphs.scopes[output.type]; onlyDeclaration 时仅编译 type 为 "type" 的 output。
  *
- * @param configRead - ConfigRead with graphs and outputs
+ * @param configRead - ConfigRead with graphs.scopes and outputs
  * @returns Same configRead with output.code set
  * @group Pipeline
  */
@@ -61,6 +66,10 @@ declare function compiler(configRead: ApiPipeline.ConfigRead): ApiPipeline.Confi
  * @param userConfig - Raw config from defineConfig
  * @returns ConfigRead (config + inputs + outputs)
  * @group Pipeline
+ * @example
+ * ```ts
+ * const configRead = config(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+ * ```
  */
 declare function config(userConfig: ApiPipeline.Config): ApiPipeline.ConfigRead<Required<ApiPipeline.Config>>;
 //#endregion
@@ -70,6 +79,11 @@ declare function config(userConfig: ApiPipeline.Config): ApiPipeline.ConfigRead<
  *
  * @param configRead - ConfigRead with outputs[].path and outputs[].code
  * @group Pipeline
+ * @example
+ * ```ts
+ * await dest(configRead)
+ * // Writes configRead.outputs[].code to configRead.outputs[].path
+ * ```
  */
 declare function dest(configRead: ApiPipeline.ConfigRead): Promise<void>;
 //#endregion
@@ -80,8 +94,24 @@ declare function dest(configRead: ApiPipeline.ConfigRead): Promise<void>;
  * @param configRead - ConfigRead with outputs[].code
  * @returns Same configRead with outputs[].code formatted
  * @group Pipeline
+ * @example
+ * ```ts
+ * await generate(configRead)
+ * await generate(configRead, { printWidth: 100 })
+ * ```
  */
 declare function generate(configRead: ApiPipeline.ConfigRead, options?: any): Promise<ApiPipeline.ConfigRead<ApiPipeline.Config>>;
+/**
+ * Formats TypeScript/JavaScript code string with Prettier.
+ *
+ * @param code - Source code to format
+ * @param options - Prettier options (merged with parser: 'typescript', printWidth: 800)
+ * @returns Formatted code string
+ * @example
+ * ```ts
+ * const formatted = await formatTypescript('const x=1')
+ * ```
+ */
 declare function formatTypescript(code: string, options?: any): Promise<string>;
 //#endregion
 //#region src/original/index.d.ts
@@ -93,7 +123,12 @@ declare function formatTypescript(code: string, options?: any): Promise<string>;
  * @param configRead - ConfigRead with inputs (uri, http, or json)
  * @returns Same configRead with source set and transformed if needed
  * @group Pipeline
+ * @example
+ * ```ts
+ * await original(configRead)
+ * // configRead.source is set from uri/http/json; wpapi transformed to swagger2 if parser is 'wpapi'
+ * ```
  */
 declare function original(configRead: ApiPipeline.ConfigRead): Promise<ApiPipeline.ConfigRead<ApiPipeline.Config>>;
 //#endregion
-export { type PipelineDest, type PipelineFlow, type PipelineRead, compiler, compilerTsRequestDeclaration, compilerTsTypingsDeclaration, config, pipeline as default, dest, formatTypescript, generate, original };
+export { type PipelineDest, type PipelineFlow, type PipelineRead, compile, compiler, config, pipeline as default, dest, formatTypescript, generate, original };

package/dist/index.mjs

@@ -9,73 +9,9 @@ import { wpapiToSwagger2 } from "@genapi/transform";
 import { parseYAML } from "confbox";
 import { ofetch } from "ofetch";
 
-//#region src/compiler/typings.ts
-/**
-* Compiles configRead graphs to typings code string using knitwork-x.
-*/
-function compilerTsTypingsDeclaration(configRead, comment = true) {
-	configRead.graphs.comments = configRead.graphs.comments || [];
-	configRead.graphs.typings = configRead.graphs.typings || [];
-	configRead.graphs.interfaces = configRead.graphs.interfaces || [];
-	const sections = [];
-	if (comment && configRead.graphs.comments.length > 0) sections.push(genComment(configRead.graphs.comments.join("\n"), { block: true }));
-	const typings = configRead.graphs.typings.map((item) => {
-		return genTypeAlias(item.name, item.value, { export: !!item.export });
-	});
-	if (typings.length > 0) sections.push(typings.join("\n"));
-	const interfaces = configRead.graphs.interfaces.map((item) => {
-		const properties = (item.properties || []).map((p) => ({
-			name: p.name,
-			type: p.type ?? "any",
-			optional: !p.required,
-			jsdoc: p.description
-		}));
-		return genInterface(item.name, properties, { export: !!item.export });
-	});
-	if (interfaces.length > 0) sections.push(interfaces.join("\n"));
-	return sections.filter(Boolean).join("\n\n");
-}
-
-//#endregion
-//#region src/compiler/request.ts
-function compilerTsRequestDeclaration(configRead) {
-	const { graphs, config, outputs } = configRead;
-	const sections = [];
-	const interfaceMap = new Map((graphs.interfaces || []).map((i) => [i.name, i]));
-	if (graphs.comments?.length) sections.push(genComment(graphs.comments.join("\n"), { block: true }));
-	const importLines = (graphs.imports || []).map((item) => {
-		const isType = !!item.type;
-		if (item.namespace) return genImport(item.value, {
-			name: "*",
-			as: item.name
-		}, { type: isType });
-		if (item.name && !item.names) return genImport(item.value, item.name, { type: isType });
-		const names = item.names || [];
-		const imports = item.name ? [{
-			name: "default",
-			as: item.name
-		}, ...names.map((n) => ({ name: n }))] : names;
-		return genImport(item.value, imports, { type: isType });
-	});
-	if (config.meta?.mockjs) importLines.push(genImport("better-mock", { name: "Mock" }));
-	if (importLines.length) sections.push(importLines.join("\n"));
-	const variables = (graphs.variables || []).map((item) => genVariable(item.name, item.value ?? "", {
-		export: !!item.export,
-		kind: item.flag
-	}));
-	if (variables.length) sections.push(variables.join("\n"));
-	const functions = genFunctionsWithMock(graphs.functions || [], interfaceMap, config);
-	if (functions.length) sections.push(functions.join("\n\n"));
-	const isGenerateType = outputs.some((v) => v.type === "typings");
-	const isTsRequest = outputs.some((v) => v.type === "request" && v.path.endsWith(".ts"));
-	if (!isGenerateType && isTsRequest) sections.push(compilerTsTypingsDeclaration(configRead, false));
-	return sections.filter(Boolean).join("\n\n");
-}
+//#region src/compiler/scope.ts
 const RE_NAMESPACE = /^(Types\.|import\(['"][^'"]+['"]\)\.)/g;
 const RE_ARRAY_TYPE = /^(.+)\[\]$/;
-/**
-* 优化后的 Mock 模板生成函数
-*/
 function generateMockTemplate(typeName, interfaceMap, visited = /* @__PURE__ */ new Set()) {
 	const cleanTypeName = typeName.replace(RE_NAMESPACE, "").trim();
 	const arrayMatch = cleanTypeName.match(RE_ARRAY_TYPE);
@@ -100,16 +36,15 @@ function generateMockTemplate(typeName, interfaceMap, visited = /* @__PURE__ */
 			const itemTemplate = generateMockTemplate(propType.slice(0, -2), interfaceMap, nextVisited);
 			return `'${prop.name}|1-5': ${itemTemplate}`;
 		}
-		const innerTemplate = generateMockTemplate(propType, interfaceMap, nextVisited);
-		return `'${prop.name}': ${innerTemplate}`;
+		return `'${prop.name}': ${generateMockTemplate(propType, interfaceMap, nextVisited)}`;
 	});
 	visited.delete(cleanTypeName);
 	return properties.length > 0 ? `{\n    ${properties.join(",\n    ")}\n  }` : "{}";
 }
 function genFunctionsWithMock(functions, interfaceMap, config) {
 	const functionBlocks = [];
-	(functions || []).forEach((item) => {
-		const functionCode = genFunction({
+	for (const item of functions || []) {
+		functionBlocks.push(genFunction({
 			export: true,
 			name: item.name,
 			parameters: (item.parameters || []).map((p) => ({
@@ -122,29 +57,90 @@ function genFunctionsWithMock(functions, interfaceMap, config) {
 			returnType: item.returnType,
 			generics: item.generics,
 			jsdoc: item.description
-		});
-		functionBlocks.push(functionCode);
+		}));
 		const responseType = inject(item.name)?.responseType;
-		if (!config.meta?.mockjs || !responseType || responseType === "void" || responseType === "any") return;
-		const mockTemplate = generateMockTemplate(responseType, interfaceMap);
-		functionBlocks.push(`${item.name}.mock = () => Mock.mock(${mockTemplate});`);
-	});
+		if (config.meta?.mockjs && responseType && responseType !== "void" && responseType !== "any") {
+			const mockTemplate = generateMockTemplate(responseType, interfaceMap);
+			functionBlocks.push(`${item.name}.mock = () => Mock.mock(${mockTemplate});`);
+		}
+	}
 	return functionBlocks;
 }
+function emptySlice() {
+	return {
+		comments: [],
+		functions: [],
+		imports: [],
+		variables: [],
+		typings: [],
+		interfaces: []
+	};
+}
+function varFiledToRaw(name) {
+	if (name.length >= 2 && name.startsWith("'") && name.endsWith("'")) return name.slice(1, -1);
+	return name;
+}
+/**
+* 统一编译：按 scope 从 graphs.scopes[scope] 生成一段完整 TS 代码（comments → imports → variables → functions → typings → interfaces）。
+*/
+function compile(configRead, scope) {
+	const slice = configRead.graphs.scopes[scope] ?? emptySlice();
+	const { config } = configRead;
+	const sections = [];
+	if (slice.comments?.length) sections.push(genComment(slice.comments.join("\n"), { block: true }));
+	const importLines = (slice.imports || []).map((item) => {
+		const isType = !!item.type;
+		if (item.namespace) return genImport(item.value, {
+			name: "*",
+			as: item.name
+		}, { type: isType });
+		if (item.name && !item.names) return genImport(item.value, item.name, { type: isType });
+		const names = item.names || [];
+		const imports = item.name ? [{
+			name: "default",
+			as: item.name
+		}, ...names.map((n) => ({ name: n }))] : names;
+		return genImport(item.value, imports, { type: isType });
+	});
+	if (config.meta?.mockjs) importLines.push(genImport("better-mock", { name: "Mock" }));
+	if (importLines.length) sections.push(importLines.join("\n"));
+	const variables = (slice.variables || []).map((item) => genVariable(item.name, item.value ?? "", {
+		export: !!item.export,
+		kind: item.flag
+	}));
+	if (variables.length) sections.push(variables.join("\n"));
+	const interfaceMap = new Map((slice.interfaces || []).map((i) => [i.name, i]));
+	const functions = genFunctionsWithMock(slice.functions || [], interfaceMap, config);
+	if (functions.length) sections.push(functions.join("\n\n"));
+	const typings = (slice.typings || []).map((item) => genTypeAlias(item.name, item.value, { export: !!item.export }));
+	if (typings.length) sections.push(typings.join("\n"));
+	const interfaces = (slice.interfaces || []).map((item) => {
+		const properties = (item.properties || []).map((p) => ({
+			name: varFiledToRaw(p.name),
+			type: p.type ?? "any",
+			optional: !p.required,
+			jsdoc: p.description
+		}));
+		return genInterface(item.name, properties, { export: !!item.export });
+	});
+	if (interfaces.length) sections.push(interfaces.join("\n"));
+	return sections.filter(Boolean).join("\n\n");
+}
 
 //#endregion
 //#region src/compiler/index.ts
 /**
-* Compiles graphs to code string: request and typings for each output.
+* Compiles each output from graphs.scopes[output.type]; onlyDeclaration 时仅编译 type 为 "type" 的 output。
 *
-* @param configRead - ConfigRead with graphs and outputs
+* @param configRead - ConfigRead with graphs.scopes and outputs
 * @returns Same configRead with output.code set
 * @group Pipeline
 */
 function compiler(configRead) {
+	const onlyDeclaration = !!configRead.config.meta?.onlyDeclaration;
 	for (const output of configRead.outputs) {
-		if (output.type === "request" && !configRead.config.meta?.onlyDeclaration) output.code = compilerTsRequestDeclaration(configRead);
-		if (output.type === "typings") output.code = compilerTsTypingsDeclaration(configRead);
+		if (onlyDeclaration && output.type !== "type") continue;
+		output.code = compile(configRead, output.type);
 	}
 	return configRead;
 }
@@ -157,6 +153,10 @@ function compiler(configRead) {
 * @param userConfig - Raw config from defineConfig
 * @returns ConfigRead (config + inputs + outputs)
 * @group Pipeline
+* @example
+* ```ts
+* const configRead = config(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+* ```
 */
 function config(userConfig) {
 	userConfig.meta = userConfig.meta || {};
@@ -172,28 +172,40 @@ function config(userConfig) {
 	const isTypescript = userConfig.output.main.endsWith(".ts");
 	const isGenerateType = userConfig.output?.type !== false;
 	const importTypePath = userConfig.meta.import.type || getImportTypePath(userConfig.output.main, userConfig.output.type || "");
-	const imports = [isTypescript && isGenerateType && {
-		name: "Types",
-		value: importTypePath,
-		type: true,
-		namespace: true
-	}];
-	const outputs = [{
-		type: "request",
-		root: path.join(userRoot, path.dirname(userConfig.output.main)),
-		path: path.join(userRoot, userConfig.output.main)
-	}];
-	const typings = [!!userConfig.meta.responseType?.infer && {
-		export: true,
-		name: "Infer<T>",
-		value: userConfig.meta.responseType.infer
-	}];
-	if (userConfig.output.type !== false) outputs.push({
-		type: "typings",
-		root: path.join(userRoot, path.dirname(userConfig.output.type)),
-		import: importTypePath,
-		path: path.join(userRoot, userConfig.output.type)
-	});
+	const outputs = [];
+	const scopes = {};
+	const outputKeys = [
+		"main",
+		...userConfig.output.type !== false ? ["type"] : [],
+		...objectOutputKeys(userConfig.output)
+	];
+	for (const key of outputKeys) {
+		const outPath = key === "main" ? userConfig.output.main : key === "type" ? userConfig.output.type : userConfig.output[key];
+		if (typeof outPath !== "string") continue;
+		outputs.push({
+			type: key,
+			root: path.join(userRoot, path.dirname(outPath)),
+			path: path.join(userRoot, outPath),
+			...key === "type" ? { import: importTypePath } : {}
+		});
+		scopes[key] = {
+			comments: [],
+			functions: [],
+			imports: key === "main" && isTypescript && isGenerateType ? [{
+				name: "Types",
+				value: importTypePath,
+				type: true,
+				namespace: true
+			}] : [],
+			variables: [],
+			typings: key === "type" && userConfig.meta.responseType?.infer ? [{
+				export: true,
+				name: "Infer<T>",
+				value: userConfig.meta.responseType.infer
+			}] : [],
+			interfaces: []
+		};
+	}
 	const inputs = {};
 	if (typeof userConfig.input === "string") inputs.uri = userConfig.input;
 	if (typeof userConfig.input === "object") Object.assign(inputs, userConfig.input);
@@ -202,21 +214,43 @@ function config(userConfig) {
 		inputs,
 		outputs,
 		graphs: {
-			imports: imports.filter(Boolean),
-			variables: [],
-			comments: [],
-			functions: [],
-			interfaces: [],
-			typings: typings.filter(Boolean),
+			scopes,
 			response: userConfig.meta.responseType
 		}
 	};
 	provide({
 		config: userConfig,
-		configRead
+		configRead,
+		imports: block(configRead, "imports")
 	});
 	return configRead;
 }
+function block(configRead, key) {
+	return {
+		add(scope, item) {
+			let slice = configRead.graphs.scopes[scope];
+			if (!slice) {
+				slice = {
+					comments: [],
+					functions: [],
+					imports: [],
+					variables: [],
+					typings: [],
+					interfaces: []
+				};
+				configRead.graphs.scopes[scope] = slice;
+			}
+			if (Array.isArray(slice[key])) slice[key].push(item);
+		},
+		values(scope) {
+			const slice = configRead.graphs.scopes[scope];
+			return slice && Array.isArray(slice[key]) ? slice[key] : [];
+		},
+		all() {
+			return Object.values(configRead.graphs.scopes).flatMap((s) => s[key] || []);
+		}
+	};
+}
 function prefix(path) {
 	return path.startsWith(".") ? path : `./${path}`;
 }
@@ -226,6 +260,11 @@ function getImportTypePath(main, type) {
 	importTypePath = prefix(importTypePath).replace(".ts", "");
 	return importTypePath;
 }
+/** 从 output 对象中取除 main/type 外的 key（如 api），且值为 string 的 */
+function objectOutputKeys(output) {
+	if (typeof output !== "object" || output == null) return [];
+	return Object.keys(output).filter((k) => k !== "main" && k !== "type" && typeof output[k] === "string");
+}
 
 //#endregion
 //#region src/dest/index.ts
@@ -234,6 +273,11 @@ function getImportTypePath(main, type) {
 *
 * @param configRead - ConfigRead with outputs[].path and outputs[].code
 * @group Pipeline
+* @example
+* ```ts
+* await dest(configRead)
+* // Writes configRead.outputs[].code to configRead.outputs[].path
+* ```
 */
 async function dest(configRead) {
 	await Promise.all(configRead.outputs.map(async (output) => {
@@ -250,11 +294,27 @@ async function dest(configRead) {
 * @param configRead - ConfigRead with outputs[].code
 * @returns Same configRead with outputs[].code formatted
 * @group Pipeline
+* @example
+* ```ts
+* await generate(configRead)
+* await generate(configRead, { printWidth: 100 })
+* ```
 */
 async function generate(configRead, options) {
 	for (const output of configRead.outputs || []) if (output.code) output.code = await formatTypescript(output.code, options);
 	return configRead;
 }
+/**
+* Formats TypeScript/JavaScript code string with Prettier.
+*
+* @param code - Source code to format
+* @param options - Prettier options (merged with parser: 'typescript', printWidth: 800)
+* @returns Formatted code string
+* @example
+* ```ts
+* const formatted = await formatTypescript('const x=1')
+* ```
+*/
 async function formatTypescript(code, options) {
 	return await format(code, {
 		printWidth: 800,
@@ -289,6 +349,11 @@ async function fetchSource(url, options) {
 * @param configRead - ConfigRead with inputs (uri, http, or json)
 * @returns Same configRead with source set and transformed if needed
 * @group Pipeline
+* @example
+* ```ts
+* await original(configRead)
+* // configRead.source is set from uri/http/json; wpapi transformed to swagger2 if parser is 'wpapi'
+* ```
 */
 async function original(configRead) {
 	if (configRead.inputs.uri) configRead.source = await fetchSource(configRead.inputs.uri);
@@ -329,6 +394,11 @@ function readJsonSource(json) {
 * @param dest - Writes output files
 * @returns A function that runs the pipeline for a given config
 * @group Pipeline
+* @example
+* ```ts
+* const run = pipeline(config, original, parser, compiler, generate, dest)
+* await run(defineConfig({ input: 'openapi.json', output: { main: 'src/api.ts' } }))
+* ```
 */
 function pipeline(config, original, parser, compiler, generate, dest) {
 	return pPipe(config, original, parser, compiler, generate, dest);
@@ -345,4 +415,4 @@ pipeline.dest = dest;
 var src_default = pipeline;
 
 //#endregion
-export { compiler, compilerTsRequestDeclaration, compilerTsTypingsDeclaration, config, src_default as default, dest, formatTypescript, generate, original };
+export { compile, compiler, config, src_default as default, dest, formatTypescript, generate, original };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genapi/pipeline",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "author": "Hairyf <wwu710632@gmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/hairyf/genapi#readme",
@@ -26,12 +26,12 @@
   "dependencies": {
     "confbox": "^0.2.4",
     "fs-extra": "^11.3.3",
-    "knitwork-x": "^0.2.0",
+    "knitwork-x": "^0.3.1",
     "ofetch": "^1.5.1",
     "p-pipe": "^4.0.0",
     "prettier": "^3.8.1",
-    "@genapi/shared": "4.0.0",
-    "@genapi/transform": "4.0.0"
+    "@genapi/shared": "4.1.0",
+    "@genapi/transform": "4.1.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",