@typespec/emitter-framework 0.8.0-dev.2 → 0.8.0-dev.3

package/src/typescript/components/interface-member.tsx

@@ -1,3 +1,4 @@
+import { Children } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { isNeverType, ModelProperty, Operation } from "@typespec/compiler";
 import { getHttpPart } from "@typespec/http";
@@ -7,6 +8,7 @@ import { TypeExpression } from "./type-expression.js";
 
 export interface InterfaceMemberProps {
   type: ModelProperty | Operation;
+  doc?: Children;
   optional?: boolean;
 }
 
@@ -14,6 +16,7 @@ export function InterfaceMember(props: InterfaceMemberProps) {
   const { $ } = useTsp();
   const namer = ts.useTSNamePolicy();
   const name = namer.getName(props.type.name, "object-member-getter");
+  const doc = props.doc ?? $.type.getDoc(props.type);
 
   if ($.modelProperty.is(props.type)) {
     if (isNeverType(props.type.type)) {
@@ -28,6 +31,7 @@ export function InterfaceMember(props: InterfaceMemberProps) {
 
     return (
       <ts.InterfaceMember
+        doc={doc}
         name={name}
         optional={props.optional ?? props.type.optional}
         type={<TypeExpression type={unpackedType} />}

package/src/typescript/components/interface-method.tsx

@@ -1,12 +1,14 @@
-import { splitProps } from "@alloy-js/core/jsx-runtime";
+import { Children, splitProps } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { Operation } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
 import { buildParameterDescriptors, getReturnType } from "../utils/operation.js";
 import { TypeExpression } from "./type-expression.jsx";
 
 export interface InterfaceMethodPropsWithType extends Omit<ts.InterfaceMethodProps, "name"> {
   type: Operation;
   name?: string;
+  doc?: Children;
   parametersMode?: "prepend" | "append" | "replace";
 }
 
@@ -18,6 +20,7 @@ export type InterfaceMethodProps = InterfaceMethodPropsWithType | ts.InterfaceMe
  * provided will take precedence.
  */
 export function InterfaceMethod(props: Readonly<InterfaceMethodProps>) {
+  const { $ } = useTsp();
   const isTypeSpecTyped = "type" in props;
   if (!isTypeSpecTyped) {
     return <ts.InterfaceMethod {...props} />;
@@ -36,6 +39,8 @@ export function InterfaceMethod(props: Readonly<InterfaceMethodProps>) {
     mode: props.parametersMode,
   });
 
+  const doc = props.doc ?? $.type.getDoc(props.type);
+
   return (
     <ts.InterfaceMethod
       {...forwardProps}
@@ -43,6 +48,7 @@ export function InterfaceMethod(props: Readonly<InterfaceMethodProps>) {
       name={name}
       returnType={returnType}
       parameters={allParameters}
+      doc={doc}
     />
   );
 }

package/src/typescript/components/type-alias-declaration.tsx

@@ -30,11 +30,12 @@ export function TypeAliasDeclaration(props: TypeAliasDeclarationProps) {
     reportDiagnostic($.program, { code: "type-declaration-missing-name", target: props.type });
   }
 
+  const doc = props.doc ?? $.type.getDoc(props.type);
   const refkeys = declarationRefkeys(props.refkey, props.name);
 
   const name = ts.useTSNamePolicy().getName(originalName, "type");
   return (
-    <ts.TypeDeclaration {...props} name={name} refkey={refkeys}>
+    <ts.TypeDeclaration doc={doc} {...props} name={name} refkey={refkeys}>
       <TypeExpression type={props.type} noReference />
       {props.children}
     </ts.TypeDeclaration>

package/src/typescript/components/type-declaration.tsx

@@ -1,5 +1,6 @@
 import * as ts from "@alloy-js/typescript";
 import { Type } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
 import { declarationRefkeys } from "../utils/refkey.js";
 import { EnumDeclaration } from "./enum-declaration.js";
 import { InterfaceDeclaration } from "./interface-declaration.jsx";
@@ -14,9 +15,9 @@ export interface TypeDeclarationProps extends Omit<ts.TypeDeclarationProps, "nam
 export type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
 
 export function TypeDeclaration(props: TypeDeclarationProps) {
+  const { $ } = useTsp();
   if (!props.type) {
     const refkeys = declarationRefkeys(props.refkey, props.name);
-
     return (
       <ts.TypeDeclaration
         {...(props as WithRequired<ts.TypeDeclarationProps, "name">)}
@@ -26,16 +27,17 @@ export function TypeDeclaration(props: TypeDeclarationProps) {
   }
 
   const { type, ...restProps } = props;
+  const doc = props.doc ?? $.type.getDoc(type);
   switch (type.kind) {
     case "Model":
-      return <InterfaceDeclaration type={type} {...restProps} />;
+      return <InterfaceDeclaration doc={doc} type={type} {...restProps} />;
     case "Union":
-      return <UnionDeclaration type={type} {...restProps} />;
+      return <UnionDeclaration doc={doc} type={type} {...restProps} />;
     case "Enum":
-      return <EnumDeclaration type={type} {...restProps} />;
+      return <EnumDeclaration doc={doc} type={type} {...restProps} />;
     case "Scalar":
-      return <TypeAliasDeclaration type={type} {...restProps} />;
+      return <TypeAliasDeclaration doc={doc} type={type} {...restProps} />;
     case "Operation":
-      return <TypeAliasDeclaration type={type} {...restProps} />;
+      return <TypeAliasDeclaration doc={doc} type={type} {...restProps} />;
   }
 }

package/src/typescript/components/union-declaration.tsx

@@ -1,3 +1,4 @@
+import { Children } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
 import { Enum, Union } from "@typespec/compiler";
 import { useTsp } from "../../core/context/tsp-context.js";
@@ -7,6 +8,7 @@ import { UnionExpression } from "./union-expression.js";
 
 export interface TypedUnionDeclarationProps extends Omit<ts.TypeDeclarationProps, "name"> {
   type: Union | Enum;
+  doc?: Children;
   name?: string;
 }
 
@@ -29,8 +31,9 @@ export function UnionDeclaration(props: UnionDeclarationProps) {
 
   const name = ts.useTSNamePolicy().getName(originalName!, "type");
 
+  const doc = props.doc ?? $.type.getDoc(type);
   return (
-    <ts.TypeDeclaration {...props} name={name} refkey={refkeys}>
+    <ts.TypeDeclaration doc={doc} {...props} name={name} refkey={refkeys}>
       <UnionExpression type={type}>{coreProps.children}</UnionExpression>
     </ts.TypeDeclaration>
   );

package/src/typescript/components/union-expression.tsx

@@ -1,8 +1,9 @@
 import * as ay from "@alloy-js/core";
 import { Children } from "@alloy-js/core";
 import * as ts from "@alloy-js/typescript";
-import { Enum, EnumMember, Union, UnionVariant } from "@typespec/compiler";
+import { compilerAssert, Enum, EnumMember, Union, UnionVariant } from "@typespec/compiler";
 import { useTsp } from "../../core/context/tsp-context.js";
+import { efRefkey } from "../utils/refkey.js";
 import { TypeExpression } from "./type-expression.jsx";
 
 export interface UnionExpressionProps {
@@ -19,11 +20,30 @@ export function UnionExpression({ type, children }: UnionExpressionProps) {
 
   const variants = (
     <ay.For joiner={" | "} each={items}>
-      {(_, value) => {
-        if ($.enumMember.is(value)) {
-          return <ts.ValueExpression jsValue={value.value ?? value.name} />;
-        } else {
-          return <TypeExpression type={value.type} />;
+      {(_, type) => {
+        if ($.enumMember.is(type)) {
+          return <ts.ValueExpression jsValue={type.value ?? type.name} />;
+        }
+
+        const discriminatedUnion = $.union.getDiscriminatedUnion(type.union);
+        switch (discriminatedUnion?.options.envelope) {
+          case "object":
+            return (
+              <ObjectEnvelope
+                discriminatorPropertyName={discriminatedUnion.options.discriminatorPropertyName}
+                envelopePropertyName={discriminatedUnion.options.envelopePropertyName}
+                type={type}
+              />
+            );
+          case "none":
+            return (
+              <NoneEnvelope
+                discriminatorPropertyName={discriminatedUnion.options.discriminatorPropertyName}
+                type={type}
+              />
+            );
+          default:
+            return <TypeExpression type={type.type} />;
         }
       }}
     </ay.For>
@@ -32,10 +52,83 @@ export function UnionExpression({ type, children }: UnionExpressionProps) {
   if (children || (Array.isArray(children) && children.length)) {
     return (
       <>
-        {variants} {` | ${children}`}
+        {variants} {`| ${children}`}
       </>
     );
   }
 
   return variants;
 }
+
+interface ObjectEnvelopeProps {
+  type: UnionVariant;
+  discriminatorPropertyName: string;
+  envelopePropertyName: string;
+}
+
+/**
+ * Renders a discriminated union with "object" envelope style
+ * where model properties are nested inside an envelope
+ */
+function ObjectEnvelope(props: ObjectEnvelopeProps) {
+  const { $ } = useTsp();
+
+  const envelope = $.model.create({
+    properties: {
+      [props.discriminatorPropertyName]: $.modelProperty.create({
+        name: props.discriminatorPropertyName,
+        type: $.literal.createString(props.type.name as string),
+      }),
+      [props.envelopePropertyName]: $.modelProperty.create({
+        name: props.envelopePropertyName,
+        type: props.type.type,
+      }),
+    },
+  });
+
+  return <TypeExpression type={envelope} />;
+}
+
+interface NoneEnvelopeProps {
+  type: UnionVariant;
+  discriminatorPropertyName: string;
+}
+
+/**
+ * Renders a discriminated union with "none" envelope style
+ * where discriminator property sits alongside model properties
+ */
+function NoneEnvelope(props: NoneEnvelopeProps) {
+  const { $ } = useTsp();
+
+  compilerAssert(
+    $.model.is(props.type.type),
+    "Expected all union variants to be models when using a discriminated union with no envelope",
+  );
+
+  // Render anonymous models as a set of properties + the discriminator
+  if ($.model.isExpresion(props.type.type)) {
+    const model = $.model.create({
+      properties: {
+        [props.discriminatorPropertyName]: $.modelProperty.create({
+          name: props.discriminatorPropertyName,
+          type: $.literal.createString(props.type.name as string),
+        }),
+        ...Object.fromEntries(props.type.type.properties),
+      },
+    });
+    return <TypeExpression type={model} />;
+  }
+
+  return (
+    <ay.List joiner={" & "}>
+      <ts.ObjectExpression>
+        <ts.ObjectProperty
+          name={props.discriminatorPropertyName}
+          value={<ts.ValueExpression jsValue={props.type.name} />}
+        />
+      </ts.ObjectExpression>
+      <>{efRefkey(props.type.type)}</>
+    </ay.List>
+  );
+}

package/src/typescript/utils/operation.ts

@@ -47,10 +47,13 @@ export function buildParameterDescriptors(
 }
 
 export function buildParameterDescriptor(modelProperty: ModelProperty): ts.ParameterDescriptor {
+  const { $ } = useTsp();
   const namePolicy = ts.useTSNamePolicy();
   const paramName = namePolicy.getName(modelProperty.name, "parameter");
   const isOptional = modelProperty.optional || modelProperty.defaultValue !== undefined;
+  const doc = $.type.getDoc(modelProperty);
   return {
+    doc,
     name: paramName,
     refkey: efRefkey(modelProperty),
     optional: isOptional,

package/test/typescript/components/enum-declaration.test.tsx

@@ -34,6 +34,78 @@ describe("Typescript Enum Declaration", () => {
     `);
   });
 
+  it("adds JSDoc from TypeSpec", async () => {
+    const code = `
+      /**
+       * This is a test enum
+       */
+      enum Foo {
+        @doc("This is one")
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `;
+    const output = await getEmitOutput(code, (program) => {
+      const Foo = program.resolveTypeReference("Foo")[0]! as Enum;
+      return (
+        <TspContext.Provider value={{ program }}>
+          <EnumDeclaration type={Foo} />
+        </TspContext.Provider>
+      );
+    });
+
+    expect(output).toBe(d`
+      /**
+       * This is a test enum
+       */
+      enum Foo {
+        /**
+         * This is one
+         */
+        one = 1,
+        two = 2,
+        three = 3
+      }
+    `);
+  });
+
+  it("explicit doc take precedence", async () => {
+    const code = `
+      /**
+       * This is a test enum
+       */
+      enum Foo {
+        @doc("This is one")
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `;
+    const output = await getEmitOutput(code, (program) => {
+      const Foo = program.resolveTypeReference("Foo")[0]! as Enum;
+      return (
+        <TspContext.Provider value={{ program }}>
+          <EnumDeclaration type={Foo} doc={["This is an explicit doc"]} />
+        </TspContext.Provider>
+      );
+    });
+
+    expect(output).toBe(d`
+      /**
+       * This is an explicit doc
+       */
+      enum Foo {
+        /**
+         * This is one
+         */
+        one = 1,
+        two = 2,
+        three = 3
+      }
+    `);
+  });
+
   it("takes a union type parameter", async () => {
     const code = `
       union Foo {

package/test/typescript/components/function-declaration.test.tsx

@@ -36,6 +36,84 @@ describe("Typescript Function Declaration", () => {
         expect(actualContent).toBe(expectedContent);
       });
 
+      it("creates a function with JSDoc", async () => {
+        const program = await getProgram(`
+        namespace DemoService;
+        /**
+         * This is a test function
+         */
+        op getName(
+        @doc("This is the id")
+        id: string, name: string): string;
+        `);
+
+        const [namespace] = program.resolveTypeReference("DemoService");
+        const operation = Array.from((namespace as Namespace).operations.values())[0];
+
+        const res = render(
+          <Output program={program}>
+            <SourceFile path="test.ts">
+              <FunctionDeclaration type={operation} />
+            </SourceFile>
+          </Output>,
+        );
+
+        const testFile = res.contents.find((file) => file.path === "test.ts");
+        assert(testFile, "test.ts file not rendered");
+        const actualContent = await format(testFile.contents as string, { parser: "typescript" });
+        const expectedContent = await format(
+          `
+          /**
+           * This is a test function
+           * 
+           * @param {string} id - This is the id
+           * @param {string} name
+           */
+          function getName(id: string, name: string): string{}`,
+          {
+            parser: "typescript",
+          },
+        );
+        expect(actualContent).toBe(expectedContent);
+      });
+
+      it("creates a function with overridden JSDoc", async () => {
+        const program = await getProgram(`
+        namespace DemoService;
+        /**
+         * This is a test function
+         */
+        op getName(id: string): string;`);
+
+        const [namespace] = program.resolveTypeReference("DemoService");
+        const operation = Array.from((namespace as Namespace).operations.values())[0];
+
+        const res = render(
+          <Output program={program}>
+            <SourceFile path="test.ts">
+              <FunctionDeclaration doc={["This is a custom description"]} type={operation} />
+            </SourceFile>
+          </Output>,
+        );
+
+        const testFile = res.contents.find((file) => file.path === "test.ts");
+        assert(testFile, "test.ts file not rendered");
+        const actualContent = await format(testFile.contents as string, { parser: "typescript" });
+        const expectedContent = await format(
+          `
+          /**
+           * This is a custom description
+           *
+           * @param {string} id
+           */
+          function getName(id: string): string{}`,
+          {
+            parser: "typescript",
+          },
+        );
+        expect(actualContent).toBe(expectedContent);
+      });
+
       it("creates an async function", async () => {
         const program = await getProgram(`
         namespace DemoService;