JSON to TypeScript Interface Converter

A powerful tool that automatically generates TypeScript interfaces from JSON objects, making type-safe development easier and more efficient.

Features ✨

🔧 Convert JSON to TypeScript interfaces with ease
📦 Generate separate interfaces for nested objects
🔢 Intelligent type inference for Numbers, Strings, Booleans, and null values
📋 Create type definitions for arrays, objects and primitive types
🔄 Transform nested/complex JSON into flattened interface via --flat flag
✏️ Specify custom names for root interfaces
🗂️ Preserve original JSON structure in generated interfaces
🌐 Export options for generated interfaces (all, root, none)
📊 Handle complex nested structures with arrays of objects
🚀 Fast and lightweight CLI for quick conversions
📝 Support for both file and direct text input
🔌 Read JSON output directly from the stdin for pipeline operations
✏️ Added property name suggestion and correction logic based on strict TypeScript identifier rules
🔄 Automatically detects and resolves circular references in JSON structures to prevent infinite recursion
🛡️ Generate strict TypeScript types with exact property matching when enabled via --strict flag
🔒 Read-only Properties: Generate immutable interfaces with readonly modifier
❓ Optional Properties: Generate interfaces with all properties marked optional (?)
🐪 Property Case Transformation: Convert property names to various case formats:
- c - camelCase (userName)
- l - lower_snake_case (user_name)
- o - preserve original (default)
- p - PascalCase (UserName)
- u - UPPER_SNAKE_CASE (USER_NAME)
- k - kebab-case (user-name)
📐 Smart Array Type Detection: Automatically infers array types including:
- Primitive arrays (e.g., string[], number[])
- Mixed-type tuples (e.g., [string, number, boolean])
- Object arrays (e.g., User[])
- Nested arrays with proper type preservation
🗺️ Custom Type Mapping: Override default type detection with custom mappings:
- Map specific JSON properties to custom TypeScript types
- Useful for integrating with existing type definitions
- Example: Map "user_id" to UserID type
- Configure via typeMap option in API or CLI

Command Line Interface 💻

The package includes a command-line interface (CLI) for quick conversions without writing code.

Installation 📦

npm install -g @junaidatari/json2ts # NPM pnpm install -g @junaidatari/json2ts # PNPM yarn global add @junaidatari/json2ts # Yarn

Command Options ⚙️

Option	Type	Description	Default
`-f, --file`	`string`	Path to JSON file to convert	Required*
`-t, --text`	`string`	Raw JSON string to convert	Required*
`-o, --output`	`string`	Output file path	Prints to console
`-n, --name`	`string`	Root interface name	`RootObject`
`-l, --flat`	`boolean`	Generate flattened interface	-
`-e, --export`	`string`	Export type: `a`=all, `r`=root, `n`=none	`r` (root)
`--pc, --property-case`	`string`	Property case transformation: `c`=camelCase, `l`=lower_snake, `o`=original, `p`=PascalCase, `u`=UPPER_SNAKE, `k`=kebab-case	`o` (original)
`-s, --strict`	`boolean`	Generate strict TypeScript types with exact property matching	-
`-r, --readonly`	`boolean`	Make all generated properties readonly	-
`--op, --optional`	`boolean`	Make all generated properties optional	-

Either --file or --text must be provided or pipe through to read directly from the stdin.

Examples 📝

Basic file conversion

json2ts -f input.json -o types.ts -n ApiResponse

Direct text conversion

# Linux/Mac json2ts -t '{"user": {"name": "John"}}' -n User # Windows json2ts -t "{\"user\": {\"name\": \"John\"}}" -n User

Readonly properties

# Generate with readonly properties json2ts -f input.json -o readonly-types.ts -n Data --readonly # Combine with strict mode json2ts -f input.json -o strict-readonly.ts -n Data --strict --readonly

Optional properties

# Generate with optional properties json2ts -f input.json -o optional-types.ts -n Data --op # Combine with readonly mode json2ts -f input.json -o readonly-optional.ts -n Data --readonly --optional

Generate flattened interface

json2ts -f complex.json -o flat-types.ts -n Data --flat

Export all interfaces

json2ts -f input.json -o types.ts -n Response -e a

No exports (internal interfaces)

json2ts -f input.json -o types.ts -n Response --export n

Property case transformation

