wormajs 0.3.1 → 1.0.0-beta.0

package/dist/plugins/presets/postman.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapTransformationOutput = unwrapTransformationOutput;
+exports.postman = postman;
+const constant_1 = require("../../constant");
+/** Base address of the Postman API */
+const POSTMAN_API_BASE = 'https://api.getpostman.com';
+/**
+ * Unwraps the OpenAPI definition returned by the Postman collection
+ * transformation endpoint, which responds with `{ output: "<stringified spec>" }`
+ * instead of the specification itself.
+ *
+ * The response is parsed exactly once. Anything that is not a transformation
+ * envelope (an error payload, an HTML page, a malformed body, …) throws instead
+ * of being silently passed through, so the real problem surfaces immediately.
+ * The unwrapped spec is then validated by the generator's parser, like any other
+ * input — this function does not re-parse or validate it.
+ */
+function unwrapTransformationOutput(spec) {
+    let parsed;
+    try {
+        parsed = JSON.parse(spec);
+    }
+    catch (error) {
+        throw new Error('[postman] The transformation response is not valid JSON: '
+            + `${error instanceof Error ? error.message : String(error)}. `
+            + `Received: ${spec.slice(0, 200)}`);
+    }
+    const output = parsed?.output;
+    if (typeof output !== 'string') {
+        throw new TypeError('[postman] The transformation response must be a JSON object with a string `output` field. '
+            + 'Check that the collection uid is correct and that you have access to it. '
+            + `Received: ${spec.slice(0, 200)}`);
+    }
+    return output;
+}
+/**
+ * Postman platform plugin.
+ *
+ * Postman collections are not OpenAPI documents, so the plugin points `input` to
+ * the collection transformation endpoint, which converts the collection into an
+ * OpenAPI definition:
+ *
+ * ```
+ * https://api.getpostman.com/collections/<collectionId>/transformations
+ * ```
+ *
+ * The `x-api-key` header is injected through `fetchOptions`. The endpoint responds
+ * with `{ output: "<spec>" }`, so the plugin unwraps that envelope in its
+ * `beforeSpecParse` hook.
+ *
+ * `apiKey` and `collectionId` are both required — the plugin throws a clear error
+ * when either is missing.
+ *
+ * @param options - `{ apiKey, collectionId }`
+ * @param options.apiKey - Postman API key used to read the collection
+ * @param options.collectionId - The uid of the Postman collection
+ *
+ * @example
+ * ```ts
+ * import { postman, alovaGlobals } from 'wormajs/plugin';
+ *
+ * defineConfig({
+ *   generator: [{
+ *     plugins: [
+ *       postman({
+ *         apiKey: 'PMAK-xxx',
+ *         collectionId: '12345678-a1b2-c3d4-e5f6-7890abcdef12',
+ *       }),
+ *       alovaGlobals(),
+ *     ],
+ *     output: './src/api',
+ *   }]
+ * });
+ * ```
+ */
+function postman({ apiKey, collectionId }) {
+    return {
+        name: constant_1.PluginName.POSTMAN,
+        async config({ config }) {
+            if (!apiKey) {
+                throw new Error('[postman] `apiKey` is required — the Postman API key used to read the collection '
+                    + '(e.g. postman({ apiKey: "PMAK-xxx", collectionId: "12345678-..." })).');
+            }
+            if (!collectionId) {
+                throw new Error('[postman] `collectionId` is required — the uid of the Postman collection '
+                    + '(e.g. postman({ apiKey: "PMAK-xxx", collectionId: "12345678-..." })).');
+            }
+            config.input = `${POSTMAN_API_BASE}/collections/${encodeURIComponent(collectionId.trim())}/transformations`;
+            config.fetchOptions = {
+                ...config.fetchOptions,
+                method: 'GET',
+                headers: {
+                    ...config.fetchOptions?.headers,
+                    'x-api-key': apiKey,
+                },
+            };
+            return config;
+        },
+        beforeSpecParse({ spec }) {
+            return unwrapTransformationOutput(spec);
+        },
+    };
+}
+exports.default = postman;

package/dist/template/presets/ai-doc/SKILL.md.handlebars

@@ -1,5 +1,5 @@
 ---
-name: apis-{{{title}}}
+name: {{{skillName}}}
 description: >-
   API reference documentation for {{{serverName}}} ({{{title}}} v{{{version}}}).
   Contains specifications for all REST API endpoints, including HTTP request methods,

package/dist/template/presets/alova/common/services/{tag}.d.cts.handlebars

