wormajs 0.4.0 → 1.0.0-beta.0

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

@@ -2,154 +2,140 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.payloadModifier = payloadModifier;
 const constant_1 = require("../../../constant");
+const logger_1 = require("../../../helper/logger");
 const utils_1 = require("../utils");
-const hepler_1 = require("./hepler");
-// 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 dsl_1 = require("./dsl");
+const patch_1 = require("./patch");
+const scope_1 = require("./scope");
+const LOG_TAG = '[payloadModifier]';
+/** Tests a value against one or more rules. No rule given = everything matches. */
+function matchRule(value, rule) {
+    if (rule === undefined) {
+        return true;
     }
-    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;
+    const rules = Array.isArray(rule) ? rule : [rule];
+    return rules.some(item => (0, utils_1.isMatch)(value, item));
 }
-// Convert an object schema back to parameters, keeping other types untouched
-function schemaToParameters(parameters, schema, type) {
-    if (!parameters || !Array.isArray(parameters)) {
-        return parameters;
+/** Tag dimension: any tag hitting any rule makes the config apply. */
+function matchTags(tags, rule) {
+    if (rule === undefined) {
+        return true;
     }
-    if (!schema || typeof schema !== 'object' || !schema.properties) {
-        return parameters.filter(param => param.in !== type);
+    if (!Array.isArray(tags) || tags.length === 0) {
+        return false;
     }
-    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;
+    return tags.some(tag => matchRule(tag, rule));
+}
+/** Interface filters are ANDed together. */
+function matchApi(apiDescriptor, config) {
+    return matchRule(apiDescriptor.url ?? '', config.path)
+        && matchTags(apiDescriptor.tags, config.tag);
+}
+/**
+ * Navigates an unwrap path. Only `properties` is followed, so array items are out of
+ * reach by design — use `handler` for those. Returns `undefined` when a segment is missing.
+ */
+function unwrapSchema(root, path) {
+    let node = root;
+    for (const segment of path.split('.')) {
+        if (!node || !node.properties) {
+            return undefined;
         }
-        newParameters.push({
-            ...param,
-            schema: propSchema,
-            required: requiredSet.has(param.name),
-        });
+        node = node.properties[segment];
     }
-    return newParameters;
+    return node;
 }
-// Apply modifications to properties of an object schema (used when `match` is set)
-function modifySchemaProperties(schema, config) {
-    if (!schema || typeof schema !== 'object') {
-        return schema;
+/** Runs patch then handler on a single located node. */
+function applyStages(node, key, config, warn) {
+    let result = { schema: node };
+    if ('patch' in config) {
+        result = (0, patch_1.applyFieldValue)(node, config.patch, { warn });
+        if (!result.schema) {
+            return result;
+        }
     }
-    const targetSchema = { ...schema };
-    // recurse into union keywords
-    if (Array.isArray(targetSchema.oneOf)) {
-        targetSchema.oneOf = targetSchema.oneOf.map(item => modifySchemaProperties(item, config));
+    if (config.handler) {
+        const handled = config.handler(result.schema, key);
+        return { schema: handled ? (0, dsl_1.stripRef)(handled) : null, required: result.required };
     }
-    if (Array.isArray(targetSchema.anyOf)) {
-        targetSchema.anyOf = targetSchema.anyOf.map(item => modifySchemaProperties(item, config));
+    return result;
+}
+function applyConfig(apiDescriptor, config) {
+    if (!apiDescriptor || !matchApi(apiDescriptor, config)) {
+        return apiDescriptor;
     }
-    if (Array.isArray(targetSchema.allOf)) {
-        targetSchema.allOf = targetSchema.allOf.map(item => modifySchemaProperties(item, config));
+    const warn = (message) => logger_1.logger.warn(`${LOG_TAG} ${message}`);
+    const root = (0, scope_1.getScopeSchema)(apiDescriptor, config.scope);
+    if (!root) {
+        return apiDescriptor;
     }
-    // modify matched properties
-    if (targetSchema.properties) {
-        const props = { ...targetSchema.properties };
-        let required = Array.isArray(targetSchema.required) ? [...targetSchema.required] : [];
-        for (const key of Object.keys(props)) {
-            if (!(0, utils_1.isMatch)(key, config.match)) {
-                continue;
-            }
-            const { required: requiredOverride, schema: schemaValue } = (0, hepler_1.applyModifierSchema)(props[key], config, { required: required.includes(key), key });
-            required = required.filter(r => r !== key);
-            if (!schemaValue) {
-                delete props[key];
-                continue;
-            }
-            props[key] = schemaValue;
-            if (requiredOverride) {
-                required.push(key);
-            }
+    // 1. redirect: the scope root itself is replaced before anything else runs
+    let located = root;
+    if (config.unwrap !== undefined) {
+        const unwrapped = unwrapSchema(root, config.unwrap);
+        if (!unwrapped) {
+            warn(`unwrap "${config.unwrap}" does not exist in scope "${config.scope}" of ${apiDescriptor.url}, config skipped`);
+            return apiDescriptor;
         }
-        targetSchema.properties = props;
-        targetSchema.required = Array.from(new Set(required));
+        located = (0, dsl_1.stripRef)(unwrapped);
     }
-    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;
+    // 2. locate: either the root itself or every matching top-level field
+    if (config.match === undefined) {
+        const { schema } = applyStages(located, undefined, config, warn);
+        const next = { ...apiDescriptor };
+        (0, scope_1.setScopeSchema)(next, config.scope, schema);
+        return next;
     }
-    return parameters.map((param) => {
-        if (param.in !== type || !(0, utils_1.isMatch)(param.name, config.match)) {
-            return param;
+    const keys = Object.keys(located.properties ?? {}).filter(key => (0, utils_1.isMatch)(key, config.match));
+    if (!keys.length) {
+        return apiDescriptor;
+    }
+    const properties = { ...(located.properties ?? {}) };
+    const required = new Set(Array.isArray(located.required) ? located.required : []);
+    for (const key of keys) {
+        const result = applyStages(properties[key], key, config, warn);
+        if (!result.schema) {
+            delete properties[key];
+            required.delete(key);
+            continue;
         }
-        const { schema, required } = (0, hepler_1.applyModifierSchema)(param.schema, config, { required: !!param.required, key: param.name });
-        if (!schema) {
-            return null;
+        properties[key] = result.schema;
+        if (result.required ?? required.has(key)) {
+            required.add(key);
+        }
+        else {
+            required.delete(key);
         }
-        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)
-        return null;
-    // API path filter: if path does not match, return as-is and this config does not apply
-    if (!(0, utils_1.isMatch)(apiDescriptor.url, config.path))
-        return apiDescriptor;
-    const newDescriptor = { ...apiDescriptor };
-    const { scope } = config;
-    switch (scope) {
-        case 'params':
-            newDescriptor.parameters = applyToParameters(newDescriptor.parameters, constant_1.ParameterIn.QUERY, config);
-            break;
-        case 'pathParams':
-            newDescriptor.parameters = applyToParameters(newDescriptor.parameters, constant_1.ParameterIn.PATH, config);
-            break;
-        case 'data':
-            newDescriptor.requestBody = applyToSchemaField(newDescriptor.requestBody, config);
-            break;
-        case 'response':
-            newDescriptor.responses = applyToSchemaField(newDescriptor.responses, config);
-            break;
     }
-    return newDescriptor;
+    const next = { ...apiDescriptor };
+    (0, scope_1.setScopeSchema)(next, config.scope, {
+        ...located,
+        properties,
+        required: Array.from(required),
+    });
+    return next;
 }
+/**
+ * Flexibly adds, deletes and modifies the payload of your APIs.
+ *
+ * Every config runs the same fixed pipeline: interface filter (`path` / `tag`) → redirect
+ * (`unwrap`) → locate (`match`) → patch (`patch`) → custom (`handler`). Configs are applied
+ * in array order, so a later config sees the result of the previous ones.
+ *
+ * @example
+ * ```ts
+ * payloadModifier([
+ *   { scope: 'response', unwrap: 'data' },
+ *   { scope: 'response', match: /[Ii]d$/, patch: 'string' },
+ *   { scope: 'data', path: '/planPoint', patch: { operatorId: { type: 'string', required: true } } },
+ * ])
+ * ```
+ */
 function payloadModifier(configs) {
+    // Guards against the config hook being run twice for the same descriptor,
+    // which happens when the CLI loads the same plugin instance more than once.
+    const processed = Symbol('worma:payloadModifier:processed');
+    const list = Array.isArray(configs) ? configs : [configs];
     return {
         name: constant_1.PluginName.PAYLOAD_MODIFIER,
         config({ config }) {
@@ -158,13 +144,14 @@ function payloadModifier(configs) {
                     if (!apiDescriptor) {
                         return null;
                     }
-                    // Apply each configuration in sequence
-                    return configs.reduce((desc, conf) => {
-                        if (!desc) {
-                            return null;
-                        }
-                        return payloadModifierApiDescriptor(desc, conf);
-                    }, apiDescriptor);
+                    if (apiDescriptor[processed]) {
+                        return apiDescriptor;
+                    }
+                    const next = list.reduce((descriptor, conf) => (descriptor ? applyConfig(descriptor, conf) : null), apiDescriptor);
+                    if (next) {
+                        next[processed] = true;
+                    }
+                    return next;
                 },
             });
         },

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

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_KEYS = void 0;
+exports.isPatchObject = isPatchObject;
+exports.applyFieldValue = applyFieldValue;
+exports.applyPropertiesPatch = applyPropertiesPatch;
+const dsl_1 = require("./dsl");
+/**
+ * OpenAPI keywords plus `required`. An object holding one of them is a partial patch of
+ * the target itself; an object holding none of them is a shorthand for `properties`.
+ */
+exports.RESERVED_KEYS = new Set([
+    'type',
+    'required',
+    'description',
+    'properties',
+    'items',
+    'enum',
+    'oneOf',
+    'anyOf',
+    'allOf',
+    'format',
+    'example',
+    'default',
+    'deprecated',
+    'nullable',
+    'title',
+]);
+/** Keys written through verbatim when present in a patch object. */
+const DOC_KEYS = [
+    'description',
+    'title',
+    'format',
+    'example',
+    'default',
+    'deprecated',
+    'nullable',
+];
+function isPatchObject(value) {
+    return Object.keys(value).some(key => exports.RESERVED_KEYS.has(key));
+}
+/**
+ * Applies a single patch value to a target schema. This is the one and only entry point
+ * of the patch syntax: the same rules apply to the top level patch and to every value
+ * inside a field table, therefore they apply recursively.
+ *
+ * @param current the target schema, `undefined` when the patch creates a new field
+ */
+function applyFieldValue(current, value, ctx) {
+    if (value === null) {
+        return { schema: null };
+    }
+    if (typeof value === 'string' || Array.isArray(value)) {
+        return { schema: replaceType(current, value) };
+    }
+    const patch = value;
+    if (!isPatchObject(patch)) {
+        return applyTablePatch(current, patch, ctx);
+    }
+    return applyPatchObject(current, patch, ctx);
+}
+/**
+ * Applies a field table to a target: a value of `null` deletes the field, every other
+ * value is applied recursively. Fields added this way are required unless they say otherwise.
+ */
+function applyPropertiesPatch(target, table, ctx) {
+    const properties = { ...(target.properties ?? {}) };
+    const required = new Set(Array.isArray(target.required) ? target.required : []);
+    for (const key of Object.keys(table)) {
+        const isNew = !(key in properties);
+        const result = applyFieldValue(isNew ? undefined : properties[key], table[key], ctx);
+        if (!result.schema) {
+            delete properties[key];
+            required.delete(key);
+            continue;
+        }
+        properties[key] = result.schema;
+        const nextRequired = result.required ?? (isNew ? true : required.has(key));
+        if (nextRequired) {
+            required.add(key);
+        }
+        else {
+            required.delete(key);
+        }
+    }
+    return {
+        ...target,
+        type: 'object',
+        properties,
+        required: Array.from(required),
+    };
+}
+/** `null` as the whole table means dropping every field. */
+function applyTablePatch(current, table, ctx) {
+    const base = current ?? { type: 'object' };
+    if (!isObjectTarget(base)) {
+        ctx.warn('field table patch skipped: the target is not an object schema');
+        return { schema: current ?? null };
+    }
+    return { schema: applyPropertiesPatch(base, table, ctx) };
+}
+function applyPatchObject(current, patch, ctx) {
+    let out = current ? { ...current } : {};
+    let required;
+    if (patch.type !== undefined) {
+        out = {
+            ...(0, dsl_1.stripRef)((0, dsl_1.clearTypeFamily)(out)),
+            ...(0, dsl_1.dslToSchemaObject)(patch.type),
+        };
+    }
+    // `required` never becomes a schema key, the caller translates it.
+    if (patch.required !== undefined) {
+        required = !!patch.required;
+    }
+    if (patch.properties !== undefined) {
+        if (isObjectTarget(out)) {
+            out = applyPropertiesPatch(out, patch.properties, ctx);
+        }
+        else {
+            ctx.warn('`properties` patch skipped: the target is not an object schema');
+        }
+    }
+    if (patch.items !== undefined) {
+        out.items = (0, dsl_1.dslToSchemaObject)(patch.items);
+        if (out.type !== 'array') {
+            out.type = 'array';
+        }
+    }
+    if (patch.enum !== undefined) {
+        out.enum = patch.enum;
+        if (out.type === undefined) {
+            const inferred = (0, dsl_1.inferEnumType)(patch.enum);
+            if (inferred) {
+                out.type = inferred;
+            }
+        }
+    }
+    // A union fully determines the type, so it replaces the type family just like `type` does.
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        const members = patch[key];
+        if (members === undefined) {
+            continue;
+        }
+        out = {
+            ...(0, dsl_1.stripRef)((0, dsl_1.clearTypeFamily)(out)),
+            [key]: members.map(item => (0, dsl_1.dslToSchemaObject)(item)),
+        };
+    }
+    for (const key of DOC_KEYS) {
+        const next = patch[key];
+        if (next !== undefined) {
+            out[key] = next;
+        }
+    }
+    return { schema: out, required };
+}
+/** Replaces the type of a target: type-family keys are cleared, everything else is kept. */
+function replaceType(current, dsl) {
+    const rest = (0, dsl_1.stripRef)((0, dsl_1.clearTypeFamily)(current ?? {}));
+    return { ...rest, ...(0, dsl_1.dslToSchemaObject)(dsl) };
+}
+/** A patch may only touch the field table when the target really is an object. */
+function isObjectTarget(target) {
+    if (!target) {
+        return true;
+    }
+    if (target.oneOf || target.anyOf || target.allOf) {
+        return false;
+    }
+    return target.type === undefined || target.type === 'object';
+}

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

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopeParameterIn = scopeParameterIn;
+exports.parametersToSchema = parametersToSchema;
+exports.removeParameters = removeParameters;
+exports.schemaToParameters = schemaToParameters;
+exports.getScopeSchema = getScopeSchema;
+exports.setScopeSchema = setScopeSchema;
+const constant_1 = require("../../../constant");
+/** Maps a scope onto the parameter location it owns. Schema scopes have no location. */
+function scopeParameterIn(scope) {
+    if (scope === 'params') {
+        return constant_1.ParameterIn.QUERY;
+    }
+    if (scope === 'pathParams') {
+        return constant_1.ParameterIn.PATH;
+    }
+    return undefined;
+}
+/** Builds an object-schema view of the parameters of one location. */
+function parametersToSchema(parameters, location) {
+    const schema = { type: 'object', properties: {}, required: [] };
+    if (!Array.isArray(parameters)) {
+        return schema;
+    }
+    const properties = schema.properties;
+    const required = schema.required;
+    for (const param of parameters) {
+        if (param.in !== location) {
+            continue;
+        }
+        properties[param.name] = param.schema;
+        if (param.required) {
+            required.push(param.name);
+        }
+    }
+    return schema;
+}
+/** Drops every parameter of one location. */
+function removeParameters(parameters, location) {
+    if (!Array.isArray(parameters)) {
+        return parameters;
+    }
+    return parameters.filter(param => param.in !== location);
+}
+/**
+ * Writes an object-schema view back into parameters. Parameters of other locations are
+ * kept untouched and fields absent from the original list are appended as new parameters.
+ */
+function schemaToParameters(parameters, schema, location) {
+    if (!Array.isArray(parameters)) {
+        return parameters;
+    }
+    if (!schema || typeof schema !== 'object' || !schema.properties) {
+        return removeParameters(parameters, location);
+    }
+    const properties = schema.properties;
+    const requiredSet = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const next = [];
+    for (const param of parameters) {
+        if (param.in !== location) {
+            next.push(param);
+            continue;
+        }
+        const propSchema = properties[param.name];
+        if (!propSchema) {
+            continue;
+        }
+        next.push({ ...param, schema: propSchema, required: requiredSet.has(param.name) });
+    }
+    // fields added by a patch become brand new parameters
+    for (const name of Object.keys(properties)) {
+        if (next.some(param => param.in === location && param.name === name)) {
+            continue;
+        }
+        next.push({
+            name,
+            in: location,
+            required: requiredSet.has(name),
+            schema: properties[name],
+        });
+    }
+    return next;
+}
+/** Reads the root schema of a scope. Parameter scopes are read as an object-schema view. */
+function getScopeSchema(apiDescriptor, scope) {
+    const location = scopeParameterIn(scope);
+    if (location) {
+        return parametersToSchema(apiDescriptor.parameters, location);
+    }
+    return scope === 'data' ? apiDescriptor.requestBody : apiDescriptor.responses;
+}
+/**
+ * Writes the root schema of a scope back into the descriptor. `null` empties the scope.
+ */
+function setScopeSchema(apiDescriptor, scope, schema) {
+    const location = scopeParameterIn(scope);
+    if (location) {
+        apiDescriptor.parameters = schema === null
+            ? removeParameters(apiDescriptor.parameters, location)
+            : schemaToParameters(apiDescriptor.parameters, schema, location);
+        return;
+    }
+    if (scope === 'data') {
+        apiDescriptor.requestBody = schema ?? undefined;
+        return;
+    }
+    apiDescriptor.responses = schema ?? undefined;
+}

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

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.yapi = exports.swagger = exports.withCookie = exports.normalizeBase = exports.defineUrlPlatformPlugin = exports.knife4j = exports.fastapi = void 0;
-var fastapi_1 = require("./fastapi");
-Object.defineProperty(exports, "fastapi", { enumerable: true, get: function () { return fastapi_1.fastapi; } });
+exports.yapi = exports.swagger = exports.withCookie = exports.normalizeBase = exports.defineUrlPlatformPlugin = exports.knife4j = void 0;
 var knife4j_1 = require("./knife4j");
 Object.defineProperty(exports, "knife4j", { enumerable: true, get: function () { return knife4j_1.knife4j; } });
 var shared_1 = require("./shared");