wormajs 0.1.0 → 0.2.0

package/dist/constant.js

@@ -3,7 +3,7 @@
 // 枚举常量定义 — 统一管理项目中所有硬编码的字符串/数字常量
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FRAMEWORK_NAMES = exports.MODULE_TYPE_TO_KIND = exports.MODULE_TYPE_DIRS = exports.ModuleTypeDir = exports.PresetTemplateName = exports.TemplateSkipDir = exports.TemplatePlaceholder = exports.PluginName = exports.ModifierScope = exports.FilterScope = exports.RenameScope = exports.ParameterIn = exports.TEMPLATE_EXTENSIONS = exports.FileExtension = exports.FrameworkName = exports.ModuleKind = exports.PlatformTypeEnum = exports.ConfigTypeEnum = exports.TemplateTypeEnum = void 0;
+exports.FRAMEWORK_NAMES = exports.MODULE_TYPE_TO_KIND = exports.MODULE_TYPE_DIRS = exports.ModuleTypeDir = exports.PresetTemplateName = exports.TemplateSkipDir = exports.TemplatePlaceholder = exports.PluginName = exports.FilterScope = exports.RenameScope = exports.ParameterIn = exports.TEMPLATE_EXTENSIONS = exports.FileExtension = exports.FrameworkName = exports.ModuleKind = exports.PlatformTypeEnum = exports.ConfigTypeEnum = exports.TemplateTypeEnum = void 0;
 exports.getTypeFileExtension = getTypeFileExtension;
 /** 模板代码生成类型 */
 var TemplateTypeEnum;
@@ -86,14 +86,6 @@ var FilterScope;
     FilterScope["URL"] = "url";
     FilterScope["TAG"] = "tag";
 })(FilterScope || (exports.FilterScope = FilterScope = {}));
-/** 参数修改 scope 类型 */
-var ModifierScope;
-(function (ModifierScope) {
-    ModifierScope["PARAMS"] = "params";
-    ModifierScope["PATH_PARAMS"] = "pathParams";
-    ModifierScope["DATA"] = "data";
-    ModifierScope["RESPONSE"] = "response";
-})(ModifierScope || (exports.ModifierScope = ModifierScope = {}));
 /** 内建插件名称 */
 var PluginName;
 (function (PluginName) {

package/dist/core/parser/openApiParser/helper.js

@@ -13,7 +13,6 @@ const swagger2openapi_1 = __importDefault(require("swagger2openapi"));
 const poolManager_1 = require("../../../core/workerPool/poolManager");
 const helper_1 = require("../../../helper");
 const utils_1 = require("../../../utils");
-const supportedExtname = ['json', 'yaml'];
 function isSwagger2(data) {
     return !!data?.swagger;
 }
@@ -61,56 +60,72 @@ function convertSwagger2Async(data) {
         });
     });
 }
