Type From JSON

A CLI tool that automatically generates TypeScript type definitions from runtime API responses or JSON files.

Features

• JSON file type inference: Read JSON files and generate TypeScript interfaces
• Multiple response union type detection: Detect union types when fields have different types across samples
• Generate .d.ts files: Output clean TypeScript declaration files
• Watch mode: Watch files and regenerate types on changes
• CLI interface: User-friendly command-line interface with commander.js

Installation

# Clone the repository
cd type-from-json

# Install dependencies
npm install

# Build the project
npm run build

# Install globally (optional)
npm install -g .

Usage

Generate types from JSON files

# Generate .d.ts for a single file
type-from-json infer data.json

# Generate .d.ts for all JSON files matching a pattern
type-from-json infer "src/**/*.json"

# Specify output directory
type-from-json infer "*.json" --output ./types

# Specify custom interface name
type-from-json infer data.json --name MyCustomType

# Verbose output (shows generated types)
type-from-json infer data.json --verbose

Watch mode

# Watch for file changes and regenerate types
type-from-json watch "src/**/*.json"

# Watch with output directory
type-from-json watch "src/**/*.json" --output ./types

# Watch with verbose output
type-from-json watch "data.json" --verbose

Direct CLI options

# Using direct options
type-from-json -i "*.json" -o ./types -n MyType

# Watch mode via CLI
type-from-json -i "*.json" --watch

Examples

Simple object

Input (data.json):

{
  "name": "John",
  "age": 30,
  "active": true
}

Output (data.d.ts):

export interface Data {
  name: string;
  age: number;
  active: boolean;
}

Nested objects

Input (user.json):

{
  "id": 1,
  "name": "Alice",
  "address": {
    "street": "123 Main St",
    "city": "Boston"
  }
}

Output (user.d.ts):

export interface User {
  id: number;
  name: string;
  address: Address;
}

export interface Address {
  street: string;
  city: string;
}

Arrays

Input (items.json):

[
  { "id": 1, "name": "Item 1" },
  { "id": 2, "name": "Item 2" }
]

Output (items.d.ts):

export type Items = {
  id: number;
  name: string;
}[];

Union types

When analyzing multiple samples with different types:

Input (response1.json):

{ "id": 1, "status": "active" }

Input (response2.json):

{ "id": "abc", "status": "inactive" }

Output:

export interface Response {
  id: number | string;
  status: "active" | "inactive";
}

Optional fields

Input (users.json):

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob" }
]

Output (users.d.ts):

export interface Users {
  id: number;
  name: string;
  email?: string;
}

API Reference

TypeInferrer

import { TypeInferrer } from 'type-from-json';

const inferrer = new TypeInferrer({ 
  rootName: 'MyType',      // Optional: custom root type name
  detectUnions: true,       // Optional: detect union types (default: true)
  literalThreshold: 3       // Optional: min occurrences for literal types
});

// Single JSON value
const result = inferrer.infer({ name: 'John', age: 30 });

// Multiple samples for union detection
const result = inferrer.inferFromMultiple([
  { id: 1 },
  { id: 'two' }
]);

DeclarationGenerator

import { DeclarationGenerator } from 'type-from-json';

const generator = new DeclarationGenerator(2); // 2-space indentation

// Generate from TypeDefinition array
const declaration = generator.generate(types);

// Generate standalone declaration
const standalone = generator.generateStandalone(types);

FileWatcher

import { FileWatcher } from 'type-from-json';

const watcher = new FileWatcher({
  patterns: ['**/*.json'],
  ignored: ['node_modules/**', 'dist/**'],
  debounceMs: 300
});

await watcher.initialize();

watcher.start((event, filePath) => {
  console.log(`${event}: ${filePath}`);
});

// Find files matching patterns
const files = await watcher.findFiles(['**/*.json']);

watcher.stop();

Configuration

Environment Variables

Variable	Description	Default
NODE_ENV	Environment mode	development

TypeScript Configuration

The project uses ES2022 target with strict mode. Configuration is in tsconfig.json.

Project Configuration (Optional)

Create a type-from-json.config.json in your project root:

{
  "outputDir": "./types",
  "rootName": "ApiResponse",
  "watchPatterns": ["src/**/*.json"],
  "ignoredPatterns": ["node_modules/**", "dist/**"]
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

License

MIT