node-expand-my-type

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

node-expand-my-type

★ 16 Open GitHub ↗

Expand TypeScript type expressions programmatically

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Expand My Type

</div>

In TypeScript, expanding a type (also known as computing, resolving,
simplifying, unpacking, or unwrapping) refers to converting a type expression
into a flattened type that doesn't reference other types. This is mostly done
to improve the readability of type hints shown in editors/IDEs.

**Expand My Type** provides a programmatic way to expand type expressions in
TypeScript (see [How It Works](#how-it-works) section for more information). It
gets the source code as input, along with a type expression and returns the
expanded form as a string. That can be useful for code-generation, testing, and
debugging complex type errors.

Under the hood, it uses the [TypeScript Compiler API][ts-compiler-api] to expand
the type expression and optionally formats the output using Biome.

## CLI

### Installation

To install the CLI globally, run:

```sh
npm install -g expand-my-type
```

Alternatively, the CLI can be run using `npx`:

```sh
npx expand-my-type
```

### CLI Usage

```
Usage:
  expand-my-type [options] <source-file> <expression>

Options:
  -h, --help                    Show this help message
  -p, --prettify                Prettify the output (default)
  -P, --no-prettify             Do not prettify the output
  -c, --tsconfig <file>         Use the specified tsconfig.json file
```

Given a file named `example.ts` with the following contents:

```typescript
interface SomeInterface {
  a: number;
  b?: string;
  c: number | undefined;
}

type SomeType = {
  d: number;
  e: SomeInterface;
  f: () => void;
};
```

Running the following command expands the type expression `SomeType["e"]`:

```sh
expand-my-type example.ts 'SomeType["e"]'
# Output:
# { a: number; b?: string; c: number }
```

## API

This package exports a function named `expandMyType` that can be used in one of
the following ways:

1. Expand the type expression in a source file:

Given a file named `example.ts` with the following contents:

```typescript
   interface SomeInterface {
     a: number;
     b?: string;
     c: number | undefined;
   }

type SomeType = {
     d: number;
     e: SomeInterface;
     f: () => void;
   };
   ```

Running the following code expands the type expression `SomeType`:

```typescript
   import { expandMyType } from "expand-my-type";

const expandedType = await expandMyType({
     typeExpression: "SomeType",
     sourceFileName: "./example.ts",
   });

console.log(expandedType);
   /* {
     d: number
     e: { a: number; b?: string; c: number }
     f: () => void
   } */
   ```

2. Expand the type expression in a source text:

```typescript
   import { expandMyType } from "expand-my-type";

console.log(expandedType);
   /* { a: string; b: number } */
   ```

Advanced users can pass Biome configuration directly:

```typescript
import { expandMyType } from "expand-my-type";

const expandedType = await expandMyType({
  typeExpression: "SomeType",
  sourceFileName: "./example.ts",
  prettify: {
    biomeOptions: {
      formatter: {
        indentStyle: "space",
        lineWidth: 120,
      },
      javascript: {
        formatter: {
          semicolons: "always",
        },
      },
    },
  },
});
```

For local development in this repository, use Bun:

```sh
bun install
bun run check
bun run build
bun run deps:update
```

## How It Works

Expand My Type uses the following utility types to expand the type expression:

```typescript
// Expands a type expression
type Expand<T> = T extends (...args: infer A) => infer R
  ? (...args: Expand<A>) => Expand<R>
  : T extends Promise<infer U>
    ? Promise<ExpandTypeArgument<U>>
    : {
        [K in keyof T]: T[K] extends string ? ExpandString<T[K]> : Expand<T[K]>;
      } & {};

type ExpandTypeArgument<T> = [T & {}] extends [never]
  ? T
  : T & {} extends void
    ? T
    : Expand<T & {}>;

// Forces a union of string literal types to be expanded
type ExpandString<T extends string> = RemoveUnderscore<AppendUnderscore<T>>;
type AppendUnderscore<T extends string> = `${T}_` extends string
  ? `${T}_`
  : never;
type RemoveUnderscore<T extends string> = T extends `${infer U}_` ? U : never;
```

This approach comes with some limitations. Most notably, expanding a type that
leads to an infinite recursion might throw an error (when prettify option is
enabled), return a truncated output, or return any.

[ts-compiler-api]: https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API

node-expand-my-type

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README