-// Parse local openapi files
-async function parseLocalFile(url, projectPath = process.cwd()) {
-    const [, extname] = /\.([^.]+)$/.exec(url) ?? [];
-    if (!supportedExtname.includes(extname)) {
-        throw helper_1.logger.throwError(`Unsupported file type: ${extname}`, {
-            url,
-            projectPath,
-        });
-    }
+// Read local openapi spec file as raw text
+async function fetchRawLocalFile(url, projectPath = process.cwd()) {
     const filePath = node_path_1.default.resolve(projectPath, url);
-    if (extname === 'yaml') {
-        return js_yaml_1.default.load(await promises_1.default.readFile(filePath, 'utf-8'));
-    }
-    // M6-C3: prefer async read, fallback to require() for environments where
-    // fs is mocked (e.g. memfs in tests) but the real file exists on disk
     try {
-        return JSON.parse(await promises_1.default.readFile(filePath, 'utf-8'));
+        return await promises_1.default.readFile(filePath, 'utf-8');
     }
     catch {
-        // Fallback: use require() which bypasses fs mocks to reach real disk
+        // M6-C3: fallback to require() for environments where fs is mocked
+        // (e.g. memfs in tests) but the real file exists on disk. Limited to JSON.
         // eslint-disable-next-line ts/no-require-imports
-        return require(filePath);
+        return JSON.stringify(require(filePath), null, 2);
     }
 }
-// Parse remote openapi files
-async function parseRemoteFile(url, fetchOptions) {
-    const dataText = (await (0, utils_1.fetchData)(url, fetchOptions)) ?? '';
-    let data;
-    try {
-        // 尝试解析为 JSON 格式
-        data = JSON.parse(dataText);
+// Fetch remote openapi spec as raw text
+async function fetchRawRemoteFile(url, fetchOptions) {
+    return (await (0, utils_1.fetchData)(url, fetchOptions)) ?? '';
+}
+const isRemoteUrl = (u) => /^https?:\/\//.test(u);
+/**
+ * Fetch the raw spec text (JSON/YAML) from the first URL that succeeds.
+ * Returns the raw text together with the resolved URL; throws if all URLs fail.
+ */
+async function fetchRawText(urls, options) {
+    if (urls.length === 0) {
+        throw helper_1.logger.throwError('No URLs provided to fetch OpenAPI document');
     }
-    catch (jsonError) {
-        try {
-            // 若 JSON 解析失败，尝试解析为 YAML 格式
-            data = js_yaml_1.default.load(dataText);
-        }
-        catch (yamlError) {
-            throw helper_1.logger.throwError(`Only JSON and YAML formats are supported. Parsing failed:
-        ${jsonError instanceof Error ? jsonError.message : String(jsonError)}
-        ${yamlError instanceof Error ? yamlError.message : String(yamlError)}`, {
-                url,
-            });
-        }
+    const { projectPath, fetchOptions } = options;
+    // All URLs race in parallel: local files are fast, remote ones use network.
+    // Each task fetches the raw text AND validates that it is actually an OpenAPI/Swagger
+    // document before resolving. Invalid candidates (e.g. an HTML error page returned by
+    // a fallback URL) reject, so that Promise.any falls through to the next URL
+    // instead of resolving with garbage text.
+    const tasks = urls.map((u) => {
+        return (async () => {
+            const text = isRemoteUrl(u)
+                ? await fetchRawRemoteFile(u, fetchOptions)
+                : await fetchRawLocalFile(u, projectPath);
+            // Quick parse + validity check (full parse + Swagger2→OpenAPI3 conversion
+            // happens later in parseSpec, after beforeSpecParse may rewrite the text).
+            let probe;
+            try {
+                probe = JSON.parse(text);
+            }
+            catch (jsonError) {
+                try {
+                    probe = js_yaml_1.default.load(text);
+                }
+                catch (yamlError) {
+                    throw new Error(`${u}: ${(jsonError instanceof Error ? jsonError.message : String(jsonError))} (YAML: ${yamlError instanceof Error ? yamlError.message : String(yamlError)})`);
+                }
+            }
+            if (!isValidOpenApiData(probe)) {
+                throw new Error(`${u} did not yield a valid OpenAPI/Swagger document`);
+            }
+            return { text, url: u };
+        })();
+    });
+    try {
+        return await Promise.any(tasks);
     }
-    // Validate if the data is valid (prevent server from returning error responses)
-    if (!isValidOpenApiData(data)) {
-        throw new Error(`Data retrieved from URL ${url} is not a valid OpenAPI document`);
+    catch (err) {
+        const errors = (err instanceof AggregateError)
+            ? err.errors.map((e) => e.message)
+            : [err.message];
+        throw helper_1.logger.throwError(`Unable to retrieve valid OpenAPI document from any URL:\n${errors.join('\n')}`);
     }
-    return data;
 }
 // Validate OpenAPI data
 function isValidOpenApiData(data) {
@@ -124,49 +139,56 @@ function isValidOpenApiData(data) {
     // Check if it contains required OpenAPI/Swagger structure
     return !!(data.openapi || data.swagger || data.info || data.paths);
 }
-const isRemoteUrl = (u) => /^https?:\/\//.test(u);
 /**
- * Try all URLs in parallel (local & remote) — first successful one wins.
- * Returns the parsed data together with the resolved URL; throws if all URLs fail.
+ * Parse a raw spec string (JSON or YAML) into an OpenAPIDocument.
+ * Performs format auto-detection, validity checks, and Swagger2→OpenAPI3 conversion.
  */
-async function tryUrls(urls, options) {
-    if (urls.length === 0) {
-        throw helper_1.logger.throwError('No URLs provided to fetch OpenAPI document');
+async function parseSpec(text, url) {
+    let data;
+    try {
+        // Try to parse as JSON first
+        data = JSON.parse(text);
     }
-    const { projectPath, fetchOptions } = options;
-    // All URLs race in parallel: local files are fast, remote ones use network
-    const tasks = urls.map((u) => {
-        if (isRemoteUrl(u)) {
-            return parseRemoteFile(u, fetchOptions).then(data => ({ data, url: u }), (err) => {
-                throw new Error(`${u}: ${err instanceof Error ? err.message : String(err)}`);
+    catch (jsonError) {
+        try {
+            // Fall back to YAML (also covers JSON, since JSON is a subset of YAML)
+            data = js_yaml_1.default.load(text);
+        }
+        catch (yamlError) {
+            throw helper_1.logger.throwError(`Only JSON and YAML formats are supported. Parsing failed:
+        ${jsonError instanceof Error ? jsonError.message : String(jsonError)}
+        ${yamlError instanceof Error ? yamlError.message : String(yamlError)}`, {
+                url,
             });
         }
-        return parseLocalFile(u, projectPath).then(data => ({ data, url: u }));
-    });
-    try {
-        return await Promise.any(tasks);
     }
-    catch (err) {
-        const errors = (err instanceof AggregateError)
-            ? err.errors.map((e) => e.message)
-            : [err.message];
-        throw helper_1.logger.throwError(`Unable to retrieve valid OpenAPI document from any URL:\n${errors.join('\n')}`);
+    // Validate if the data is valid (prevent server from returning error responses)
+    if (!isValidOpenApiData(data)) {
+        throw new Error(`Data retrieved from URL ${url} is not a valid OpenAPI document`);
+    }
+    // If it is a swagger2 file — convert via worker to avoid main-thread blocking
+    if (isSwagger2(data)) {
+        data = await convertSwagger2Async(data);
     }
+    return data;
 }
 /**
  * Parse OpenAPI document and return the resolved URL alongside the data.
  * Use this when you need to know which URL actually provided the document.
+ *
+ * If `beforeSpecParse` is provided, it is invoked with the raw spec text once
+ * it has been fetched (but before parsing), and its returned string replaces
+ * the text that will be parsed.
  */
 async function getOpenApiDataWithUrl(url, options) {
-    const { projectPath, fetchOptions } = options ?? {};
+    const { projectPath, fetchOptions, beforeSpecParse } = options ?? {};
     // Normalize to array — single string or array both handled uniformly
     const urls = Array.isArray(url) ? url : [url];
-    const { data, url: resolvedUrl } = await tryUrls(urls, { projectPath, fetchOptions });
-    let result = data;
-    // If it is a swagger2 file — convert via worker to avoid main-thread blocking
-    if (isSwagger2(result)) {
-        result = await convertSwagger2Async(result);
-    }
+    const { text, url: resolvedUrl } = await fetchRawText(urls, { projectPath, fetchOptions });
+    // Allow the caller (e.g. a `beforeSpecParse` plugin hook) to transform the
+    // raw spec text before it is parsed into an OpenAPIDocument.
+    const finalText = (beforeSpecParse ? await beforeSpecParse(text) : text) ?? text;
+    const result = await parseSpec(finalText, resolvedUrl);
     if (!result) {
         throw helper_1.logger.throwError(`Cannot read file from ${urls.join(', ')}`, {
             projectPath,

package/dist/helper/config/GeneratorHelper.js

@@ -128,10 +128,11 @@ class GeneratorHelper {
             fetchOptions: config.fetchOptions,
         });
     }
-    static async openApiDataWithUrl(config, projectPath) {
+    static async openApiDataWithUrl(config, projectPath, opts) {
         return (0, helper_1.getOpenApiDataWithUrl)(config.input, {
             projectPath,
             fetchOptions: config.fetchOptions,
+            beforeSpecParse: opts?.beforeSpecParse,
         });
     }
     static async generate(config, { projectPath, force, tracker }) {
@@ -152,16 +153,17 @@ class GeneratorHelper {
         });
         reportCore(5, 'starting');
         const frozenConfig = Object.freeze(config);
-        // Plugin: handle before parse openapi
-        reportCore(10, 'beforeOpenapiParse');
-        helper_2.logger.debug('Running beforeOpenapiParse hook');
-        await pluginDriver.hookParallelEach('beforeOpenapiParse', () => ({
-            config: frozenConfig,
-            projectPath,
-        }));
+        reportCore(10, 'beforeSpecParse');
+        helper_2.logger.debug('Fetching and parsing OpenAPI document', { input: config.input });
         reportCore(20, 'parsing openapi document');
-        helper_2.logger.debug('Fetching OpenAPI document', { input: config.input });
-        const openApiResult = await this.openApiDataWithUrl(config, projectPath);
+        const openApiResult = await this.openApiDataWithUrl(config, projectPath, {
+            // Plugin: beforeSpecParse — receives the raw spec string, may return a modified string
+            beforeSpecParse: (spec) => pluginDriver.hookPipe('beforeSpecParse', spec, (_p, current, _ctx) => ({
+                config: frozenConfig,
+                spec: current,
+                projectPath,
+            })),
+        });
         let document = openApiResult.data;
         const resolvedInput = openApiResult.resolvedUrl;
         if (!document) {
@@ -174,10 +176,10 @@ class GeneratorHelper {
             version: document?.info?.version,
             paths: Object.keys(document?.paths || {}).length,
         });
-        reportCore(35, 'openapi parsed');
-        // Plugin: handle after parse openapi (openapiParsed)
-        helper_2.logger.debug('Running openapiParsed hook', { pluginCount });
-        const openapiParsed = await pluginDriver.hookSeqEach('openapiParsed', (_p, prevResult, _ctx) => {
+        reportCore(35, 'specParsed');
+        // Plugin: handle after parse openapi (specParsed)
+        helper_2.logger.debug('Running specParsed hook', { pluginCount });
+        const specParsed = await pluginDriver.hookSeqEach('specParsed', (_p, prevResult, _ctx) => {
             if (prevResult) {
                 document = prevResult;
             }
@@ -187,11 +189,11 @@ class GeneratorHelper {
                 projectPath,
             };
         });
-        if (openapiParsed) {
-            document = openapiParsed;
-            helper_2.logger.debug('openapiParsed hook modified document');
+        if (specParsed) {
+            document = specParsed;
+            helper_2.logger.debug('specParsed hook modified document');
         }
-        reportCore(45, 'openapiParsed');
+        reportCore(45, 'specParsed');
         const output = node_path_1.default.resolve(projectPath, config.output);
         const templateType = await GeneratorHelper.getTemplateType(config, projectPath);
         helper_2.logger.debug('Resolved output and template type', { output, templateType });

package/dist/helper/config/zType.js

@@ -26,8 +26,8 @@ exports.zFetchOptions = v3_1.z.record(v3_1.z.string(), v3_1.z.any());
 exports.zApiPlugin = v3_1.z.object({
     name: v3_1.z.string().optional(),
     config: v3_1.z.function().optional(),
-    beforeOpenapiParse: v3_1.z.function().optional(),
-    openapiParsed: v3_1.z.function().optional(),
+    beforeSpecParse: v3_1.z.function().optional(),
+    specParsed: v3_1.z.function().optional(),
     beforeCodeGenerate: v3_1.z.function().optional(),
     beforeFileWrite: v3_1.z.function().optional(),
     codeGenerated: v3_1.z.function().optional(),

package/dist/helper/progress.js

@@ -8,9 +8,9 @@ exports.CORE_PROGRESS_SOURCE = 'core';
  */
 exports.GeneratorStage = {
     INIT: 'init',
-    BEFORE_OPENAPI_PARSE: 'beforeOpenapiParse',
+    BEFORE_SPEC_PARSE: 'beforeSpecParse',
     PARSE_OPENAPI: 'parseOpenapi',
-    OPENAPI_PARSED: 'openapiParsed',
+    SPEC_PARSED: 'specParsed',
     TEMPLATE_LOADED: 'templateLoaded',
     TEMPLATE_DATA_PARSED: 'templateDataParsed',
     BEFORE_CODE_GENERATE: 'beforeCodeGenerate',

package/dist/plugins/presets/payloadModifier/hepler.js

@@ -15,11 +15,13 @@ function toSchemaObject(base, s) {
         delete schema.required;
         return schema;
     };
-    // Legacy union as array (treated as oneOf)
+    // Native array type (elements are Schema)
     if (Array.isArray(s)) {
-        const baseOneOf = base.oneOf || [];
+        const arr = s;
         cleanType(result);
-        result.oneOf = s.map((item, idx) => toSchemaObject(baseOneOf[idx] || {}, item));
+        result.type = 'array';
+        const items = arr.map(item => toSchemaObject({}, item));
+        result.items = (items.length === 1 ? items[0] : items);
         return result;
     }
     // Primitive types and no-op primitives
@@ -33,18 +35,21 @@ function toSchemaObject(base, s) {
         const baseOneOf = base.oneOf || [];
         cleanType(result);
         result.oneOf = spec.oneOf.map((item, idx) => toSchemaObject(baseOneOf[idx] || {}, item));
+        return result;
     }
     if (s.anyOf) {
         const spec = s;
         const baseAnyOf = base.anyOf || [];
         cleanType(result);
         result.anyOf = spec.anyOf.map((item, idx) => toSchemaObject(baseAnyOf[idx] || {}, item));
+        return result;
     }
     if (s.allOf) {
         const spec = s;
         const baseAllOf = base.allOf || [];
         cleanType(result);
         result.allOf = spec.allOf.map((item, idx) => toSchemaObject(baseAllOf[idx] || {}, item));
+        return result;
     }
     // Enum: set enum and optional type
     if (s.enum) {
@@ -53,30 +58,15 @@ function toSchemaObject(base, s) {
         if (spec.type) {
             result.type = spec.type;
         }
-    }
-    // Array: set/merge items
-    if (s.type === 'array') {
-        const spec = s;
-        result.type = 'array';
-        const baseItems = result.items;
-        if (Array.isArray(spec.items)) {
-            // Tuple items: replace entire items with tuple
-            const items = spec.items.map(item => toSchemaObject({}, item));
-            result.items = items;
-        }
-        else {
-            // Single items: merge into existing items schema
-            const patchItem = toSchemaObject(typeof baseItems === 'object' ? baseItems : {}, spec.items);
-            result.items = patchItem;
-        }
         return result;
     }
-    // Object (reference-like map): merge properties and required
+    // Object (reference-like map): replace properties and required with handler's spec
+    // (the SchemaReference returned by the handler fully replaces this field, only keeping scalar fields like description from base)
     const ref = s;
     if (ref && typeof ref === 'object') {
         result.type = 'object';
-        const properties = { ...result.properties };
-        const requiredSet = new Set(Array.isArray(result.required) ? result.required : []);
+        const properties = {};
+        const requiredSet = new Set();
         for (const key in ref) {
             const val = ref[key];
             if (!val) {
@@ -137,16 +127,16 @@ function toSchemaSpec(obj) {
         const type = typeof obj.type === 'string' ? obj.type : undefined;
         return { enum: obj.enum, type };
     }
-    // Array
+    // Array -> native array
     if (obj.type === 'array' || obj.items) {
         const items = obj.items;
         if (Array.isArray(items)) {
-            return { type: 'array', items: items.map((it) => toSchemaSpec(it)) };
+            return items.map((it) => toSchemaSpec(it));
         }
         if (items) {
-            return { type: 'array', items: toSchemaSpec(items) };
+            return [toSchemaSpec(items)];
         }
-        return { type: 'array', items: 'unknown' };
+        return ['unknown'];
     }
     // Object
     if (obj.type === 'object' || obj.properties) {
@@ -160,7 +150,7 @@ function toSchemaSpec(obj) {
         }
         return result;
     }
-    // type union as array
+    // type union as array -> oneOf
     if (Array.isArray(obj.type)) {
         const typeArr = obj.type;
         const mapped = typeArr.map(schemaTypeToPrimitiveType);
@@ -175,21 +165,27 @@ function applyModifierSchema(schema, config, { required }) {
     }
     const cloned = { ...schema };
     const currentSpec = toSchemaSpec(cloned);
-    const ret = config.handler(currentSpec);
+    // When the field is itself optional and is a primitive, wrap it as { required, type } before passing to handler
+    const handlerInput = (required === false && typeof currentSpec === 'string')
+        ? { required: false, type: currentSpec }
+        : currentSpec;
+    const ret = config.handler(handlerInput);
     if (!ret) {
         return {
             required,
-            value: null,
+            schema: null,
         };
     }
-    if (typeof ret === 'object' && 'required' in ret && 'value' in ret) {
+    // A returned { required, type } means changing requiredness (driven by the `type` field)
+    if (typeof ret === 'object' && !Array.isArray(ret) && 'required' in ret && 'type' in ret) {
+        const opt = ret;
         return {
-            required: !!(ret.required ?? required),
-            value: toSchemaObject(cloned, ret.value),
+            required: !!(opt.required ?? required),
+            schema: toSchemaObject(cloned, opt.type),
         };
     }
     return {
         required,
-        value: toSchemaObject(cloned, ret),
+        schema: toSchemaObject(cloned, ret),
     };
 }

package/dist/plugins/presets/payloadModifier/index.js

@@ -28,13 +28,13 @@ function modifySchemaProperties(schema, config) {
             if (!(0, utils_1.isMatch)(key, config.match)) {
                 continue;
             }
-            const { required: requiredOverride, value: valueSchema } = (0, hepler_1.applyModifierSchema)(props[key], config, { required: required.includes(key) });
+            const { required: requiredOverride, schema: schemaValue } = (0, hepler_1.applyModifierSchema)(props[key], config, { required: required.includes(key) });
             required = required.filter(r => r !== key);
-            if (!valueSchema) {
+            if (!schemaValue) {
                 delete props[key];
                 continue;
             }
-            props[key] = valueSchema;
+            props[key] = schemaValue;
             if (requiredOverride) {
                 required.push(key);
             }
@@ -53,7 +53,7 @@ function modifyParameters(parameters, type, config) {
             if (!(0, utils_1.isMatch)(param.name, config.match)) {
                 return param;
             }
-            const { value: schema, required } = (0, hepler_1.applyModifierSchema)(param.schema, config, { required: !!param.required });
+            const { schema, required } = (0, hepler_1.applyModifierSchema)(param.schema, config, { required: !!param.required });
             if (!schema) {
                 return null;
             }
@@ -73,22 +73,22 @@ function payloadModifierApiDescriptor(apiDescriptor, config) {
     const newDescriptor = { ...apiDescriptor };
     const { scope } = config;
     switch (scope) {
-        case constant_1.ModifierScope.PARAMS:
+        case 'params':
             if (newDescriptor.parameters) {
                 newDescriptor.parameters = modifyParameters(newDescriptor.parameters, constant_1.ParameterIn.QUERY, config);
             }
             break;
-        case constant_1.ModifierScope.PATH_PARAMS:
+        case 'pathParams':
             if (newDescriptor.parameters) {
                 newDescriptor.parameters = modifyParameters(newDescriptor.parameters, constant_1.ParameterIn.PATH, config);
             }
             break;
-        case constant_1.ModifierScope.DATA:
+        case 'data':
             if (newDescriptor.requestBody) {
                 newDescriptor.requestBody = modifySchemaProperties(newDescriptor.requestBody, config);
             }
             break;
-        case constant_1.ModifierScope.RESPONSE:
+        case 'response':
             if (newDescriptor.responses) {
                 newDescriptor.responses = modifySchemaProperties(newDescriptor.responses, config);
             }

package/dist/plugins/presets/rename.js

@@ -131,6 +131,8 @@ function renameUrl(url, config, apiDescriptor) {
  * Recursively processes a schema (supports nested objects and arrays),
  * applying property renaming to nested objects.
  * @param schema current schema
+ * @param config rename configuration
+ * @param apiDescriptor API descriptor
  * @param level current nesting level (starts from 0)
  * @param scopeLabel used to identify the scope in duplicate-name errors
  */
@@ -158,6 +160,9 @@ function transformSchema(schema, config, apiDescriptor, level, scopeLabel) {
 }
 /**
  * Transforms object properties using the renaming rules (supports deep recursive renaming)
+ * @param obj object whose properties to transform
+ * @param config rename configuration
+ * @param apiDescriptor API descriptor
  * @param level current nesting level (starts from 0), passed through to the match function
  * @param scopeLabel used to identify the scope in duplicate-name errors
  */

package/dist/plugins/presets/tagModifier.js

@@ -38,6 +38,10 @@ function processApiTags(apiDescriptor, handler) {
     // Process each tag and filter out null/undefined results
     newDescriptor.tags = newDescriptor.tags
         .map((tag) => {
+        // Resolve the tag to keep when the modification cannot be applied:
+        // keep the original tag only if it is itself valid, otherwise drop it.
+        // This guarantees that the final output never contains an invalid tag.
+        const keepOriginalOrDrop = () => isValidTagName(tag) ? tag : null;
         try {
             // Call user provided handler function
             const modifiedTag = handler(tag);
@@ -47,12 +51,12 @@ function processApiTags(apiDescriptor, handler) {
             }
             // Validate if modified tag follows naming conventions
             if (!isValidTagName(modifiedTag)) {
-                return tag; // Keep original tag if invalid
+                return keepOriginalOrDrop(); // Keep original tag if valid, otherwise drop
             }
             return modifiedTag.trim(); // Return trimmed modified tag
         }
         catch {
-            return tag; // Return original tag on error
+            return keepOriginalOrDrop(); // Keep original tag if valid, otherwise drop on error
         }
     })
         .filter((tag) => tag != null); // Filter out null/undefined values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wormajs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A modern OpenAPI code generator - Generate type-safe API clients from OpenAPI specs",
   "author": "worma",
   "license": "MIT",

package/typings/index.d.ts

@@ -54,12 +54,14 @@ export interface ConfigHookParams {
 	projectPath: string;
 	reportProgress: ReportProgress;
 }
-export interface BeforeOpenapiParseHookParams {
+export interface BeforeSpecParseHookParams {
 	config: Readonly<GeneratorConfig>;
+	/** The raw OpenAPI specification text (JSON or YAML), before it is parsed. */
+	spec: string;
 	projectPath: string;
 	reportProgress: ReportProgress;
 }
-export interface OpenapiParsedHookParams {
+export interface SpecParsedHookParams {
 	config: Readonly<GeneratorConfig>;
 	document: OpenAPIDocument;
 	projectPath: string;
@@ -140,14 +142,16 @@ export interface ApiPlugin {
 	 */
 	config?: (params: ConfigHookParams) => MaybePromise<GeneratorConfig | undefined | null | void>;
 	/**
-	 * Called before parsing the OpenAPI file.
+	 * Called after the raw OpenAPI spec text is fetched but before it is parsed.
+	 * Return a (possibly modified) string to replace the spec text that will be
+	 * parsed. Returning nothing keeps the original spec text.
 	 */
-	beforeOpenapiParse?: (params: BeforeOpenapiParseHookParams) => void;
+	beforeSpecParse?: (params: BeforeSpecParseHookParams) => MaybePromise<string | undefined | null | void>;
 	/**
 	 * Manipulate the openapi document after parsing.
 	 * Returning null does NOT replacing anything.
 	 */
-	openapiParsed?: (params: OpenapiParsedHookParams) => MaybePromise<OpenAPIDocument | undefined | null | void>;
+	specParsed?: (params: SpecParsedHookParams) => MaybePromise<OpenAPIDocument | undefined | null | void>;
 	/**
 	 * Called before code generation. Mutate `params.data` directly to inject
 	 * configuration data (no longer returns a value).

package/typings/plugins.d.ts

@@ -42,12 +42,14 @@ export interface ConfigHookParams {
 	projectPath: string;
 	reportProgress: ReportProgress;
 }
-export interface BeforeOpenapiParseHookParams {
+export interface BeforeSpecParseHookParams {
 	config: Readonly<GeneratorConfig>;
+	/** The raw OpenAPI specification text (JSON or YAML), before it is parsed. */
+	spec: string;
 	projectPath: string;
 	reportProgress: ReportProgress;
 }
-export interface OpenapiParsedHookParams {
+export interface SpecParsedHookParams {
 	config: Readonly<GeneratorConfig>;
 	document: OpenAPIDocument;
 	projectPath: string;
@@ -128,14 +130,16 @@ export interface ApiPlugin {
 	 */
 	config?: (params: ConfigHookParams) => MaybePromise<GeneratorConfig | undefined | null | void>;
 	/**
-	 * Called before parsing the OpenAPI file.
+	 * Called after the raw OpenAPI spec text is fetched but before it is parsed.
+	 * Return a (possibly modified) string to replace the spec text that will be
+	 * parsed. Returning nothing keeps the original spec text.
 	 */
-	beforeOpenapiParse?: (params: BeforeOpenapiParseHookParams) => void;
+	beforeSpecParse?: (params: BeforeSpecParseHookParams) => MaybePromise<string | undefined | null | void>;
 	/**
 	 * Manipulate the openapi document after parsing.
 	 * Returning null does NOT replacing anything.
 	 */
-	openapiParsed?: (params: OpenapiParsedHookParams) => MaybePromise<OpenAPIDocument | undefined | null | void>;
+	specParsed?: (params: SpecParsedHookParams) => MaybePromise<OpenAPIDocument | undefined | null | void>;
 	/**
 	 * Called before code generation. Mutate `params.data` directly to inject
 	 * configuration data (no longer returns a value).
@@ -529,36 +533,29 @@ export interface ImportTypeOptions {
 export declare function importType(imports: Record<string, string[]>, options?: {
 	files?: string[];
 }): ApiPlugin;
-declare enum ModifierScope {
-	PARAMS = "params",
-	PATH_PARAMS = "pathParams",
-	DATA = "data",
-	RESPONSE = "response"
-}
-export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never" | ({} & string);
+export type ModifierScope = "params" | "pathParams" | "data" | "response";
+export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never";
 /**
- * 表示数组类型
+ * Array type: a native JS array whose elements are Schemas.
+ * e.g. ['string'] means string[]; ['string', 'number'] means the tuple [string, number]
  */
-export interface SchemaArray {
-	type: "array";
-	items: Schema | Schema[];
-}
+export type SchemaArray = Schema[];
 /**
- * 修改参数为引用类型
- * 在key末端添加上?表示为可选值
+ * Object/reference type.
+ * Append '?' to the end of a key to mark it optional.
  */
 export interface SchemaReference {
 	[attr: string]: Schema;
 }
 /**
- * 枚举类型表示
+ * Enum type representation.
  */
 export interface SchemaEnum {
 	enum: Array<string | number | boolean | null>;
 	type?: SchemaPrimitive;
 }
 /**
- * 组合类型表示（与/或/交叉）
+ * Composite types (oneOf / anyOf / allOf).
  */
 export interface SchemaOneOf {
 	oneOf: Schema[];
@@ -570,31 +567,47 @@ export interface SchemaAllOf {
 	allOf: Schema[];
 }
 /**
- * 数据Schema
- * SchemaArray表示类型数组，而数组表示“或”的意思
+ * Standalone primitive type that is itself optional (driven by the `type` field).
+ * Used in handler input/output to mean "this field is optional / make it optional".
+ */
+export interface SchemaOptional {
+	required: boolean;
+	type: Schema;
+}
+/**
+ * The data Schema.
+ * - SchemaArray is a native array (elements are Schemas)
+ * - composite types use { oneOf | anyOf | allOf: Schema[] }
+ * - optional object properties use a trailing '?' on the key;
+ *   a standalone optional primitive uses the SchemaOptional wrapper
  */
-export type Schema = SchemaPrimitive | SchemaReference | SchemaArray | SchemaEnum | SchemaOneOf | SchemaAnyOf | SchemaAllOf | Array<SchemaPrimitive | SchemaReference | SchemaArray | SchemaEnum>;
-export interface ModifierConfig<T extends Schema> {
+export type Schema = SchemaPrimitive | SchemaReference | SchemaArray | SchemaEnum | SchemaOneOf | SchemaAnyOf | SchemaAllOf | SchemaOptional;
+export interface ModifierConfig {
 	/**
-	 * 生效范围，表示处理哪个位置的参数
+	 * The scope the modifier applies to (which parameter location to process).
 	 */
 	scope: ModifierScope;
 	/**
-	 * 匹配规则，只有匹配到的才会进行转换，不指定则转换全部
-	 * string：原参数名包含此string；RegExp：原参数名匹配此正则；函数时接收key并返回是否匹配的boolean值
+	 * Match rule. Only matched fields are transformed; when omitted, all fields are transformed.
+	 * - string: the original field name contains this string
+	 * - RegExp: the original field name matches this pattern
+	 * - function: receives the key and returns a boolean indicating a match
 	 */
 	match?: string | RegExp | ((key: string) => boolean);
 	/**
-	 * handler用于灵活修改参数类型值
-	 * @param schema Schema中的一种，由用户自行定义
-	 * @returns 返回多种参数，具体为：Schema表示修改的类型；{ required: boolean, value: Schema }表示可将当前值修改为是否必填；void | null | undefined表示移除当前字段
+	 * handler flexibly modifies the parameter type value.
+	 * @param schema the original field type, already converted to the user-facing Schema representation.
+	 *               When the field itself is optional and is a primitive, it is passed as { required: false, type: 'string' }.
+	 *               Narrow the type inside handler if needed (e.g. with a cast).
+	 * @returns Schema to change the type; { required: boolean, type: Schema } to change requiredness (driven by `type`);
+	 *          void | null | undefined to remove the field.
 	 */
-	handler: (schema: T) => Schema | {
+	handler: (schema: Schema) => Schema | {
 		required: boolean;
-		value: Schema;
+		type: Schema;
 	} | void | null | undefined;
 }
-export type PayloadModifierConfig = ModifierConfig<Schema>;
+export type PayloadModifierConfig = ModifierConfig;
 export declare function payloadModifier(configs: PayloadModifierConfig[]): ApiPlugin;
 /**
  * FastAPI platform plugin.