# Convert to camelCase properties json2ts -f input.json -o camel-types.ts --pc c # Convert to PascalCase properties json2ts -f input.json -o pascal-types.ts --property-case p # Convert to kebab-case properties json2ts -f input.json -o kebab-types.ts --property-case k

Strict mode generation

# Generate with strict type checking json2ts -f input.json -o strict-types.ts -n Data --strict

Combined options

# Multiple options together json2ts -f input.json -o output.ts -n ApiResponse -e a --property-case c --strict # Flattened with property transformation json2ts -f data.json -o flat.ts -n FlatData --flat --property-case l

Root-only export

# Export only root interface (default) json2ts -f input.json -o types.ts -n Response # or explicitly json2ts -f input.json -o types.ts -n Response -e r

Pipeline with curl

curl -s https://jsonplaceholder.typicode.com/posts/1 | \ json2ts -n UserResponse -o user-types.ts

Pipeline with other commands

# Convert from clipboard (Linux) xclip -selection clipboard -o | json2ts -n ClipboardData # Convert from file and copy to clipboard json2ts -f data.json | tee types.ts | pbcopy # Format with prettier curl -s https://api.example.com/data | json2ts -n Data | \ npx prettier --parser typescript

Configuration files

# Convert package.json cat package.json | json2ts -n PackageConfig -o package-types.ts # Convert tsconfig.json json2ts -f tsconfig.json -n TsConfig -o tsconfig-types.ts

Database exports

# MongoDB export mongoexport --collection users --out users.json json2ts -f users.json -n UserDoc -o user-types.ts --export a # PostgreSQL query psql -c "SELECT row_to_json(t) FROM (SELECT * FROM users) t" | \ json2ts -n DBUser -o db-types.ts

Interactive usage

echo '{"name": "test", "data": {"items": [1, 2, 3]}}' | \ json2ts -n TestData json2ts -n Config -o config-types.ts << EOF {  "server": {"port": 3000},  "database": {"url": "mongodb://localhost"} } EOF

Development workflows

# Generate types from API schema curl -s "$API_SCHEMA_URL" | json2ts -n Schema -o src/types/api.ts # Watch for changes while inotifywait -e modify data/; do for file in data/*.json; do base=$(basename "$file" .json) json2ts -f "$file" -o "types/${base}.ts" -n "${base^}Type" done done # Process all JSON files find src/data -name "*.json" -exec sh -c \ 'json2ts -f "$0" -o "src/types/$(basename "$0" .json).ts"' {} \;

Multiple files script

