npm package: @kattebak/typespec-openapi-types-emitter
Description: TypeSpec emitter that generates TypeScript types from OpenAPI specs similar to openapicmd typegen
Latest version: 1.0.0

# @kattebak/typespec-openapi-types-emitter

A TypeSpec emitter that generates TypeScript type definitions from your API specifications. Define your API once in TypeSpec and get fully typed client interfaces with complete code completion support.

## Features

- Generates TypeScript types directly from TypeSpec API definitions
- Outputs `Components.Schemas` namespace with all models, enums, and scalars
- Generates `Paths` namespace with operation-specific types (parameters, request bodies, responses)
- Creates `OperationMethods` interface for typed API method calls
- Produces `PathsDictionary` for path-based method access
- Exports convenient top-level type aliases

## Installation

```bash
npm install @kattebak/typespec-openapi-types-emitter
```

## Usage

### 1. Add the emitter to your TypeSpec project

Create or update your `tspconfig.yaml`:

```yaml
emit:
  - "@kattebak/typespec-openapi-types-emitter"
options:
  "@kattebak/typespec-openapi-types-emitter":
    output-file: "types.d.ts"
    # Optional: generate a package.json for the types
    package-name: "@myorg/api-types"
    package-version: "1.0.0"
```

### 2. Compile your TypeSpec project

```bash
npx tsp compile .
```

This will generate a `types.d.ts` file in your output directory.

## Configuration Options

| Option               | Type   | Default          | Description                                                    |
| -------------------- | ------ | ---------------- | -------------------------------------------------------------- |
| `output-file`        | string | `"types.d.ts"`   | The output filename for the generated types                    |
| `emitter-output-dir` | string | `"{output-dir}"` | The directory where the types file will be written             |
| `package-name`       | string | -                | If provided, a `package.json` will be generated with this name |
| `package-version`    | string | `"0.0.1"`        | Version for the generated `package.json`                       |

## Generated Output Structure

The emitter produces TypeScript declarations with the following structure:

```typescript
declare namespace Components {
  namespace Schemas {
    // All models, enums, and scalar types
    export interface Book { ... }
    export type BookStatus = "available" | "out_of_stock";
    // ...
  }
}

declare namespace Paths {
  namespace GetBooks {
    export interface QueryParameters { ... }
    namespace Responses {
      export type $200 = Components.Schemas.Book[];
    }
  }
  // ... other operations
}

export interface OperationMethods {
  getBooks(
    parameters?: Paths.GetBooks.QueryParameters | null,
    data?: any,
    config?: RequestConfig
  ): Promise<Paths.GetBooks.Responses.$200>;
  // ... other operations
}

export interface PathsDictionary {
  ['/books']: {
    get(...): Promise<...>;
    post(...): Promise<...>;
  };
  // ... other paths
}

// Convenient top-level exports
export type Book = Components.Schemas.Book;
export type BookStatus = Components.Schemas.BookStatus;
// ...
```

## Using the Generated Types

```typescript
import type { Book, Author, OperationMethods } from "@myorg/api-types";

// Use the types with your API client
const books: Book[] = await client.getBooks({ limit: 10 });
const author: Author = await client.getAuthorById({ id: 1 });
```

## Example

See the [test/main.tsp](./test/main.tsp) file for a complete example of a Bookstore API definition.

## Development

```bash
# Install dependencies
npm install

# Build the emitter
npm run build

# Run tests
npm test

# Lint and format
npm run lint
npm run fix
```

## License

MIT