wormajs 0.1.0 → 0.2.1

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/functions/prepareConfig.js

@@ -12,6 +12,10 @@ function extendsConfig(config, newConfig) {
         }
         // handleApi is a special case, we need to merge the functions
         if (typeof newValue === 'function' && typeof srcValue === 'function') {
+            // Avoid chaining the same function reference with itself (idempotency guard).
+            if (newValue === srcValue) {
+                return newValue;
+            }
             // chain the functions
             return (...args) => {
                 const result = srcValue(...args);

package/dist/generate.js

@@ -19,12 +19,11 @@ async function generate(config, options) {
         return [];
     const projectPath = options?.projectPath ?? process.cwd();
     const emit = options?.onProgress;
-    // Load phase (shared, no per-gen events during load) — plugins may modify generator configs
-    helper_1.logger.debug('Loading config', { projectPath });
-    await helper_1.configHelper.load(config, projectPath);
-    // Use the processed generators from ConfigManager (after plugin hooks have run)
-    const generators = helper_1.configHelper.getConfig().generator;
-    helper_1.logger.debug('Config loaded', { generatorCount: generators.length });
+    // Each generate() call creates its own ConfigHelper / ConfigManager,
+    // so multiple concurrent calls never share mutable config state.
+    const helper = new helper_1.ConfigHelper();
+    await helper.load(config, projectPath);
+    const generators = helper.getConfig().generator;
     // Run all generators in parallel, each with its own ProgressTracker
     const results = await Promise.all(generators.map(async (gen, i) => {
         const generatorName = gen.input || `generator-${i}`;

package/dist/helper/config/ConfigHelper.js

@@ -1,30 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configHelper = exports.ConfigHelper = void 0;
+exports.ConfigHelper = void 0;
 const lodash_1 = require("lodash");
 const helper_1 = require("../../helper");
-const logger_1 = require("../../helper/logger");
 const ConfigManager_1 = require("./ConfigManager");
 const GeneratorHelper_1 = require("./GeneratorHelper");
 class ConfigHelper {
     constructor() {
-        this.configManager = ConfigManager_1.ConfigManager.getInstance();
-    }
-    static getInstance() {
-        if (!ConfigHelper.instance) {
-            ConfigHelper.instance = new ConfigHelper();
-        }
-        return ConfigHelper.instance;
+        this.configManager = new ConfigManager_1.ConfigManager();
     }
     async load(config, projectPath = process.cwd(), tracker) {
         this.projectPath = projectPath;
-        logger_1.logger.debug('ConfigHelper.load — loading config manager', { projectPath, generatorCount: config.generator?.length ?? 0 });
         await this.configManager.load(config, projectPath, tracker);
-        logger_1.logger.debug('ConfigHelper.load — reading cache data');
         await this.readAlovaJson();
-        logger_1.logger.debug('ConfigHelper.load — complete');
     }
-    async readUserConfig(userConfig) {
+    static async readUserConfig(userConfig) {
         if (typeof userConfig === 'function') {
             return await userConfig();
         }
@@ -76,4 +66,3 @@ class ConfigHelper {
     }
 }
 exports.ConfigHelper = ConfigHelper;
-exports.configHelper = ConfigHelper.getInstance();

package/dist/helper/config/ConfigManager.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configManager = exports.ConfigManager = void 0;
+exports.ConfigManager = void 0;
 const zod_validation_error_1 = require("zod-validation-error");
 const prepareConfig_1 = __importDefault(require("../../functions/prepareConfig"));
 const GeneratorHelper_1 = require("../../helper/config/GeneratorHelper");
@@ -17,12 +17,6 @@ class ConfigManager {
         this.defaultGeneratorConfig = GeneratorHelper_1.generatorHelper.getDefaultConfig();
         this.config = this.defaultConfig;
     }
-    static getInstance() {
-        if (!ConfigManager.instance) {
-            ConfigManager.instance = new ConfigManager();
-        }
-        return ConfigManager.instance;
-    }
     /**
      * 加载并验证配置
      */
@@ -84,5 +78,3 @@ class ConfigManager {
     }
 }
 exports.ConfigManager = ConfigManager;
-// 导出单例实例
-exports.configManager = ConfigManager.getInstance();

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

@@ -1,8 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyModifierSchema = applyModifierSchema;
+// Detect a `SchemaOptional` wrapper: { required: boolean, type: Schema }.
+// The `required` must be a literal boolean so a plain SchemaReference whose
+// property happens to be named "required" (e.g. { required: 'boolean' }) is not misread.
+function isSchemaOptional(val) {
+    return !!val
+        && typeof val === 'object'
+        && !Array.isArray(val)
+        && typeof val.required === 'boolean'
+        && 'type' in val;
+}
+// Collapse (possibly nested) `SchemaOptional` wrappers.
+// - The OUTERMOST `required` wins; inner `required` fields are ignored.
+// - A non-wrapped value defaults to required (required: true).
+function unwrapOptional(s) {
+    if (!isSchemaOptional(s)) {
+        return { required: true, type: s };
+    }
+    const required = s.required;
+    let type = s.type;
+    while (isSchemaOptional(type)) {
+        type = type.type;
+    }
+    return { required, type };
+}
+// Remove the internal `_$ref` marker that `removeAll$ref` stamps onto dereferenced
+// component schemas. When a handler replaces a schema, the result must NOT inherit the
+// original component's `_$ref` — otherwise `mergeObject`/`removeBaseReference` downstream
+// treats the replacement as a reference to the original component and discards the change.
+function stripInternalRef(schema) {
+    if (!schema || typeof schema !== 'object') {
+        return schema;
+    }
+    if (Array.isArray(schema)) {
+        return schema.map(stripInternalRef);
+    }
+    const out = {};
+    for (const key of Object.keys(schema)) {
+        if (key === '_$ref') {
+            continue;
+        }
+        out[key] = stripInternalRef(schema[key]);
+    }
+    return out;
+}
+// Set of valid SchemaPrimitive values for O(1) validation lookup
+const VALID_PRIMITIVES = new Set([
+    'number',
+    'string',
+    'boolean',
+    'undefined',
+    'null',
+    'unknown',
+    'any',
+    'never',
+]);
+function validatePrimitive(val) {
+    if (!VALID_PRIMITIVES.has(val)) {
+        throw new Error(`[payloadModifier] Invalid schema type "${val}". Must be one of: ${[...VALID_PRIMITIVES].join(', ')}`);
+    }
+}
 // Convert Schema (custom spec) -> OpenAPI SchemaObject
 function toSchemaObject(base, s) {
+    // A `SchemaOptional` wrapper only affects requiredness (handled by the caller);
+    // here we care about the type shape, so fully unwrap nested wrappers first.
+    if (isSchemaOptional(s)) {
+        s = unwrapOptional(s).type;
+    }
     const result = { ...base };
     const cleanType = (schema) => {
         delete schema.type;
@@ -15,15 +80,18 @@ 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
+    // Primitive types — validate against SchemaPrimitive set during conversion
     if (typeof s === 'string') {
+        validatePrimitive(s);
         result.type = s;
         return result;
     }
@@ -33,64 +101,68 @@ 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) {
         const spec = s;
         result.enum = spec.enum;
         if (spec.type) {
+            if (typeof spec.type === 'string') {
+                validatePrimitive(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) {
                 continue;
             }
-            const optional = key.endsWith('?');
-            const cleanKey = optional ? key.slice(0, -1) : key;
-            const baseProp = properties[cleanKey];
-            properties[cleanKey] = toSchemaObject(baseProp || {}, val);
-            if (optional) {
-                requiredSet.delete(cleanKey);
+            // SchemaOptional wrapper: optionality expressed via { required, type };
+            // bare value defaults to required. Nested wrappers are collapsed — outermost
+            // `required` wins, inner ones are ignored.
+            let isOptional;
+            let effectiveVal;
+            if (isSchemaOptional(val)) {
+                const { required, type } = unwrapOptional(val);
+                isOptional = !required;
+                effectiveVal = type;
+            }
+            else {
+                isOptional = false;
+                effectiveVal = val;
+            }
+            const baseProp = properties[key];
+            properties[key] = toSchemaObject(baseProp || {}, effectiveVal);
+            if (isOptional) {
+                requiredSet.delete(key);
             }
             else {
-                requiredSet.add(cleanKey);
+                requiredSet.add(key);
             }
         }
         result.properties = properties;
@@ -137,16 +209,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) {
@@ -155,12 +227,12 @@ function toSchemaSpec(obj) {
         const result = {};
         for (const key of Object.keys(properties)) {
             const spec = toSchemaSpec(properties[key]);
-            const finalKey = requiredSet.has(key) ? key : `${key}?`;
-            result[finalKey] = spec;
+            // Required fields are written bare; optional fields wrapped with SchemaOptional
+            result[key] = requiredSet.has(key) ? spec : { required: false, type: spec };
         }
         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);
@@ -169,27 +241,48 @@ function toSchemaSpec(obj) {
     return schemaTypeToPrimitiveType(obj.type);
 }
 // Replace whole schema based on handler result (used for params/pathParams)
-function applyModifierSchema(schema, config, { required }) {
+function applyModifierSchema(schema, config, { required, key }) {
     if (!schema || typeof schema !== 'object') {
-        return schema;
+        return { required, schema: schema };
     }
     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, key);
     if (!ret) {
         return {
             required,
-            value: null,
+            schema: null,
         };
     }
-    if (typeof ret === 'object' && 'required' in ret && 'value' in ret) {
+    // A returned SchemaOptional means changing requiredness (driven by the `type` field).
+    // Nested wrappers are collapsed: the outermost `required` wins, inner ones are ignored;
+    // `type` may be any Schema expression (primitive, object, array, union, ...).
+    if (isSchemaOptional(ret)) {
+        const { required: nextRequired, type } = unwrapOptional(ret);
+        let r = stripInternalRef(toSchemaObject(cloned, type));
+        // When handler explicitly sets required=false, propagate to object-level required array
+        // so all properties become nullable as semantically expected
+        if (!nextRequired && r && typeof r === 'object' && !Array.isArray(r)) {
+            const robj = r;
+            if (robj.type === 'object' && Array.isArray(robj.required) && robj.required.length > 0) {
+                r = { ...r, required: [] };
+            }
+        }
         return {
-            required: !!(ret.required ?? required),
-            value: toSchemaObject(cloned, ret.value),
+            required: nextRequired,
+            schema: r,
         };
     }
+    // Non-SchemaOptional return: handler explicitly provides a type value,
+    // so default to required=true (the handler had the chance to wrap with
+    // { required: false, type: ... } if it wanted to keep it optional).
+    const r = stripInternalRef(toSchemaObject(cloned, ret));
     return {
-        required,
-        value: toSchemaObject(cloned, ret),
+        required: true,
+        schema: r,
     };
 }

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

@@ -4,13 +4,58 @@ exports.payloadModifier = payloadModifier;
 const constant_1 = require("../../../constant");
 const utils_1 = require("../utils");
 const hepler_1 = require("./hepler");
-// Apply modifications to object properties (for data/response scopes)
+// Convert parameters of a specific type (query/path) into an object schema
+function parametersToSchema(parameters, type) {
+    if (!parameters || !Array.isArray(parameters)) {
+        return { type: 'object', properties: {}, required: [] };
+    }
+    const schema = { type: 'object', properties: {}, required: [] };
+    for (const param of parameters) {
+        if (param.in === type) {
+            ;
+            schema.properties[param.name] = param.schema;
+            if (param.required) {
+                ;
+                schema.required.push(param.name);
+            }
+        }
+    }
+    return schema;
+}
+// Convert an object schema back to parameters, keeping other types untouched
+function schemaToParameters(parameters, schema, type) {
+    if (!parameters || !Array.isArray(parameters)) {
+        return parameters;
+    }
+    if (!schema || typeof schema !== 'object' || !schema.properties) {
+        return parameters.filter(param => param.in !== type);
+    }
+    const requiredSet = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const newParameters = [];
+    for (const param of parameters) {
+        if (param.in !== type) {
+            newParameters.push(param);
+            continue;
+        }
+        const propSchema = schema.properties[param.name];
+        if (!propSchema) {
+            continue;
+        }
+        newParameters.push({
+            ...param,
+            schema: propSchema,
+            required: requiredSet.has(param.name),
+        });
+    }
+    return newParameters;
+}
+// Apply modifications to properties of an object schema (used when `match` is set)
 function modifySchemaProperties(schema, config) {
     if (!schema || typeof schema !== 'object') {
         return schema;
     }
     const targetSchema = { ...schema };
-    // union recursively
+    // recurse into union keywords
     if (Array.isArray(targetSchema.oneOf)) {
         targetSchema.oneOf = targetSchema.oneOf.map(item => modifySchemaProperties(item, config));
     }
@@ -20,7 +65,7 @@ function modifySchemaProperties(schema, config) {
     if (Array.isArray(targetSchema.allOf)) {
         targetSchema.allOf = targetSchema.allOf.map(item => modifySchemaProperties(item, config));
     }
-    // modify properties
+    // modify matched properties
     if (targetSchema.properties) {
         const props = { ...targetSchema.properties };
         let required = Array.isArray(targetSchema.required) ? [...targetSchema.required] : [];
@@ -28,13 +73,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), 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);
             }
@@ -44,56 +89,59 @@ function modifySchemaProperties(schema, config) {
     }
     return targetSchema;
 }
+// Apply modifications to matched parameters (used when `match` is set for params/pathParams)
 function modifyParameters(parameters, type, config) {
     if (!parameters || !Array.isArray(parameters)) {
         return parameters;
     }
     return parameters.map((param) => {
-        if (param.in === type) {
-            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 });
-            if (!schema) {
-                return null;
-            }
-            return {
-                ...param,
-                schema,
-                required,
-            };
+        if (param.in !== type || !(0, utils_1.isMatch)(param.name, config.match)) {
+            return param;
+        }
+        const { schema, required } = (0, hepler_1.applyModifierSchema)(param.schema, config, { required: !!param.required, key: param.name });
+        if (!schema) {
+            return null;
         }
-        return param;
+        return { ...param, schema, required };
     }).filter(item => item !== null);
 }
+// Apply config to a parameter scope (params or pathParams)
+function applyToParameters(parameters, type, config) {
+    if (!parameters)
+        return undefined;
+    if (config.match) {
+        return modifyParameters(parameters, type, config);
+    }
+    const schema = parametersToSchema(parameters, type);
+    const result = (0, hepler_1.applyModifierSchema)(schema, config, { required: false });
+    return schemaToParameters(parameters, result.schema, type);
+}
+// Apply config to a schema scope (data or response)
+function applyToSchemaField(schema, config) {
+    if (!schema)
+        return undefined;
+    if (config.match) {
+        return modifySchemaProperties(schema, config);
+    }
+    return (0, hepler_1.applyModifierSchema)(schema, config, { required: false }).schema ?? undefined;
+}
 function payloadModifierApiDescriptor(apiDescriptor, config) {
-    if (!apiDescriptor) {
+    if (!apiDescriptor)
         return null;
-    }
     const newDescriptor = { ...apiDescriptor };
     const { scope } = config;
     switch (scope) {
-        case constant_1.ModifierScope.PARAMS:
-            if (newDescriptor.parameters) {
-                newDescriptor.parameters = modifyParameters(newDescriptor.parameters, constant_1.ParameterIn.QUERY, config);
-            }
+        case 'params':
+            newDescriptor.parameters = applyToParameters(newDescriptor.parameters, constant_1.ParameterIn.QUERY, config);
             break;
-        case constant_1.ModifierScope.PATH_PARAMS:
-            if (newDescriptor.parameters) {
-                newDescriptor.parameters = modifyParameters(newDescriptor.parameters, constant_1.ParameterIn.PATH, config);
-            }
+        case 'pathParams':
+            newDescriptor.parameters = applyToParameters(newDescriptor.parameters, constant_1.ParameterIn.PATH, config);
             break;
-        case constant_1.ModifierScope.DATA:
-            if (newDescriptor.requestBody) {
-                newDescriptor.requestBody = modifySchemaProperties(newDescriptor.requestBody, config);
-            }
-            break;
-        case constant_1.ModifierScope.RESPONSE:
-            if (newDescriptor.responses) {
-                newDescriptor.responses = modifySchemaProperties(newDescriptor.responses, config);
-            }
+        case 'data':
+            newDescriptor.requestBody = applyToSchemaField(newDescriptor.requestBody, config);
             break;
-        default:
+        case 'response':
+            newDescriptor.responses = applyToSchemaField(newDescriptor.responses, config);
             break;
     }
     return newDescriptor;

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/dist/readConfig.js

@@ -34,7 +34,6 @@ async function readConfig(projectPath = process.cwd()) {
                 name: 'readConfig',
             });
         }
-        await helper_1.configHelper.load(config, projectPath);
         return config;
     }
     // 获取用户已安装的依赖
@@ -67,10 +66,8 @@ async function readConfig(projectPath = process.cwd()) {
     finally {
         await (0, promises_1.unlink)(outfile);
     }
-    const config = await helper_1.configHelper.readUserConfig(module.default || module);
-    // Read the cache file and save it
-    await helper_1.configHelper.load(config, projectPath);
-    return helper_1.configHelper.getConfig();
+    const config = await helper_1.ConfigHelper.readUserConfig(module.default || module);
+    return config;
 }
 /**
  * Get cached API docs. Cache is self-describing — no config needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wormajs",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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).
@@ -493,7 +497,7 @@ export declare const logger: Logger$1;
  * @param projectPath The project path where the configuration file is located. The default value is `process.cwd()`.
  * @returns a promise instance that contains configuration object.
  */
-export declare function readConfig(projectPath?: string): Promise<Readonly<Config>>;
+export declare function readConfig(projectPath?: string): Promise<Config>;
 /**
  * Get cached API docs. Cache is self-describing — no config needed.
  * In monorepo, pass ANY sub-package path; cache is always read from the unified cacheRoot.

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,31 @@ 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.
+ * Required properties are written directly; optional properties are wrapped
+ * with the `SchemaOptional` form `{ required: false, type: Schema }`
+ * (consistent with how a standalone optional primitive is represented).
  */
 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 +569,49 @@ 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 are wrapped with `SchemaOptional` ({ required: false, type: Schema });
+ *   a standalone optional primitive uses the same 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).
+	 * @param key the matched field key. When `match` is omitted, the whole scope object is passed to the handler
+	 *            once and `key` is `undefined`; when `match` is set, `key` is the matched field name for each call.
+	 * @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, key?: string) => 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.