tessl/npm-ts-json-schema-generator

Generate JSON schema from your TypeScript sources with extensive customization options

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

ts-json-schema-generator

Name: tessl/npm-ts-json-schema-generator
Author: tessl

ts-json-schema-generator is a powerful TypeScript library that generates JSON schemas from TypeScript type definitions. It serves as both a command-line tool and a programmatic library, offering extensive customization options for advanced TypeScript features including generics, conditional types, mapped types, and more.

Package Information

Package Name: ts-json-schema-generator
Package Type: npm
Language: TypeScript
Installation: npm install ts-json-schema-generator

Core Imports

import { createGenerator, Config, SchemaGenerator } from "ts-json-schema-generator";

For CommonJS:

const { createGenerator } = require("ts-json-schema-generator");

For advanced usage (custom parsers/formatters):

import {
  createGenerator,
  createParser,
  createFormatter,
  createProgram,
  SchemaGenerator,
  SubTypeFormatter,
  SubNodeParser,
  MutableParser,
  MutableTypeFormatter,
  BaseType,
  Context
} from "ts-json-schema-generator";

Basic Usage

import { createGenerator } from "ts-json-schema-generator";

// Simple usage
const config = {
  path: "path/to/source/file.ts",
  tsconfig: "path/to/tsconfig.json",
  type: "MyInterface", // or "*" for all types
};

const schema = createGenerator(config).createSchema(config.type);
console.log(JSON.stringify(schema, null, 2));

Architecture

ts-json-schema-generator uses a multi-stage architecture:

Program Creation: TypeScript compiler API creates program from source files
AST Parsing: Node parsers convert TypeScript AST nodes to internal type representations
Type Formatting: Type formatters convert internal types to JSON schema definitions
Schema Generation: SchemaGenerator orchestrates the process and produces final JSON schema

The library supports extensive customization through:

Custom Parsers: Handle new TypeScript syntax or special constructs
Custom Formatters: Control JSON schema output format
Configuration Options: Fine-tune parsing and generation behavior

Capabilities

Schema Generation

Core functionality for generating JSON schemas from TypeScript types with extensive configuration options.

function createGenerator(config: Config): SchemaGenerator;

interface Config {
  path?: string;
  type?: string;
  tsconfig?: string;
  expose?: "all" | "none" | "export";
  jsDoc?: "none" | "extended" | "basic";
  minify?: boolean;
  sortProps?: boolean;
  strictTuples?: boolean;
  skipTypeCheck?: boolean;
  encodeRefs?: boolean;
  topRef?: boolean;
  markdownDescription?: boolean;
  extraTags?: string[];
  additionalProperties?: boolean;
  functions?: FunctionOptions;
  schemaId?: string;
  discriminatorType?: "json-schema" | "open-api";
}

type FunctionOptions = "fail" | "comment" | "hide";

type CompletedConfig = Config & typeof DEFAULT_CONFIG;

Schema Generation

TypeScript Program Management

Create and manage TypeScript programs with custom compiler options and file resolution.

function createProgram(config: CompletedConfig): ts.Program;

Program Management

AST Node Parsing

Extensible parsing system that converts TypeScript AST nodes to internal type representations.

function createParser(
  program: ts.Program, 
  config: CompletedConfig, 
  augmentor?: ParserAugmentor
): NodeParser;

type ParserAugmentor = (parser: MutableParser) => void;

interface NodeParser {
  createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType;
}

interface MutableParser {
  addNodeParser(parser: SubNodeParser): MutableParser;
}

AST Parsing

Type Formatting

Convert internal type representations to JSON schema definitions with customizable formatters.

function createFormatter(
  config: CompletedConfig, 
  augmentor?: FormatterAugmentor
): TypeFormatter;

type FormatterAugmentor = (
  formatter: MutableTypeFormatter,
  circularReferenceTypeFormatter: CircularReferenceTypeFormatter
) => void;

interface TypeFormatter {
  getDefinition(type: BaseType): Definition;
  getChildren(type: BaseType): BaseType[];
}

interface MutableTypeFormatter {
  addTypeFormatter(formatter: SubTypeFormatter): MutableTypeFormatter;
}

Type Formatting

CLI Interface

Command-line interface with comprehensive options for batch processing and automation.

npx ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'

CLI Usage

Custom Extensions

Create custom parsers and formatters to handle special TypeScript constructs or generate custom JSON schema formats.

interface SubNodeParser extends NodeParser {
  supportsNode(node: ts.Node): boolean;
}

interface SubTypeFormatter extends TypeFormatter {
  supportsType(type: BaseType): boolean;
}

Custom Extensions

Types

Schema and Definition Types

import type { JSONSchema7 } from "json-schema";

type Schema = JSONSchema7;
type Definition = JSONSchema7;

Base Type System

abstract class BaseType {
  abstract getId(): string;
  getName(): string;
}

Context

class Context {
  constructor(reference?: ts.Node);
  pushArgument(argumentType: BaseType): void;
  pushParameter(parameterName: string): void;
  setDefault(parameterName: string, argumentType: BaseType): void;
  getCacheKey(): string;
  getArgument(parameterName: string): BaseType;
  getParameters(): readonly string[];
  getArguments(): readonly BaseType[];
  getReference(): ts.Node | undefined;
}

Error Types

class BaseError extends Error {
  format(): string;
}

class UnknownNodeError extends BaseError {}
class UnknownTypeError extends BaseError {}
class RootlessError extends BaseError {}
class MultipleDefinitionsError extends BaseError {}
class LogicError extends BaseError {}
class ExpectationFailedError extends BaseError {}
class JsonTypeError extends BaseError {}
class DefinitionError extends BaseError {}
class BuildError extends BaseError {}
class UnhandledError extends BaseError {}