for file in data/*.json; do base=$(basename "$file" .json) json2ts -f "$file" -o "types/${base}.ts" -n "${base^}Data" done

Real-world API integration

# GitHub API: Get repository information curl -s https://api.github.com/repos/torvalds/linux | \ json2ts -n GithubRepo -o repo-types.ts --property-case c # Reddit API: Fetch subreddit posts curl -s -H "User-Agent: json2ts" \ "https://www.reddit.com/r/typescript/top.json?limit=10" | \ json2ts -n RedditPost -o reddit-types.ts --export a # GraphQL API query with curl curl -s -X POST https://api.spacex.land/graphql \ -H "Content-Type: application/json" \ -d '{"query": "{ launches { id name rocket { name } } }"}' | \ jq -r '.data.launches[0]' | \ json2ts -n SpaceXLaunch -o spacex-types.ts --property-case p

Database schema introspection

# PostgreSQL schema extraction psql -d myapp -c "  SELECT json_agg(t) FROM (  SELECT   table_name,  array_agg(column_name::text) as columns,  array_agg(data_type::text) as types  FROM information_schema.columns   WHERE table_schema = 'public'  GROUP BY table_name  ) t " | json2ts -n DBSchema -o db-schema.ts --readonly # MongoDB collection structure analysis mongo myapp --eval "  db.users.findOne().forEach(printjson) " | json2ts -n MongoUser -o mongo-types.ts --strict # Prisma schema introspection npx prisma introspect --print | \ grep -o '"model"[^}]*}' | \ json2ts -n PrismaModel -o prisma-types.ts --export a

Configuration management

# Kubernetes deployment analysis kubectl get deployment myapp -o json | \ json2ts -n K8sDeployment -o k8s-types.ts --readonly # Docker compose configuration docker compose config --format json | \ json2ts -n DockerCompose -o compose-types.ts --property-case l # Terraform state parsing terraform show -json | \ jq '.values.root_module.resources[] | select(.type == "aws_instance")' | \ json2ts -n TFInstance -o terraform-types.ts --strict

Testing and validation

# Generate test types from JSON schema jsonschema2jsonpointer schema.json | \ jq -r '.[] | .pointer' | \ xargs -I {} json2ts -f schema.json -n TestSchema --strict # Validate API responses against types for endpoint in users posts comments; do curl -s "https://api.example.com/$endpoint" | \ json2ts -n "${endpoint^}Response" -o "test/types/${endpoint}.ts" done # Generate mock data types jq -n '{  users: [range(10) | {  id: .,  name: "User\(.)",  email: "user\(.)@example.com",  roles: ["user", (\. % 3 == 0 and "admin" or empty)]  }] }' | json2ts -n MockUsers -o mock-types.ts --export a

Advanced pipeline operations

# Multi-stage transformation curl -s https://api.exchangerate-api.com/v4/latest/USD | \ jq '{rates: .rates | to_entries | map({key: .key, value: .value})}' | \ json2ts -n ExchangeRate -o rates.ts --property-case c | \ npx prettier --parser typescript > src/types/rates.ts # Parallel processing echo 'users posts comments products' | \ tr ' ' '\n' | \ xargs -P 4 -I {} bash -c "  curl -s \"https://api.example.com/{}\" | \  json2ts -n \"\$(echo {} | sed 's/.*/\u&/')\" -o \"types/{}.ts\"  " # Conditional type generation json2ts -f data.json -o temp.ts -n Data && \ if grep -q 'interface.*{' temp.ts; then echo "Generated interface:" cat temp.ts else echo "No interfaces generated" fi rm temp.ts

Enterprise workflows

# Service mesh configuration istioctl proxy-config routes deployment/reviews.default -o json | \ jq '.httpRoutes[0].route[0].match' | \ json2ts -n IstioRoute -o istio-types.ts --readonly # OpenAPI schema conversion curl -s https://petstore.swagger.io/v2/swagger.json | \ jq '.definitions' | \ json2ts -n PetStore -o api-types.ts --export a # Microservice contract generation for service in auth payment notification; do curl -s "https://contract-registry.internal/api/v1/contracts/$service" | \ jq '.schema' | \ json2ts -n "${service^}Contract" -o "src/contracts/${service}.ts" --strict done # CloudFormation template parsing aws cloudformation get-template --stack-name my-stack | \ jq -r '.TemplateBody' | \ json2ts -n CFTemplate -o cf-types.ts --property-case k

CI/CD integration

# GitHub Actions workflow validation find .github/workflows -name '*.yml' -exec \ yq eval -o json {} \; | \ json2ts -n GitHubAction -o action-types.ts # Azure DevOps pipeline analysis az pipelines show --id $(az pipelines list --query [0].id -o tsv) | \ jq '.process' | \ json2ts -n AzPipeline -o pipeline-types.ts # Dockerfile instruction parsing docker inspect $(docker build -q .) | \ jq -r '.[0].Config.Labels' | \ json2ts -n DockerLabels -o labels.ts --readonly

Tips 💡

Check version: json2ts --version
View help: json2ts --help

Programmatic API 📚

Installation

npm install @junaidatari/json2ts # NPM pnpm install @junaidatari/json2ts # PNPM yarn add @junaidatari/json2ts # Yarn

Usage 🚀

import { JsonToTsConverter, JsonToFlattenedTsConverter, } from '@junaidatari/json2ts'; // Sample JSON object const json = { user: { name: 'John', age: 30, address: { street: '123 Main St', city: 'New York' } } }; // Sample JSON string const jsonText = `{  "_id": "691da8feb00505c1c11b08b9",  "index": 0,  "guid": "9150daa4-b7c4-4230-a3b8-ddd2eb05731f",  "isActive": true,  "balance": "$3,816.81",  "picture": "http://placehold.it/32x32",  "age": 39,  "eyeColor": "blue",  "name": "Vickie Snow",  "gender": "female",  "company": "DATACATOR",  "email": "vickiesnow@datacator.com",  "phone": "+1 (925) 537-2747",  "address": "843 Interborough Parkway, Floris, Washington, 5608",  "registered": "2018-11-01T06:02:48 -05:00",  "latitude": -42.568798,  "longitude": -77.971543,  "tags": [  "fugiat",  "reprehenderit",  "culpa",  "veniam",  "enim",  "occaecat",  "et"  ],  "friends": [  {  "id": 0,  "name": "Silvia Ferrell"  },  {  "id": 1,  "name": "Kirkland Benson"  },  {  "id": 2,  "name": "Howe Hester"  }  ],  "greeting": "Hello, Vickie Snow! You have 10 unread messages.",  "favoriteFruit": "strawberry" } `; // Convert to multiple interfaces with all exports const interfaces = JsonToTsConverter.convert(json, 'Person', 'all'); console.log('Generated interfaces:'); console.log(interfaces); /* Output: export interface Person {  user: User; }  export interface User {  name: string;  age: number;  address: Address; }  export interface Address {  street: string;  city: string; } */ // Convert to flattened interface const interfaceFlat = JsonToFlattenedTsConverter.convert(jsonText, 'PersonFlat', 'all'); console.log('\nGenerated flattened interface:'); console.log(interfaceFlat); /* Output: export interface PersonFlat {  _id: string;  index: number;  guid: string;  isActive: boolean;  balance: string;  picture: string;  age: number;  eyeColor: string;  name: string;  gender: string;  company: string;  email: string;  phone: string;  address: string;  registered: string;  latitude: number;  longitude: number;  tags: string[];  friends: {  id: number;  name: string;  }[];  greeting: string;  favoriteFruit: string; } */ // Example with complex nested structure const complexJson = { data: { users: [ { id: 1, profile: { name: 'Alice', preferences: { theme: 'dark', notifications: { email: true, push: false } } } } ], metadata: { total: 1, page: 1 } } }; const complexTypes = JsonToTsConverter.convert(complexJson, 'ApiResponse', 'root'); console.log(complexTypes); /* Output: export interface ApiResponse {  data: Data; }  interface Data {  users: User[];  metadata: Metadata; }  interface User {  id: number;  profile: Profile; }  interface Profile {  name: string;  preferences: Preferences; }  interface Preferences {  theme: string;  notifications: Notifications; }  interface Notifications {  email: boolean;  push: boolean; }  interface Metadata {  total: number;  page: number; } */ // Real-world example: API response handler async function handleApiResponse() { // Simulate API response const apiResponse = await fetch('https://jsonplaceholder.typicode.com/posts/1'); const data = await apiResponse.json(); // Generate types dynamically const types = JsonToTsConverter.convert(data, 'PostResponse', 'root'); console.log(types); /*  export interface PostResponse {  userId: number;  id: number;  title: string;  body: string;  }  */ }

API Reference 📖

Methods

`JsonToTsConverter.convert(json, name?, export?, options?)`

`JsonToFlattenedTsConverter.convert(json, name?, export?, options?)`

Converts JSON to TypeScript interfaces.

Parameters:

json: JSON object or string to convert
name: Root interface name (default: 'RootObject')
export: Export mode ('all', 'root', 'none') (default: 'root')
options: Configuration options for conversion (optional)
- arrayMaxTupleSize: Maximum number of items to convert to tuple type (default: 10)
- arrayMinTupleSize: Minimum number of items required to create a tuple type (default: 2)
- strict: Enable strict type checking for better type inference (default: false)
- typeMap: Custom type mapping for specific JSON structures (default: {})
- propertyCase: Naming convention for generated property names (default: 'original')
- readonlyProperties: Make all generated properties readonly (default: false)
- optionalProperties: Make all generated properties optional (default: false)

Returns: Generated TypeScript interfaces string

Contributing 🤝

We welcome contributions! Please follow these steps:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup 🔧

git clone https://github.com/blacksmoke26/json2ts.git cd json2ts npm install npm run dev npm run dev:flat

Testing CLI with `/samples/*.json` JSON files

npm run build node .\bin\json2ts -f .\samples\jsons\sample.json -n Sample1 node .\bin\json2ts -f .\samples\jsons\sample2.json -n Sample2 -o sample2.ts --flat

Running test cases

npm run test

License 📄

This project is licensed under the ISC License.

Support 💬

If you encounter issues or have questions:

Search existing GitHub Issues
Create a new issue

Acknowledgments 🙏

Originally developed for Posquelize
Thanks to all contributors
Inspired by the need for type safety in JSON-heavy applications

Copyright ©️

Developed with ❤️ by Junaid Atari

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
bin		bin
samples		samples
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
README.md		README.md
index.js		index.js
package.json		package.json
tsconfig.json		tsconfig.json

blacksmoke26/json2ts

Folders and files

Latest commit

History

Repository files navigation