npm package: @geekles007/spring-to-ts
Description: Generate TypeScript types from Spring Boot/Kotlin entities
Author: geekles007
Latest version: 1.0.1

# Spring to TypeScript Generator

[![npm version](https://badge.fury.io/js/spring-to-ts.svg)](https://www.npmjs.com/package/spring-to-ts)
[![CI](https://github.com/geekles007/spring-to-ts/workflows/CI/badge.svg)](https://github.com/geekles007/spring-to-ts/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/spring-to-ts.svg)](https://nodejs.org)

Generate TypeScript types automatically from your Spring Boot/Kotlin entities to ensure synchronization between backend and frontend.

## Features

- ✨ Parse Kotlin/Java classes annotated with JPA
- 🔄 Generate TypeScript interfaces with proper types
- 🔗 Support entity relations (@OneToMany, @ManyToOne, etc.)
- 📦 Handle enums, nullable types, and Optional
- ✅ Include validation annotations
- 👀 Watch mode for automatic regeneration
- ⚙️ Highly configurable via JSON/YAML

## Installation

```bash
npm install -g @geekles007/spring-to-ts
```

Or use with npx:

```bash
npx @geekles007/spring-to-ts generate --source ./src/main/kotlin --output ./frontend/types
```

## Quick Start

1. Initialize a configuration file:

```bash
spring-to-ts init
```

2. Edit the generated `spring-to-ts.config.json`:

```json
{
  "sourceDir": "./backend/src/main/kotlin/entities",
  "outputDir": "./frontend/src/types",
  "includeValidation": true,
  "dateFormat": "ISO"
}
```

3. Generate TypeScript types:

```bash
spring-to-ts generate
```

## CLI Usage

### Generate Types

```bash
spring-to-ts generate [options]
```

Options:
- `-s, --source <path>`: Source directory containing Kotlin/Java entities
- `-o, --output <path>`: Output directory for TypeScript types
- `-c, --config <path>`: Path to configuration file
- `-w, --watch`: Watch mode - regenerate on file changes
- `--no-validation`: Exclude validation annotations
- `--no-relations`: Exclude entity relations
- `--date-format <format>`: Date format (ISO, Date, or number)

### Initialize Configuration

```bash
spring-to-ts init [options]
```

Options:
- `-f, --format <format>`: Configuration format (json or yaml)

## Configuration

### Configuration File

Create a `spring-to-ts.config.json` or `spring-to-ts.config.yaml`:

```json
{
  "sourceDir": "./backend/src/main/kotlin/entities",
  "outputDir": "./frontend/src/types",
  "includeValidation": true,
  "dateFormat": "ISO",
  "includeEnums": true,
  "includeRelations": true,
  "excludePatterns": ["**/*Test.kt", "**/*Spec.kt"],
  "watch": false,
  "customTypeMapping": {
    "UUID": "string",
    "BigDecimal": "number",
    "LocalDateTime": "string",
    "LocalDate": "string"
  }
}
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sourceDir` | string | - | **Required.** Source directory with entities |
| `outputDir` | string | - | **Required.** Output directory for types |
| `includeValidation` | boolean | true | Include validation annotations as comments |
| `dateFormat` | string | "ISO" | Date format: "ISO", "Date", or "number" |
| `includeEnums` | boolean | true | Generate enums |
| `includeRelations` | boolean | true | Include entity relations |
| `excludePatterns` | string[] | [] | Glob patterns to exclude files |
| `watch` | boolean | false | Enable watch mode |
| `customTypeMapping` | object | {} | Custom type mappings |

## Examples

### Example Kotlin Entity

```kotlin
package com.example.entities

import jakarta.persistence.*
import java.time.LocalDateTime
import java.util.UUID

@Entity
@Table(name = "users")
data class User(
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    val id: UUID? = null,

    @Column(nullable = false)
    val username: String,

    @Column(nullable = false)
    val email: String,

    val createdAt: LocalDateTime = LocalDateTime.now(),

    @OneToMany(mappedBy = "user")
    val posts: List<Post> = emptyList()
)

enum class UserRole {
    ADMIN,
    USER,
    GUEST
}
```

### Generated TypeScript

```typescript
// User.ts
import { Post } from './Post';

export interface User {
  id?: string;
  username: string;
  email: string;
  createdAt: string;
  posts: Post[];
}

// UserRole.ts
export enum UserRole {
  ADMIN = 'ADMIN',
  USER = 'USER',
  GUEST = 'GUEST',
}
```

## Type Mappings

Default Kotlin/Java to TypeScript mappings:

| Kotlin/Java | TypeScript |
|-------------|------------|
| String | string |
| Int, Long, Double, Float | number |
| Boolean | boolean |
| UUID | string |
| LocalDate, LocalDateTime | string (configurable) |
| List<T>, Set<T> | T[] |
| Map<K, V> | Record<K, V> |
| Optional<T>, T? | T \| undefined |

## Watch Mode

Enable automatic regeneration when files change:

```bash
spring-to-ts generate --watch
```

Or in configuration:

```json
{
  "watch": true
}
```

## Supported Annotations

- `@Entity`, `@Table`, `@Document` - Entity detection
- `@OneToMany`, `@ManyToOne`, `@OneToOne`, `@ManyToMany` - Relations
- `@Column(nullable = false)` - Nullable detection
- Validation annotations (included as comments when `includeValidation: true`)

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format
```

## 📚 Documentation

- [Publishing Guide](PUBLISHING.md) - How to publish to npm
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Changelog](CHANGELOG.md) - Version history

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:

- How to set up your development environment
- Coding standards and guidelines
- How to submit pull requests
- Reporting bugs and requesting features

## 📝 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Commander.js](https://github.com/tj/commander.js/)
- Styled with [Chalk](https://github.com/chalk/chalk)
- Powered by [TypeScript](https://www.typescriptlang.org/)

## 📞 Support

- 🐛 [Report a bug](https://github.com/geekles007/spring-to-ts/issues/new?template=bug_report.md)
- ✨ [Request a feature](https://github.com/geekles007/spring-to-ts/issues/new?template=feature_request.md)
- 💬 [Discussions](https://github.com/geekles007/spring-to-ts/discussions)

---

Made with ❤️ by Geekles007 (https://github.com/geekles007)