adorn-api 1.0.9 → 1.0.11

package/dist/cli.js

@@ -137,6 +137,7 @@ function analyzeMethod(node, className, checker) {
   if (!signature) return null;
   let returnType = checker.getReturnTypeOfSignature(signature);
   returnType = unwrapPromise(returnType, checker);
+  const returnTypeNode = unwrapPromiseTypeNode(node.type);
   const parameters = [];
   for (let i = 0; i < node.parameters.length; i++) {
     const param = node.parameters[i];
@@ -153,7 +154,7 @@ function analyzeMethod(node, className, checker) {
   }
   const pathParamNames = extractPathParams(path4);
   const pathParamIndices = matchPathParamsToIndices(pathParamNames, parameters);
-  const { bodyParamIndex, queryParamIndices, queryObjectParamIndex, headerObjectParamIndex, cookieObjectParamIndex, bodyContentType } = classifyParameters(parameters, httpMethod, pathParamIndices, checker);
+  const { bodyParamIndex, queryParamIndices, queryObjectParamIndex, headerObjectParamIndex, cookieObjectParamIndex, paginationParamIndex, bodyContentType } = classifyParameters(parameters, httpMethod, pathParamIndices, checker);
   return {
     methodName,
     httpMethod,
@@ -161,6 +162,7 @@ function analyzeMethod(node, className, checker) {
     operationId: defaultOperationId(className, methodName),
     methodDeclaration: node,
     returnType,
+    returnTypeNode,
     parameters,
     pathParamIndices,
     bodyParamIndex,
@@ -168,6 +170,7 @@ function analyzeMethod(node, className, checker) {
     queryObjectParamIndex,
     headerObjectParamIndex,
     cookieObjectParamIndex,
+    paginationParamIndex,
     bodyContentType
   };
 }
@@ -193,6 +196,7 @@ function classifyParameters(parameters, httpMethod, pathParamIndices, checker) {
   let queryObjectParamIndex = null;
   let headerObjectParamIndex = null;
   let cookieObjectParamIndex = null;
+  let paginationParamIndex = null;
   const isBodyMethod = ["POST", "PUT", "PATCH"].includes(httpMethod);
   for (let i = 0; i < parameters.length; i++) {
     const param = parameters[i];
@@ -219,6 +223,11 @@ function classifyParameters(parameters, httpMethod, pathParamIndices, checker) {
       usedIndices.add(i);
       continue;
     }
+    if (typeStr === "PaginationParams") {
+      paginationParamIndex = i;
+      usedIndices.add(i);
+      continue;
+    }
     if (isBodyMethod && bodyParamIndex === null) {
       bodyParamIndex = i;
       usedIndices.add(i);
@@ -239,6 +248,7 @@ function classifyParameters(parameters, httpMethod, pathParamIndices, checker) {
     queryObjectParamIndex,
     headerObjectParamIndex,
     cookieObjectParamIndex,
+    paginationParamIndex,
     bodyContentType: void 0
   };
 }
@@ -291,6 +301,15 @@ function unwrapPromise(type, checker) {
   }
   return type;
 }
+function unwrapPromiseTypeNode(typeNode) {
+  if (!typeNode) return void 0;
+  if (ts2.isTypeReferenceNode(typeNode)) {
+    if (ts2.isIdentifier(typeNode.typeName) && typeNode.typeName.text === "Promise") {
+      return typeNode.typeArguments?.[0] ?? typeNode;
+    }
+  }
+  return typeNode;
+}
 
 // src/compiler/schema/openapi.ts
 import ts6 from "typescript";
@@ -337,10 +356,10 @@ function typeToJsonSchema(type, ctx, typeNode) {
     return { type: "boolean", enum: [intrinsic === "true"] };
   }
   if (type.isUnion()) {
-    return handleUnion(type.types, ctx, typeNode);
+    return handleUnion(type, ctx, typeNode);
   }
   if (type.isIntersection()) {
-    return handleIntersection(type.types, ctx, typeNode);
+    return handleIntersection(type, ctx, typeNode);
   }
   if (checker.isArrayType(type)) {
     const typeArgs = type.typeArguments;
@@ -377,56 +396,96 @@ function isSetType(type, checker) {
   if (name === "Set") return true;
   return false;
 }
-function handleUnion(types, ctx, typeNode) {
-  const nullType = types.find((t) => t.flags & ts3.TypeFlags.Null);
-  const otherTypes = types.filter((t) => !(t.flags & ts3.TypeFlags.Null) && !(t.flags & ts3.TypeFlags.Undefined));
-  const allStringLiterals = otherTypes.every((t) => t.flags & ts3.TypeFlags.StringLiteral);
-  if (allStringLiterals && otherTypes.length > 0) {
-    const enumValues = otherTypes.map((t) => t.value);
-    const schema = { type: "string", enum: enumValues };
-    if (nullType) {
-      schema.type = ["string", "null"];
-    }
-    return schema;
+function getSchemaName(type, typeNode) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  const aliasName = aliasSymbol?.getName();
+  if (aliasName && aliasName !== "__type") {
+    return aliasName;
   }
-  if (otherTypes.length === 1 && nullType) {
-    const innerSchema = typeToJsonSchema(otherTypes[0], ctx);
-    if (typeof innerSchema.type === "string") {
-      innerSchema.type = [innerSchema.type, "null"];
-    }
-    return innerSchema;
-  }
-  if (otherTypes.length > 1) {
-    const branches = otherTypes.map((t) => typeToJsonSchema(t, ctx));
-    const hasNull = !!nullType;
-    const result = {};
-    if (hasNull) {
-      result.anyOf = [...branches, { type: "null" }];
-    } else {
-      result.anyOf = branches;
-    }
-    const discriminatorResult = detectDiscriminatedUnion(otherTypes, ctx, branches);
-    if (discriminatorResult) {
-      result.oneOf = branches;
-      result.discriminator = discriminatorResult;
-    }
-    return result;
+  const symbol = type.getSymbol();
+  const symbolName = symbol?.getName?.();
+  if (symbolName && symbolName !== "__type") {
+    return symbolName;
   }
-  if (otherTypes.length === 1) {
-    return typeToJsonSchema(otherTypes[0], ctx);
+  const nodeName = getExplicitTypeNameFromNode(typeNode);
+  if (nodeName && nodeName !== "__type") {
+    return nodeName;
   }
-  return {};
+  return null;
 }
-function handleIntersection(types, ctx, typeNode) {
-  const brandCollapsed = tryCollapseBrandedIntersection(types, ctx, typeNode);
-  if (brandCollapsed) {
-    return brandCollapsed;
+function buildNamedSchema(type, ctx, typeNode, build) {
+  const name = getSchemaName(type, typeNode);
+  if (!name) {
+    return build();
   }
-  const allOf = [];
-  for (const t of types) {
-    allOf.push(typeToJsonSchema(t, ctx));
+  const { components, typeStack } = ctx;
+  if (components.has(name) || typeStack.has(type)) {
+    return { $ref: `#/components/schemas/${name}` };
   }
-  return { allOf };
+  typeStack.add(type);
+  const schema = build();
+  typeStack.delete(type);
+  if (!components.has(name)) {
+    components.set(name, schema);
+  }
+  return { $ref: `#/components/schemas/${name}` };
+}
+function handleUnion(type, ctx, typeNode) {
+  return buildNamedSchema(type, ctx, typeNode, () => {
+    const types = type.types;
+    const nullType = types.find((t) => t.flags & ts3.TypeFlags.Null);
+    const otherTypes = types.filter((t) => !(t.flags & ts3.TypeFlags.Null) && !(t.flags & ts3.TypeFlags.Undefined));
+    const allStringLiterals = otherTypes.every((t) => t.flags & ts3.TypeFlags.StringLiteral);
+    if (allStringLiterals && otherTypes.length > 0) {
+      const enumValues = otherTypes.map((t) => t.value);
+      const schema = { type: "string", enum: enumValues };
+      if (nullType) {
+        schema.type = ["string", "null"];
+      }
+      return schema;
+    }
+    if (otherTypes.length === 1 && nullType) {
+      const innerSchema = typeToJsonSchema(otherTypes[0], ctx);
+      if (typeof innerSchema.type === "string") {
+        innerSchema.type = [innerSchema.type, "null"];
+      }
+      return innerSchema;
+    }
+    if (otherTypes.length > 1) {
+      const branches = otherTypes.map((t) => typeToJsonSchema(t, ctx));
+      const hasNull = !!nullType;
+      const result = {};
+      if (hasNull) {
+        result.anyOf = [...branches, { type: "null" }];
+      } else {
+        result.anyOf = branches;
+      }
+      const discriminatorResult = detectDiscriminatedUnion(otherTypes, ctx, branches);
+      if (discriminatorResult) {
+        result.oneOf = branches;
+        result.discriminator = discriminatorResult;
+      }
+      return result;
+    }
+    if (otherTypes.length === 1) {
+      return typeToJsonSchema(otherTypes[0], ctx);
+    }
+    return {};
+  });
+}
+function handleIntersection(type, ctx, typeNode) {
+  return buildNamedSchema(type, ctx, typeNode, () => {
+    const types = type.types;
+    const brandCollapsed = tryCollapseBrandedIntersection(types, ctx, typeNode);
+    if (brandCollapsed) {
+      return brandCollapsed;
+    }
+    const allOf = [];
+    for (const t of types) {
+      allOf.push(typeToJsonSchema(t, ctx));
+    }
+    return { allOf };
+  });
 }
 function tryCollapseBrandedIntersection(types, ctx, typeNode) {
   const { checker } = ctx;
@@ -557,8 +616,8 @@ function handleObjectType(type, ctx, typeNode) {
   typeStack.delete(type);
   return schema;
 }
-function getTypeNameFromNode(typeNode, ctx) {
-  if (!typeNode) return `Anonymous_${ctx.typeNameStack.length}`;
+function getExplicitTypeNameFromNode(typeNode) {
+  if (!typeNode) return null;
   if (ts3.isTypeReferenceNode(typeNode)) {
     if (ts3.isIdentifier(typeNode.typeName)) {
       return typeNode.typeName.text;
@@ -569,6 +628,11 @@ function getTypeNameFromNode(typeNode, ctx) {
       return typeNode.parent.name.text;
     }
   }
+  return null;
+}
+function getTypeNameFromNode(typeNode, ctx) {
+  const explicitName = getExplicitTypeNameFromNode(typeNode);
+  if (explicitName) return explicitName;
   return `Anonymous_${ctx.typeNameStack.length}`;
 }
 function buildObjectSchema(type, ctx, typeNode) {
@@ -867,7 +931,7 @@ function buildOperation(operation, ctx, controllerConsumes) {
   if (parameters.length > 0) {
     op.parameters = parameters;
   }
-  const responseSchema = typeToJsonSchema(operation.returnType, ctx);
+  const responseSchema = typeToJsonSchema(operation.returnType, ctx, operation.returnTypeNode);
   const status = operation.httpMethod === "POST" ? 201 : 200;
   op.responses[status] = {
     description: status === 201 ? "Created" : "OK",
@@ -1085,7 +1149,8 @@ function buildOperationEntry(op, ctx) {
     path: [],
     query: [],
     headers: [],
-    cookies: []
+    cookies: [],
+    paginationParamIndex: op.paginationParamIndex
   };
   buildPathArgs(op, ctx, args);
   buildQueryArgs(op, ctx, args);
@@ -1104,7 +1169,7 @@ function buildOperationEntry(op, ctx) {
       };
     }
   }
-  const responseSchema = typeToJsonSchema(op.returnType, ctx);
+  const responseSchema = typeToJsonSchema(op.returnType, ctx, op.returnTypeNode);
   const status = op.httpMethod === "POST" ? 201 : 200;
   let schemaRef = responseSchema.$ref;
   let isArray = false;