Milky 1.3 累积更新

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+*.g.ts
 
 ### IntelliJ IDEA ###
 .idea/

common/src/generator/typescript/shared.ts

@@ -1,6 +1,31 @@
 import type { IRField } from '@saltify/milky-protocol';
 
-export function getTypeScriptTypeProjection(field: IRField): string {
+export type TypeScriptTypeProjectionMode = 'input' | 'output';
+
+export interface TypeScriptTypeProjectionOptions {
+  mode?: TypeScriptTypeProjectionMode;
+  getRefTypeName?: (name: string, mode: TypeScriptTypeProjectionMode) => string;
+}
+
+function getDefaultRefTypeName(name: string, mode: TypeScriptTypeProjectionMode): string {
+  if (mode === 'input') {
+    return `${name}_ZodInput`;
+  }
+  return name;
+}
+
+export function getTypeScriptTypeProjection(field: IRField, options: TypeScriptTypeProjectionOptions = {}): string {
+  const mode = options.mode ?? 'output';
+  const getRefTypeName = options.getRefTypeName ?? getDefaultRefTypeName;
+
+  if (field.isOptional) {
+    return `${getTypeScriptTypeProjection({ ...field, isOptional: false }, options)} | null | undefined`;
+  }
+
+  if (mode === 'input' && field.defaultValue !== undefined) {
+    return `${getTypeScriptTypeProjection({ ...field, defaultValue: undefined }, options)} | null | undefined`;
+  }
+
   if (field.fieldType === 'scalar') {
     if (field.scalarType === 'string') {
       if (field.isArray) {
@@ -35,9 +60,9 @@ export function getTypeScriptTypeProjection(field: IRField): string {
 
   if (field.fieldType === 'ref') {
     if (field.isArray) {
-      return `${field.refStructName}[]`;
+      return `${getRefTypeName(field.refStructName, mode)}[]`;
     } else {
-      return field.refStructName;
+      return getRefTypeName(field.refStructName, mode);
     }
   }
 

common/src/generator/typescript/static.ts

@@ -1,9 +1,35 @@
-import type { IR } from '@saltify/milky-protocol';
+import type { IR, IRField } from '@saltify/milky-protocol';
 
 import { getApiTypeNames } from '../shared/ir';
 import { normalizeDerivedStructName } from '../shared/naming';
 import { createLineWriter, formatBlockDocComment } from '../shared/text';
-import { getTypeScriptTypeProjection } from './shared';
+import { getTypeScriptTypeProjection, type TypeScriptTypeProjectionMode } from './shared';
+
+function getZodInputTypeName(name: string): string {
+  return `${name}_ZodInput`;
+}
+
+function getTypeScriptFieldProjection(field: IRField, mode: TypeScriptTypeProjectionMode): string {
+  return getTypeScriptTypeProjection(field, { mode });
+}
+
+function isFieldOptionalInProjection(field: IRField, mode: TypeScriptTypeProjectionMode): boolean {
+  return field.isOptional || (mode === 'input' && field.defaultValue !== undefined);
+}
+
+function renderField(
+  l: (line?: string) => void,
+  field: IRField,
+  mode: TypeScriptTypeProjectionMode,
+  indent: string = '  ',
+) {
+  formatBlockDocComment(field.description, field.since, indent).forEach((line) => {
+    l(line);
+  });
+  l(
+    `${indent}${field.name}${isFieldOptionalInProjection(field, mode) ? '?' : ''}: ${getTypeScriptFieldProjection(field, mode)};`,
+  );
+}
 
 export function generateTypeScriptStaticSpec(ir: IR): string {
   const writer = createLineWriter();
@@ -25,10 +51,16 @@ export function generateTypeScriptStaticSpec(ir: IR): string {
       });
       l(`export interface ${struct.name} {`);
       struct.fields.forEach((field) => {
-        formatBlockDocComment(field.description, field.since, '  ').forEach((line) => {
-          l(line);
-        });
-        l(`  ${field.name}${field.isOptional ? '?' : ''}: ${getTypeScriptTypeProjection(field)};`);
+        renderField(l, field, 'output');
+      });
+      l('}');
+      l();
+      formatBlockDocComment(struct.description, struct.since).forEach((line) => {
+        l(line);
+      });
+      l(`export interface ${getZodInputTypeName(struct.name)} {`);
+      struct.fields.forEach((field) => {
+        renderField(l, field, 'input');
       });
       l('}');
     } else {
@@ -42,10 +74,20 @@ export function generateTypeScriptStaticSpec(ir: IR): string {
           l(`  /** 数据类型区分字段，表示自身为${derivedStruct.description} */`);
           l(`  ${struct.tagFieldName}: '${derivedStruct.tagValue}';`);
           derivedStruct.fields.forEach((field) => {
-            formatBlockDocComment(field.description, field.since, '  ').forEach((line) => {
-              l(line);
-            });
-            l(`  ${field.name}${field.isOptional ? '?' : ''}: ${getTypeScriptTypeProjection(field)};`);
+            renderField(l, field, 'output');
+          });
+          l('}');
+          l();
+          formatBlockDocComment(derivedStruct.description, derivedStruct.since).forEach((line) => {
+            l(line);
+          });
+          l(
+            `export interface ${getZodInputTypeName(normalizeDerivedStructName(struct.name, derivedStruct.tagValue))} {`,
+          );
+          l(`  /** 数据类型区分字段，表示自身为${derivedStruct.description} */`);
+          l(`  ${struct.tagFieldName}: '${derivedStruct.tagValue}';`);
+          derivedStruct.fields.forEach((field) => {
+            renderField(l, field, 'input');
           });
           l('}');
           l();
@@ -59,47 +101,87 @@ export function generateTypeScriptStaticSpec(ir: IR): string {
             `  | ${normalizeDerivedStructName(struct.name, derivedStruct.tagValue)}${index === struct.derivedStructs.length - 1 ? ';' : ''}`,
           );
         });
+        l();
+        formatBlockDocComment(struct.description, struct.since).forEach((line) => {
+          l(line);
+        });
+        l(`export type ${getZodInputTypeName(struct.name)} =`);
+        struct.derivedStructs.forEach((derivedStruct, index) => {
+          l(
+            `  | ${getZodInputTypeName(normalizeDerivedStructName(struct.name, derivedStruct.tagValue))}${index === struct.derivedStructs.length - 1 ? ';' : ''}`,
+          );
+        });
       } else {
         // with data property
         struct.derivedTypes.forEach((derivedType) => {
+          const derivedStructName = normalizeDerivedStructName(struct.name, derivedType.tagValue);
           formatBlockDocComment(derivedType.description, derivedType.since).forEach((line) => {
             l(line);
           });
+          l(`export interface ${derivedStructName} {`);
+          l(`  /** 数据类型区分字段，表示自身为${derivedType.description} */`);
+          l(`  ${struct.tagFieldName}: '${derivedType.tagValue}';`);
+          struct.baseFields.forEach((field) => {
+            renderField(l, field, 'output');
+          });
+
           if (derivedType.derivingType === 'struct') {
-            l(`export interface ${normalizeDerivedStructName(struct.name, derivedType.tagValue)}Data {`);
+            l(`  /** 数据内容 */`);
+            l(`  data: {`);
             derivedType.fields.forEach((field) => {
-              formatBlockDocComment(field.description, field.since, '  ').forEach((line) => {
-                l(line);
-              });
-              l(`  ${field.name}${field.isOptional ? '?' : ''}: ${getTypeScriptTypeProjection(field)};`);
+              renderField(l, field, 'output', '    ');
             });
-            l('}');
+            l('  }');
           } else {
             // ref type
-            l(
-              `export type ${normalizeDerivedStructName(struct.name, derivedType.tagValue)}Data = ${derivedType.refStructName};`,
-            );
+            l(`  /** 数据内容 */`);
+            l(`  data: ${derivedType.refStructName};`);
           }
-          // add type aliases for Event
-          if (struct.name === 'Event') {
-            formatBlockDocComment(derivedType.description, derivedType.since).forEach((line) => {
-              l(line);
+          l('}');
+          l();
+          formatBlockDocComment(derivedType.description, derivedType.since).forEach((line) => {
+            l(line);
+          });
+          l(`export interface ${getZodInputTypeName(derivedStructName)} {`);
+          l(`  /** 数据类型区分字段，表示自身为${derivedType.description} */`);
+          l(`  ${struct.tagFieldName}: '${derivedType.tagValue}';`);
+          struct.baseFields.forEach((field) => {
+            renderField(l, field, 'input');
+          });
+
+          if (derivedType.derivingType === 'struct') {
+            l(`  /** 数据内容 */`);
+            l(`  data: {`);
+            derivedType.fields.forEach((field) => {
+              renderField(l, field, 'input', '    ');
             });
-            l(
-              `export type ${normalizeDerivedStructName(struct.name, derivedType.tagValue)} = ${normalizeDerivedStructName(struct.name, derivedType.tagValue)}Data;`,
-            );
+            l('  }');
+          } else {
+            // ref type
+            l(`  /** 数据内容 */`);
+            l(`  data: ${getZodInputTypeName(derivedType.refStructName)};`);
           }
+          l('}');
           l();
         });
         formatBlockDocComment(struct.description, struct.since).forEach((line) => {
           l(line);
         });
         l(`export type ${struct.name} =`);
         struct.derivedTypes.forEach((derivedType, index) => {
-          l('  | {');
-          l(`      ${struct.tagFieldName}: '${derivedType.tagValue}';`);
-          l(`      data: ${normalizeDerivedStructName(struct.name, derivedType.tagValue)}Data;`);
-          l(`    }${index === struct.derivedTypes.length - 1 ? ';' : ''}`);
+          l(
+            `  | ${normalizeDerivedStructName(struct.name, derivedType.tagValue)}${index === struct.derivedTypes.length - 1 ? ';' : ''}`,
+          );
+        });
+        l();
+        formatBlockDocComment(struct.description, struct.since).forEach((line) => {
+          l(line);
+        });
+        l(`export type ${getZodInputTypeName(struct.name)} =`);
+        struct.derivedTypes.forEach((derivedType, index) => {
+          l(
+            `  | ${getZodInputTypeName(normalizeDerivedStructName(struct.name, derivedType.tagValue))}${index === struct.derivedTypes.length - 1 ? ';' : ''}`,
+          );
         });
       }
     }
@@ -119,32 +201,52 @@ export function generateTypeScriptStaticSpec(ir: IR): string {
       if (api.requestFields !== undefined) {
         l(`export interface ${typeNames.inputName} {`);
         api.requestFields.forEach((field) => {
-          formatBlockDocComment(field.description, field.since, '  ').forEach((line) => {
-            l(line);
-          });
-          l(`  ${field.name}${field.isOptional ? '?' : ''}: ${getTypeScriptTypeProjection(field)};`);
+          renderField(l, field, 'output');
         });
         l('}');
       } else {
         l(`export type ${typeNames.inputName} = {};`);
       }
       l();
+      formatBlockDocComment(`${api.description} API 请求参数`, api.since).forEach((line) => {
+        l(line);
+      });
+      if (api.requestFields !== undefined) {
+        l(`export interface ${getZodInputTypeName(typeNames.inputName)} {`);
+        api.requestFields.forEach((field) => {
+          renderField(l, field, 'input');
+        });
+        l('}');
+      } else {
+        l(`export type ${getZodInputTypeName(typeNames.inputName)} = {};`);
+      }
+      l();
       formatBlockDocComment(`${api.description} API 响应数据`, api.since).forEach((line) => {
         l(line);
       });
       if (api.responseFields !== undefined) {
         l(`export interface ${typeNames.outputName} {`);
         api.responseFields.forEach((field) => {
-          formatBlockDocComment(field.description, field.since, '  ').forEach((line) => {
-            l(line);
-          });
-          l(`  ${field.name}${field.isOptional ? '?' : ''}: ${getTypeScriptTypeProjection(field)};`);
+          renderField(l, field, 'output');
         });
         l('}');
       } else {
         l(`export type ${typeNames.outputName} = {};`);
       }
       l();
+      formatBlockDocComment(`${api.description} API 响应数据`, api.since).forEach((line) => {
+        l(line);
+      });
+      if (api.responseFields !== undefined) {
+        l(`export interface ${getZodInputTypeName(typeNames.outputName)} {`);
+        api.responseFields.forEach((field) => {
+          renderField(l, field, 'input');
+        });
+        l('}');
+      } else {
+        l(`export type ${getZodInputTypeName(typeNames.outputName)} = {};`);
+      }
+      l();
     });
   });
   l('export interface ApiCategories {');
@@ -158,13 +260,33 @@ export function generateTypeScriptStaticSpec(ir: IR): string {
       });
       l(`    ${api.endpoint}: {`);
       l(`      request: ${typeNames.inputName};`);
+      l(`      request_ZodInput: ${getZodInputTypeName(typeNames.inputName)};`);
       l(`      response: ${typeNames.outputName};`);
+      l(`      response_ZodInput: ${getZodInputTypeName(typeNames.outputName)};`);
       l('    };');
     });
     l('  };');
   });
   l('}');
   l();
+  l('export interface ApiEndpoints {');
+  ir.apiCategories.forEach((category) => {
+    category.apis.forEach((api) => {
+      const typeNames = getApiTypeNames(api.endpoint);
+      formatBlockDocComment(api.description, api.since, '  ').forEach((line) => {
+        l(line);
+      });
+      l(`  /** ${api.description} */`);
+      l(`  '${api.endpoint}': {`);
+      l(`    request: ${typeNames.inputName};`);
+      l(`    request_ZodInput: ${getZodInputTypeName(typeNames.inputName)};`);
+      l(`    response: ${typeNames.outputName};`);
+      l(`    response_ZodInput: ${getZodInputTypeName(typeNames.outputName)};`);
+      l('  };');
+    });
+  });
+  l('}');
+  l();
 
   return writer.toString();
 }