@@ -6,7 +6,7 @@ type {{{currentTag.tag}}}DefaultConfig = TagDefaultConfig<typeof defaultConfig,
 
 {{> extract-responded}}
 {{#each currentTag.apis}}
-{{> dts-extra-config}}
+{{> dts-types}}
 {{> api-jsdoc}}
 {{> dts-fn-declare}}
 

package/dist/template/presets/alova/module/services/{tag}.d.ts.handlebars

@@ -6,7 +6,7 @@ type {{{currentTag.tag}}}DefaultConfig = TagDefaultConfig<typeof defaultConfig,
 
 {{> extract-responded}}
 {{#each currentTag.apis}}
-{{> dts-extra-config}}
+{{> dts-types}}
 {{> api-jsdoc}}
 {{> dts-fn-declare}}
 

package/dist/template/presets/alova/partials/dts-fn-declare.handlebars

@@ -1 +1 @@
-export declare function {{{name}}}<Config extends Alova2MethodConfig<{{addNamespace response @root.componentNames}}> & {{{name}}}ExtraConfig>(config{{#or pathParameters queryParameters requestBody }}{{else}}?{{/or}}: Config): Alova2Method<ExtractResponded<Config, '{{{name}}}', {{addNamespace response @root.componentNames}}>>;
+export declare function {{{name}}}<Config extends Alova2MethodConfig<{{{name}}}Response> & {{{name}}}ExtraConfig>(config{{#or pathParameters queryParameters requestBody }}{{else}}?{{/or}}: Config): Alova2Method<ExtractResponded<Config, '{{{name}}}', {{{name}}}Response>>;

package/dist/template/presets/alova/partials/dts-types.handlebars

@@ -0,0 +1,12 @@
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#or pathParameters queryParameters requestBody}}
+export interface {{{name}}}ExtraConfig {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}data: {{{name}}}Data;
+  {{/if}}
+}
+{{/or}}

package/dist/template/presets/alova/typescript/services/{tag}.ts.handlebars

@@ -10,16 +10,21 @@ const {{{currentTag.tag}}}DefaultConfig = resolveTagDefaultConfig(defaultConfig,
 {{> extract-responded}}
 {{#each currentTag.apis}}
 
-interface {{{name}}}ExtraConfig {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}params: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}data: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}
+export interface {{{name}}}ExtraConfig {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}data: {{{name}}}Data;
   {{/if}}
 }
 {{> api-jsdoc}}
-export function {{{name}}}<Config extends Alova2MethodConfig<{{addNamespace response @root.componentNames}}> & {{{name}}}ExtraConfig>(config{{#or pathParameters queryParameters requestBody }}{{else}}?{{/or}}: Config): Alova2Method<ExtractResponded<Config, '{{{name}}}', {{addNamespace response @root.componentNames}}>> {
+export function {{{name}}}<Config extends Alova2MethodConfig<{{{name}}}Response> & {{{name}}}ExtraConfig>(config{{#or pathParameters queryParameters requestBody }}{{else}}?{{/or}}: Config): Alova2Method<ExtractResponded<Config, '{{{name}}}', {{{name}}}Response>> {
   const { url, data, mergedConfig } = buildPayload('{{{path}}}', {{../currentTag.tag}}DefaultConfig, {{{name}}}.name, config);
-  return alovaInstance.Request<ExtractResponded<Config, '{{{name}}}', {{addNamespace response @root.componentNames}}>>({
+  return alovaInstance.Request<ExtractResponded<Config, '{{{name}}}', {{{name}}}Response>>({
     ...mergedConfig,
     url,
     data,

package/dist/template/presets/axios/partials/dts-types.handlebars

@@ -1,7 +1,11 @@
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
-type {{{name}}}ExtraConfig = Omit<AxiosRequestConfig, 'data' | 'params'> & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}params: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}data: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}
+export type {{{name}}}ExtraConfig = Omit<AxiosRequestConfig, 'data' | 'params'> & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}data: {{{name}}}Data;
   {{/if}}
 };

package/dist/template/presets/axios/typescript/services/{tag}.ts.handlebars

@@ -8,11 +8,15 @@ import type * as ComponentTypes from '../components';
 const {{{currentTag.tag}}}DefaultConfig = resolveTagDefaultConfig(defaultConfig, '{{{currentTag.tag}}}DefaultConfig');
 
 {{#each currentTag.apis}}
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
-type {{{name}}}ExtraConfig = Omit<AxiosRequestConfig, 'data' | 'params'> & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}params: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}data: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}
+export type {{{name}}}ExtraConfig = Omit<AxiosRequestConfig, 'data' | 'params'> & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}data: {{{name}}}Data;
   {{/if}}
 };
 {{> api-jsdoc}}

package/dist/template/presets/fetch/partials/dts-types.handlebars

@@ -1,7 +1,10 @@
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
-type {{{name}}}ExtraConfig = Omit<RequestInit, 'body'> & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}params?: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}body?: {{addNamespace requestBody @root.componentNames}} | BodyInit;
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+export type {{{name}}}ExtraConfig = Omit<RequestInit, 'body'> & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params?: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}body?: {{{name}}}Data | BodyInit;
   {{/if}}
 };

package/dist/template/presets/fetch/typescript/services/{tag}.ts.handlebars

@@ -7,11 +7,15 @@ import type * as ComponentTypes from '../components';
 const {{{currentTag.tag}}}DefaultConfig = resolveTagDefaultConfig(defaultConfig, '{{{currentTag.tag}}}DefaultConfig');
 
 {{#each currentTag.apis}}
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
-type {{{name}}}ExtraConfig = Omit<RequestInit, 'body'> & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}params?: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}body?: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}
+export type {{{name}}}ExtraConfig = Omit<RequestInit, 'body'> & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}params?: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}body?: {{{name}}}Data;
   {{/if}}
 };
 {{> api-jsdoc}}

package/dist/template/presets/ky/partials/dts-types.handlebars

@@ -1,9 +1,12 @@
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
 {{#or pathParameters queryParameters requestBody}}
-type {{{name}}}ExtraConfig = Options & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}searchParams: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}json: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}ExtraConfig = Options & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}searchParams: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}json: {{{name}}}Data;
   {{/if}}
 };
 {{/or}}

