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
📋 Create type definitions for arrays and primitive types
✏️ Specify custom names for root interfaces
🔄 Transform nested/complex JSON into flattened interface
❓ Support for optional properties and nullable types
🗂️ 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
🔢 Intelligent type inference for numbers, strings, booleans, and null values
🔌 Read JSON directly from stdin for pipeline operations

CLI Usage 💻

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

Installation 📦

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

Command Options ⚙️

Option	Type	Description	Default
`-f, --file`	`string`	Path to the JSON file to be converted to TypeScript interfaces	Required (unless `--text` is used)
`-t, --text`	`string`	Raw JSON string to be converted to TypeScript interfaces	Required (unless `--file` is used)
`-o, --output`	`string`	Path where the generated TypeScript interface file will be saved	Prints to console if not specified
`-n, --name`	`string`	Name for the root TypeScript interface	`RootObject`
`-l, --flat`	`boolean`	Generate a single flattened interface instead of nested interfaces	`false`
`-e, --export`	`string`	Export type: `a`=all, `r`=root, or `n`=none	`r` (root only)

Examples 📝

Basic file conversion

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

Direct text conversion and print to console

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

# Windows
json2ts -t "{\"user\": {\"name\": \"John Doe\"}}" -n User

Generate flattened interface

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

Export all interfaces

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

No exports (all interfaces internal)

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

Pipeline with curl (fetch JSON from API)

# Convert API response directly to TypeScript types
curl -s https://jsonplaceholder.typicode.com/posts/1 | json2ts -n UserResponse -o user-types.ts

Pipeline with other commands

# Convert from clipboard (using xclip on Linux)
xclip -selection clipboard -o | json2ts -n ClipboardData

# Convert from file and pipe to another command
json2ts -f data.json | tee types.ts | pbcopy

# Chain multiple conversions
curl -s https://api.example.com/data | json2ts -n ApiResponse | npx prettier --parser typescript

Using with package managers

# Convert package.json to TypeScript interface
cat package.json | json2ts -n PackageConfig -o package-types.ts

# Convert npm shrinkwrap file
json2ts -f npm-shrinkwrap.json -n ShrinkwrapData -o shrinkwrap-types.ts --flat

Processing configuration files

# Convert TypeScript config
json2ts -f tsconfig.json -n TsConfig -o tsconfig-types.ts

# Convert ESLint config
cat .eslintrc.json | json2ts -n EsLintConfig -o eslint-types.ts

Working with databases

# Convert MongoDB export to TypeScript
mongoexport --collection users --out users.json
json2ts -f users.json -n UserDocument -o user-types.ts --export all

# Convert from database query result
psql -c "SELECT row_to_json(t) FROM (SELECT * FROM users LIMIT 1) t" | json2ts -n DBUser -o db-types.ts

Interactive usage

# Interactive JSON input with multiple lines
echo '{
  "name": "test",
  "data": {
    "items": [1, 2, 3]
  }
}' | json2ts -n TestData

# Using heredoc for complex JSON
json2ts -n ComplexConfig -o config-types.ts << EOF
{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "database": {
    "url": "mongodb://localhost:27017",
    "options": {
      "useNewUrlParser": true
    }
  }
}
EOF

Development workflows

# Generate types from API schema in CI/CD
curl -s "$API_SCHEMA_URL" | json2ts -n ApiSchema -o src/types/api.ts

# Watch for changes and regenerate types
while inotifywait -e modify data/; do
  for file in data/*.json; do
    basename=$(basename "$file" .json)
    json2ts -f "$file" -o "types/${basename}.ts" -n "${basename^}Type"
  done
done

# Generate types for all JSON files in a directory
find src/data -name "*.json" -exec sh -c 'json2ts -f "$0" -o "src/types/$(basename "$0" .json).ts" -n "$(basename "$0" .json | sed "s/\b\w/\U/g/g")"' {} \;

Processing multiple files with a script

# Create a script to process multiple JSON files
for file in data/*.json; do
  basename=$(basename "$file" .json)
  json2ts -f "$file" -o "types/${basename}.ts" -n "${basename^}Data"
done

Advanced Usage Tips 💡

Input from stdin: Use - as the file path to read from standard input
Version information: Use --version to check the current version
Detailed help: Use --help to see all available options with descriptions

Help ❓

For more information about available options, use:

json2ts --help

Programmatic API 📚

npm install @junaidatari/json2ts   # for NPM
pnpm install @junaidatari/json2ts  # for PNPM
yarn add @junaidatari/json2ts      # for 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 Address {
  street: string;
  city: string;
}

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

export interface Person {
  user: User;
}
*/

// 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;
  }
  */
}

// Working with arrays and unions
const unionExample = {
  items: [
    { type: 'text', value: 'Hello' },
    { type: 'number', value: 42 },
    { type: 'boolean', value: true }
  ]
};

const unionTypes = JsonToTsConverter.convert(unionExample, 'UnionContainer', 'all');
console.log(unionTypes);
/*
export interface TextItem {
  type: string;
  value: string;
}

export interface NumberItem {
  type: string;
  value: number;
}

export interface BooleanItem {
  type: string;
  value: boolean;
}

export interface UnionContainer {
  items: (TextItem | NumberItem | BooleanItem)[];
}
*/

API Reference 📖

`JsonToTsConverter.convert(json, rootInterfaceName, exportType)`

`JsonToFlattenedTsConverter.convert(json, rootInterfaceName, exportType)`

Converts a JSON object into TypeScript interfaces.

Parameters:

json: The JSON object or JSON string to convert
rootInterfaceName: Name for the root interface (optional, default: 'RootObject')
exportType: Export mode ('all', 'root', or 'none') (optional, default: 'all')

Returns: A string containing the generated TypeScript interfaces

Notes:

The json parameter can be either a parsed JSON object or a JSON string
Export modes:
- 'all': All interfaces are exported
- 'root': Only the root interface is exported, others are internal
- 'none': No interfaces are exported (all are internal)

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

License 📄

This project is licensed under the ISC License.

Support 💬

If you encounter any issues or have questions, please:

Search existing GitHub Issues
Create a new issue with detailed information

Acknowledgments 🙏

This project was originally developed as part of Posquelize.
Special thanks to all contributors who helped improve this tool.
Inspired by the need for better type safety in JSON-heavy applications.

Copyright ©️

Developed with ❤️ by Junaid Atari

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
bin		bin
samples		samples
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.jshintrc		.jshintrc
.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