JSON to TypeScript Interface Converter

Common errors

• Cannot find module 'json-to-ts'

  cause The package is not installed or the import path is incorrect.
  fix Run `npm install json-to-ts` or `yarn add json-to-ts`. Verify the import statement uses the correct package name: `from 'json-to-ts'`.

• TypeError: JsonToTS is not a function

  cause The main conversion function was imported incorrectly, often by attempting a named import from a module that uses a default or CommonJS module.exports export.
  fix For CommonJS, use `const JsonToTS = require('json-to-ts');`. For ESM, use `import JsonToTS from 'json-to-ts';` to correctly capture the default export.

• Property 'x' is missing in type 'Y' but required in type 'Z' (or similar type mismatch during compilation/runtime)

  cause The TypeScript interfaces generated by `json-to-ts` do not perfectly align with the actual runtime JSON data, possibly due to optional fields not being inferred correctly or unexpected variations in data structure.
  fix Manually review and adjust the generated TypeScript interfaces to precisely reflect the expected JSON structure. Add `?` for optional properties or use union types (e.g., `string | number | null | undefined`) where data can vary. Ensure sample JSON provided for generation is representative of all possible data shapes.

Warnings

• gotcha Generating types for very large or deeply nested JSON structures can strain TypeScript's type inference engine, potentially leading to slow compilation times or 'Type instantiation is excessively deep and potentially infinite' errors, particularly with older TypeScript versions or specific compiler flags.
  Fix: For extremely complex or large JSONs, consider simplifying the input or manually refining the generated types. Ensure your `tsconfig.json` has appropriate `maxNodeModuleJsDepth` or similar settings if encountering deep recursion errors.
• gotcha While `json-to-ts` excels at inference, highly ambiguous JSON structures (e.g., arrays with mixed types, objects with inconsistent property presence across array elements, or null values without explicit alternatives) might result in broader union types or `any` where more specific types were desired. This sometimes requires manual refinement of the generated interfaces.
  Fix: Review the generated types for `any` or overly broad union types. Manually specify more precise types if the inference is not exact enough for your use case, particularly for optional fields (e.g., `field?: Type`) or explicit nullability (e.g., `field: Type | null`).
• gotcha The library primarily uses a CommonJS default export (`module.exports = function`). When used in a pure ESM project, especially with strict `esModuleInterop: false` or certain bundler configurations, directly importing `JsonToTS` might behave unexpectedly if not using `import JsonToTS from 'json-to-ts'` (default import syntax).
  Fix: Ensure `esModuleInterop: true` in your `tsconfig.json` for better compatibility. Always use the default import syntax (`import JsonToTS from 'json-to-ts';`) for ESM, and `const JsonToTS = require('json-to-ts');` for CommonJS.

Install

• npm install json-to-ts npm
• yarn add json-to-ts yarn
• pnpm add json-to-ts pnpm

Imports

• JsonToTS
  wrong:

  import { JsonToTS } from 'json-to-ts';

  correct:

  import JsonToTS from 'json-to-ts';

  The primary conversion function is exported as the default export in ESM. Attempting a named import will likely result in an undefined function.
• JsonToTS (CommonJS)

  const JsonToTS = require('json-to-ts');

  For CommonJS environments, the entire module export is the JsonToTS function.
• Type definitions

  import type { RootObject, Cat } from 'json-to-ts/dist/types';

  While `json-to-ts` generates types, if you need to import its internal types (e.g., for extending its behavior), they are typically found in the `dist/types` directory. However, generally, you'd use the generated types directly.

Quickstart

This example demonstrates how to import and use `json-to-ts` to convert a complex JSON object into a set of TypeScript interfaces, including nested objects and optional properties.

import JsonToTS from 'json-to-ts';

const json = {
  users: [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com', phone: '123-456-7890' }
  ],
  settings: {
    theme: 'dark',
    notificationsEnabled: true
  },
  version: 2.1,
  timestamp: new Date().toISOString()
};

console.log('Generating TypeScript interfaces...');
JsonToTS(json, {
  rootName: 'AppData',
  // Optional: customize type names, e.g., for arrays of specific objects
  // arrayTypeSuffix: 'Item'
}).forEach(typeInterface => {
  console.log(typeInterface);
});
/* Expected Output:
interface AppData {
  users: User[];
  settings: Settings;
  version: number;
  timestamp: string;
}
interface User {
  id: number;
  name: string;
  email: string;
  phone?: string;
}
interface Settings {
  theme: string;
  notificationsEnabled: boolean;
}
*/