package/dist/template/presets/ky/typescript/services/{tag}.ts.handlebars

@@ -8,11 +8,15 @@ import type * as ComponentTypes from '../components';
 const {{{currentTag.tag}}}DefaultConfig = resolveTagDefaultConfig(defaultConfig, '{{{currentTag.tag}}}DefaultConfig');
 
 {{#each currentTag.apis}}
-type {{{name}}}Response = {{addNamespace response @root.componentNames}};
-type {{{name}}}ExtraConfig = Options & {
-  {{#if pathParameters}}pathParams: {{addNamespace pathParameters @root.componentNames}};
-  {{/if}}{{#if queryParameters}}searchParams: {{addNamespace queryParameters @root.componentNames}};
-  {{/if}}{{#if requestBody}}json: {{addNamespace requestBody @root.componentNames}};
+export type {{{name}}}Response = {{addNamespace response @root.componentNames}};
+{{#if pathParameters}}export type {{{name}}}PathParams = {{addNamespace pathParameters @root.componentNames}};
+{{/if}}{{#if queryParameters}}export type {{{name}}}Params = {{addNamespace queryParameters @root.componentNames}};
+{{/if}}{{#if requestBody}}export type {{{name}}}Data = {{addNamespace requestBody @root.componentNames}};
+{{/if}}
+export type {{{name}}}ExtraConfig = Options & {
+  {{#if pathParameters}}pathParams: {{{name}}}PathParams;
+  {{/if}}{{#if queryParameters}}searchParams: {{{name}}}Params;
+  {{/if}}{{#if requestBody}}json: {{{name}}}Data;
   {{/if}}
 };
 {{> api-jsdoc}}

package/dist/utils/format.js

@@ -33,13 +33,37 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.prettierConfig = void 0;
+exports.defaultFormatOptions = void 0;
+exports.isFormatEnabled = isFormatEnabled;
 exports.format = format;
-const prettierBabel = __importStar(require("prettier/plugins/babel"));
-const prettierEsTree = __importStar(require("prettier/plugins/estree"));
-const prettierTs = __importStar(require("prettier/plugins/typescript"));
-const prettier = __importStar(require("prettier/standalone"));
-exports.prettierConfig = {
+const config_1 = require("../config");
+/**
+ * 回退用的真实动态 import。
+ * `new Function` 内的 `import()` 不会被 TypeScript 降级为 `require()`，用于 CJS 产物中加载纯 ESM 包。
+ */
+// eslint-disable-next-line no-new-func -- CJS 产物必须保留 new Function 包裹的真实动态 import，才能加载纯 ESM 的 oxfmt
+const fallbackImport = new Function('specifier', 'return import(specifier)');
+/** oxfmt 只加载一次，后续复用 */
+let oxfmtPromise;
+/**
+ * oxfmt 是 ESM-only（`"type": "module"`，无 require 条件），而 worma 的编译产物是 CommonJS。
+ *
+ * 优先使用字面量 `import()`：vite/vitest 的 SSR 转换器只会识别源码中直接出现的 `import(...)`
+ * 并替换为它的 dynamic import 回调，因此测试环境必须走这条路径。
+ * 而在 `module: CommonJS` 编译产物中，TypeScript 会把 `import()` 降级为 `require()`，
+ * 对纯 ESM 包会抛 `ERR_REQUIRE_ESM`（或 oxfmt 含顶层 await 时抛 `ERR_REQUIRE_ASYNC_MODULE`），
+ * 此时回退到 `new Function` 包裹的真实动态 import。
+ */
+function loadOxfmt() {
+    oxfmtPromise ??= Promise.resolve().then(() => __importStar(require('oxfmt'))).catch(() => fallbackImport('oxfmt'));
+    return oxfmtPromise;
+}
+/**
+ * 与历史 prettier 配置等价的默认格式化参数。
+ * prettier 的 `insertPragma` 在 oxfmt 中不存在（原本即为 false，直接去掉）；
+ * `endOfLine: 'auto'` 不为 oxfmt 支持，语义最接近的是 `lf`。
+ */
+exports.defaultFormatOptions = {
     printWidth: 120,
     tabWidth: 2,
     useTabs: false,
@@ -47,18 +71,41 @@ exports.prettierConfig = {
     singleQuote: true,
     trailingComma: 'none',
     bracketSpacing: true,
-    insertPragma: false,
-    endOfLine: 'auto',
     bracketSameLine: true,
     arrowParens: 'avoid',
-    vueIndentScriptAndStyle: false,
     singleAttributePerLine: true,
+    vueIndentScriptAndStyle: false,
+    endOfLine: 'lf',
 };
-async function format(text, config) {
-    return prettier.format(text, {
-        ...exports.prettierConfig,
-        parser: 'typescript', // Specify to use babel parser
+/** 合并 默认 < 用户全局配置 < 本次调用覆盖，并剥掉 worma 自有的 `enabled` 字段 */
+function resolveOptions(config) {
+    const { enabled, ...oxfmtOptions } = {
+        ...exports.defaultFormatOptions,
+        ...((0, config_1.getGlobalConfig)().format ?? {}),
         ...(config ?? {}),
-        plugins: [prettierTs, prettierEsTree, prettierBabel],
-    });
+    };
+    void enabled;
+    return oxfmtOptions;
+}
+/**
+ * 是否对生成产物执行格式化。由 `format.enabled` 控制，默认 true。
+ */
+function isFormatEnabled() {
+    return (0, config_1.getGlobalConfig)().format?.enabled ?? true;
+}
+/**
+ * 格式化一段代码。
+ * @param fileName 文件名，oxfmt 依据扩展名推断语言（无 prettier 的 `parser` 选项）
+ * @param text 源码文本
+ * @param config 单次调用的覆盖配置，优先级最高
+ * @returns 格式化后的代码；解析失败时抛错，由调用方回退原文
+ */
+async function format(fileName, text, config) {
+    const { format: oxfmtFormat } = await loadOxfmt();
+    const result = await oxfmtFormat(fileName, text, resolveOptions(config));
+    const fatal = result.errors?.find(error => error.severity === 'Error');
+    if (fatal) {
+        throw new Error(`oxfmt failed to format ${fileName}: ${fatal.message}`);
+    }
+    return result.code;
 }

package/dist/utils/template.js

@@ -111,6 +111,6 @@ async function generateFile(distDir, fileName, content) {
         await promises_1.default.mkdir(distDir, { recursive: true });
     }
     const filePath = node_path_1.default.join(distDir, fileName);
-    const formattedText = await (0, format_1.format)(content);
+    const formattedText = await (0, format_1.format)(fileName, content);
     await promises_1.default.writeFile(filePath, formattedText);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wormajs",
-  "version": "0.3.1",
+  "version": "1.0.0-beta.0",
   "description": "A modern OpenAPI code generator - Generate type-safe API clients from OpenAPI specs",
   "author": "worma",
   "license": "MIT",
@@ -50,6 +50,7 @@
   "dependencies": {
     "alova": "^3.3.4",
     "chalk": "4.1.2",
+    "cli-table3": "^0.6.5",
     "cli-truncate": "^4.0.0",
     "commander": "^14.0.0",
     "esbuild": "^0.25.6",
@@ -60,7 +61,7 @@
     "log-update": "^6.1.0",
     "openapi-types": "^12.1.3",
     "ora": "5.4.1",
-    "prettier": "^3.6.2",
+    "oxfmt": "^0.67.0",
     "skills": "^1.5.13",
     "string-width": "^7.2.0",
     "swagger2openapi": "^7.0.8",