feat: Add getTypeExpressionOrThrow() to JSDocReturnTag and `JSDoc…

…PropertyLikeTag`

packages/ts-morph/lib/ts-morph.d.ts

@@ -5221,9 +5221,13 @@ export declare function JSDocPropertyLikeTag<T extends Constructor<JSDocProperty
 
 export interface JSDocPropertyLikeTag {
     /**
-     * Gets the type expression node of the JS doc property like tag.
+     * Gets the type expression node of the JS doc tag if it exists.
      */
     getTypeExpression(): JSDocTypeExpression | undefined;
+    /**
+     * Gets the type expression node of the JS doc tag or throws if it doesn't exist.
+     */
+    getTypeExpressionOrThrow(): JSDocTypeExpression;
     /**
      * Gets the name of the JS doc property like tag.
      */
@@ -5342,9 +5346,13 @@ export declare class JSDocPropertyTag extends JSDocPropertyTagBase<ts.JSDocPrope
  */
 export declare class JSDocReturnTag extends JSDocTag<ts.JSDocReturnTag> {
     /**
-     * Gets the type expression node of the JS doc property return tag.
+     * Gets the type expression node of the JS doc return tag if it exists.
      */
     getTypeExpression(): JSDocTypeExpression | undefined;
+    /**
+     * Gets the type expression node of the JS doc return tag or throws if it doesn't exist.
+     */
+    getTypeExpressionOrThrow(): JSDocTypeExpression;
     /** @inheritdoc **/
     getParent(): NodeParentType<ts.JSDocReturnTag>;
     /** @inheritdoc **/

packages/ts-morph/src/compiler/ast/doc/JSDocReturnTag.ts

@@ -1,14 +1,21 @@
-import { ts } from "@ts-morph/common";
+import { ts, errors } from "@ts-morph/common";
 import { JSDocTag } from "./JSDocTag";
 
 /**
  * JS doc return tag node.
  */
 export class JSDocReturnTag extends JSDocTag<ts.JSDocReturnTag> {
     /**
-     * Gets the type expression node of the JS doc property return tag.
+     * Gets the type expression node of the JS doc return tag if it exists.
      */
     getTypeExpression() {
         return this._getNodeFromCompilerNodeIfExists(this.compilerNode.typeExpression);
     }
+
+    /**
+     * Gets the type expression node of the JS doc return tag or throws if it doesn't exist.
+     */
+    getTypeExpressionOrThrow() {
+        return errors.throwIfNullOrUndefined(this.getTypeExpression(), `Expected to find a ${nameof(JSDocReturnTag)}'s type expression.`);
+    }
 }

packages/ts-morph/src/compiler/ast/doc/base/JSDocPropertyLikeTag.ts

@@ -1,4 +1,4 @@
-import { ts } from "@ts-morph/common";
+import { ts, errors } from "@ts-morph/common";
 import { Constructor } from "../../../../types";
 import { EntityName } from "../../aliases";
 import { Node } from "../../common";
@@ -8,8 +8,10 @@ import { JSDocTypeExpression } from "../JSDocTypeExpression";
 export type JSDocPropertyLikeTagExtensionType = Node<ts.JSDocPropertyLikeTag> & JSDocTag;
 
 export interface JSDocPropertyLikeTag {
-    /** Gets the type expression node of the JS doc property like tag. */
+    /** Gets the type expression node of the JS doc tag if it exists. */
     getTypeExpression(): JSDocTypeExpression | undefined;
+    /** Gets the type expression node of the JS doc tag or throws if it doesn't exist. */
+    getTypeExpressionOrThrow(): JSDocTypeExpression;
     /** Gets the name of the JS doc property like tag. */
     getName(): string;
     /** Gets the name node of the JS doc property like tag. */
@@ -21,10 +23,14 @@ export interface JSDocPropertyLikeTag {
 export function JSDocPropertyLikeTag<T extends Constructor<JSDocPropertyLikeTagExtensionType>>(Base: T): Constructor<JSDocPropertyLikeTag> & T {
     return class extends Base implements JSDocPropertyLikeTag {
         // todo: more methods
-        getTypeExpression() {
+        getTypeExpression(): JSDocTypeExpression | undefined {
             return this._getNodeFromCompilerNodeIfExists(this.compilerNode.typeExpression);
         }
 
+        getTypeExpressionOrThrow() {
+            return errors.throwIfNullOrUndefined(this.getTypeExpression(), `Expected to find a JS doc type expression.`);
+        }
+
         getName() {
             return this.getNameNode().getText();
         }

packages/ts-morph/src/tests/compiler/ast/doc/jsDocReturnTagTests.ts

@@ -9,14 +9,35 @@ describe(nameof(JSDocReturnTag), () => {
     }
 
     describe(nameof<JSDocReturnTag>(d => d.getTypeExpression), () => {
+        function doTest(text: string, expectedValue: string | undefined) {
+            const { descendant } = getInfo(text);
+            expect(descendant.getTypeExpression()?.getTypeNode().getText()).to.equal(expectedValue);
+        }
+
+        it("should get undefined when there is no type given", () => {
+            doTest("/** @returns t - String */\nfunction test() {}", undefined);
+        });
+
+        it("should get when type is given", () => {
+            doTest("/** @returns {boolean} t - String */\nfunction test() {}", "boolean");
+        });
+    });
+
+    describe(nameof<JSDocReturnTag>(d => d.getTypeExpressionOrThrow), () => {
+        function doTest(text: string, expectedValue: string | undefined) {
+            const { descendant } = getInfo(text);
+            if (expectedValue == null)
+                expect(() => descendant.getTypeExpressionOrThrow()).to.throw();
+            else
+                expect(descendant.getTypeExpressionOrThrow().getTypeNode().getText()).to.equal(expectedValue);
+        }
+
         it("should get undefined when there is no type given", () => {
-            const { descendant } = getInfo("/** @returns t - String */\nfunction test() {}");
-            expect(descendant.getTypeExpression()).to.be.undefined;
+            doTest("/** @returns t - String */\nfunction test() {}", undefined);
         });
 
         it("should get when type is given", () => {
-            const { descendant } = getInfo("/** @returns {boolean} t - String */\nfunction test() {}");
-            expect(descendant.getTypeExpression()!.getTypeNode().getText()).to.equal("boolean");
+            doTest("/** @returns {boolean} t - String */\nfunction test() {}", "boolean");
         });
     });
 });