typescript-eslint · kirkwaiblinger · Jun 17, 2024 · Jun 6, 2024 · Jun 7, 2024 · Jun 17, 2024
diff --git a/docs/packages/Type_Utils.mdx b/docs/packages/Type_Utils.mdx
@@ -0,0 +1,20 @@
+---
+id: type-utils
+sidebar_label: type-utils
+---
+
+# `@typescript-eslint/type-utils`
+
+<PackageLink packageName="type-utils" scope="@typescript-eslint" />
+
+> Type utilities for working with TypeScript within ESLint rules. ✨
+
+This package contains public utilities for working with TypeScript types that ESLint rules often use.
+Rules declared in [`@typescript-eslint/eslint-plugin`](./ESLint_Plugin.mdx) use these utility functions.
+
+The utilities in this package are both:
+
+- More generally ESLint-focused than the broad TypeScript utilities in [`ts-api-utils`](https://npmjs.com/package/ts-api-utils)
+- Separated from [`@typescript-eslint/utils`](./Utils.mdx) so that that package does not require a dependency on `typescript`
+
+> See [Custom Rules](../developers/Custom_Rules.mdx) for documentation on creating your own custom ESLint rules for TypeScript code.
diff --git a/packages/type-utils/src/builtinSymbolLikes.ts b/packages/type-utils/src/builtinSymbolLikes.ts
@@ -3,18 +3,24 @@ import * as ts from 'typescript';
 import { isSymbolFromDefaultLibrary } from './isSymbolFromDefaultLibrary';

 /**
- * class Foo extends Promise<number> {}
- * Foo.reject
- *  ^ PromiseLike
+ * @example
+ * ```ts
+ * class DerivedClass extends Promise<number> {}
+ * DerivedClass.reject
+ * // ^ PromiseLike
+ * ```
 */
 export function isPromiseLike(program: ts.Program, type: ts.Type): boolean {
  return isBuiltinSymbolLike(program, type, 'Promise');
 }

 /**
- * const foo = Promise
- * foo.reject
- *  ^ PromiseConstructorLike
+ * @example
+ * ```ts
+ * const value = Promise
+ * value.reject
+ * // ^ PromiseConstructorLike
+ * ```
 */
 export function isPromiseConstructorLike(
  program: ts.Program,
@@ -24,17 +30,23 @@ export function isPromiseConstructorLike(
 }

 /**
+ * @example
+ * ```ts
 * class Foo extends Error {}
 * new Foo()
- *      ^ ErrorLike
+ * //   ^ ErrorLike
+ * ```
 */
 export function isErrorLike(program: ts.Program, type: ts.Type): boolean {
  return isBuiltinSymbolLike(program, type, 'Error');
 }

 /**
+ * @example
+ * ```ts
 * type T = Readonly<Error>
- *      ^ ReadonlyErrorLike
+ * //   ^ ReadonlyErrorLike
+ * ```
 */
 export function isReadonlyErrorLike(
  program: ts.Program,
@@ -50,8 +62,11 @@ export function isReadonlyErrorLike(
 }

 /**
+ * @example
+ * ```ts
 * type T = Readonly<{ foo: 'bar' }>
- *      ^ ReadonlyTypeLike
+ * //   ^ ReadonlyTypeLike
+ * ```
 */
 export function isReadonlyTypeLike(
  program: ts.Program,

diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js
@@ -84,6 +84,7 @@ module.exports = {
        'packages/parser',
        'packages/rule-tester',
        'packages/scope-manager',
+        'packages/type-utils',
        'packages/typescript-estree',
        'packages/typescript-eslint',
        'packages/utils',