ts-json-schema-generator 2.5.0-next.6 → 2.5.0-next.8

package/factory/generator.ts

@@ -7,7 +7,7 @@ import { createProgram } from "./program.js";
 
 export function createGenerator(config: Config): SchemaGenerator {
     const completedConfig = { ...DEFAULT_CONFIG, ...config };
-    const program = createProgram(completedConfig);
+    const program = config.tsProgram || createProgram(completedConfig);
     const parser = createParser(program, completedConfig);
     const formatter = createFormatter(completedConfig);
 

package/factory/parser.ts

@@ -62,6 +62,7 @@ import { SatisfiesNodeParser } from "../src/NodeParser/SatisfiesNodeParser.js";
 import { PromiseNodeParser } from "../src/NodeParser/PromiseNodeParser.js";
 import { SpreadElementNodeParser } from "../src/NodeParser/SpreadElementNodeParser.js";
 import { IdentifierNodeParser } from "../src/NodeParser/IdentifierNodeParser.js";
+import { castArray } from "../src/Utils/castArray.js";
 
 export type ParserAugmentor = (parser: MutableParser) => void;
 
@@ -73,7 +74,10 @@ export function createParser(program: ts.Program, config: CompletedConfig, augme
         return new ExposeNodeParser(typeChecker, nodeParser, config.expose, config.jsDoc);
     }
     function withTopRef(nodeParser: NodeParser): NodeParser {
-        return new TopRefNodeParser(chainNodeParser, config.type, config.topRef);
+        const typeArr = castArray(config.type);
+        // If we have multiple types, don't set a top-level $ref.
+        const topRefFullName = typeArr && typeArr.length === 1 ? typeArr[0] : undefined;
+        return new TopRefNodeParser(chainNodeParser, topRefFullName, config.topRef);
     }
     function withJsDoc(nodeParser: SubNodeParser): SubNodeParser {
         const extraTags = new Set(config.extraTags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-json-schema-generator",
-  "version": "2.5.0-next.6",
+  "version": "2.5.0-next.8",
   "description": "Generate JSON schema from your Typescript sources",
   "keywords": [
     "ts",
@@ -58,12 +58,13 @@
   "dependencies": {
     "@types/json-schema": "^7.0.15",
     "commander": "^14.0.0",
-    "glob": "^11.0.3",
+    "glob": "^13.0.0",
     "json5": "^2.2.3",
     "normalize-path": "^3.0.0",
     "safe-stable-stringify": "^2.5.0",
     "tslib": "^2.8.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "@typescript/vfs": "1.6.2"
   },
   "devDependencies": {
     "@auto-it/conventional-commits": "^11.3.0",
@@ -81,7 +82,7 @@
     "auto": "^11.3.0",
     "chai": "^6.0.1",
     "cross-env": "^10.0.0",
-    "eslint": "9.34.0",
+    "eslint": "9.39.1",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-prettier": "^5.5.1",
     "globals": "^16.3.0",

package/src/Config.ts

@@ -1,29 +1,149 @@
+import type ts from "typescript";
+
 export interface Config {
+    /**
+     * Glob pattern(s) for source TypeScript files to process.
+     * If not provided, falls back to files from tsconfig.
+     */
     path?: string;
-    type?: string;
+
+    /**
+     * Name of the type(s)/interface(s) to generate schema for.
+     * Use "*" to generate schemas for all exported types.
+     */
+    type?: string | string[];
+
+    /**
+     * Minify the output JSON schema (no whitespace).
+     * When false, the schema is pretty-printed with 2-space indentation.
+     * @default false
+     */
     minify?: boolean;
+
+    /**
+     * Sets the `$id` property in the root of the generated schema.
+     * Used for schema identification and referencing.
+     */
     schemaId?: string;
+
+    /**
+     * Path to a custom tsconfig.json file for TypeScript compilation.
+     * If not provided, uses default TypeScript configuration.
+     */
     tsconfig?: string;
+
+    /**
+     * Controls which types are exposed as definitions in the schema.
+     * - "all": Exposes all types except type literals
+     * - "none": Exposes no types automatically
+     * - "export": Only exposes exported types (respects @internal JSDoc tag)
+     * @default "export"
+     */
     expose?: "all" | "none" | "export";
+
+    /**
+     * Wraps the root type in a `$ref` definition.
+     * When false, inlines the root type definition directly.
+     * @default true
+     */
     topRef?: boolean;
+
+    /**
+     * Controls how JSDoc comments are parsed and included in the schema.
+     * - "none": Ignores all JSDoc annotations
+     * - "basic": Parses standard JSON Schema JSDoc tags
+     * - "extended": Parses all tags plus descriptions, examples, and type overrides
+     * @default "extended"
+     */
     jsDoc?: "none" | "extended" | "basic";
+
+    /**
+     * Adds a `markdownDescription` field alongside `description` in the schema.
+     * Preserves markdown formatting including newlines.
+     * Only works with `jsDoc: "extended"`.
+     * @default false
+     */
     markdownDescription?: boolean;
+
+    /**
+     * Includes the complete raw JSDoc comment as `fullDescription` in the schema.
+     * Only works with `jsDoc: "extended"`.
+     * @default false
+     */
     fullDescription?: boolean;
+
+    /**
+     * Sorts object properties alphabetically in the output.
+     * @default true
+     */
     sortProps?: boolean;
+
+    /**
+     * Controls whether tuples allow additional items beyond their defined length.
+     * @default false
+     */
     strictTuples?: boolean;
+
+    /**
+     * Skips TypeScript type checking to improve performance.
+     * Speeds up generation but may miss type errors.
+     * @default false
+     */
     skipTypeCheck?: boolean;
+
+    /**
+     * URI-encodes `$ref` values (e.g., `#/definitions/Foo%3CBar%3E`).
+     * When false, uses raw names in reference paths.
+     * @default true
+     */
     encodeRefs?: boolean;
+
+    /**
+     * Array of additional JSDoc tag names to include in the schema.
+     * Custom tags (e.g., `@customProperty`) are parsed and included in output.
+     * Values are parsed as JSON5.
+     * @default []
+     */
     extraTags?: string[];
+
+    /**
+     * Sets default value for `additionalProperties` on objects without index signatures.
+     * When false, objects get `additionalProperties: false` by default.
+     * When true, allows additional properties on all objects.
+     * @default false
+     */
     additionalProperties?: boolean;
+
+    /**
+     * Controls discriminator style for discriminated unions.
+     * - "json-schema": Uses `if`/`then`/`allOf` with properties containing discriminator enum
+     * - "open-api": Uses OpenAPI 3.x style with `discriminator: { propertyName }` and `oneOf`
+     * @default "json-schema"
+     */
     discriminatorType?: "json-schema" | "open-api";
+
+    /**
+     * Controls how function types are handled in the schema.
+     * - "fail": Throws error when encountering function types
+     * - "comment": Generates schema with `$comment` describing the function signature
+     * - "hide": Treats functions as NeverType (excluded from schema)
+     * @default "comment"
+     */
     functions?: FunctionOptions;
+
+    /**
+     * Pre-compiled TypeScript Program instance to use.
+     * Bypasses the default setup of a TypeScript program, and so some configuration options may not be applied.
+     * Useful for programmatic usage with existing TypeScript compilation, or for vfs scenarios where you do not want file-system representation.
+     */
+    tsProgram?: ts.Program;
 }
 
 export type CompletedConfig = Config & typeof DEFAULT_CONFIG;
 
 export type FunctionOptions = "fail" | "comment" | "hide";
 
-export const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId" | "tsconfig"> = {
+export const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId" | "tsconfig" | "tsProgram"> = {
     expose: "export",
     topRef: true,
     jsDoc: "extended",

package/src/SchemaGenerator.ts

@@ -10,6 +10,7 @@ import type { TypeFormatter } from "./TypeFormatter.js";
 import type { StringMap } from "./Utils/StringMap.js";
 import { hasJsDocTag } from "./Utils/hasJsDocTag.js";
 import { removeUnreachable } from "./Utils/removeUnreachable.js";
+import { castArray } from "./Utils/castArray.js";
 import { symbolAtNode } from "./Utils/symbolAtNode.js";
 
 export class SchemaGenerator {
@@ -20,8 +21,8 @@ export class SchemaGenerator {
         protected readonly config?: Config,
     ) {}
 
-    public createSchema(fullName?: string): Schema {
-        const rootNodes = this.getRootNodes(fullName);
+    public createSchema(fullNames?: string | string[]): Schema {
+        const rootNodes = this.getRootNodes(castArray(fullNames));
         return this.createSchemaFromNodes(rootNodes);
     }
 
@@ -60,9 +61,15 @@ export class SchemaGenerator {
         };
     }
 
-    protected getRootNodes(fullName: string | undefined): ts.Node[] {
-        if (fullName && fullName !== "*") {
-            return [this.findNamedNode(fullName)];
+    protected getRootNodes(fullNames: string[] | undefined): ts.Node[] {
+        // ["*"] means generate everything.
+        if (fullNames && fullNames.includes("*") && fullNames.length > 1) {
+            throw new Error("Cannot mix '*' with specific type names");
+        }
+
+        const generateAll = !fullNames || fullNames.length === 0 || (fullNames.length === 1 && fullNames[0] === "*");
+        if (!generateAll) {
+            return fullNames.map((name) => this.findNamedNode(name));
         }
 
         const rootFileNames = this.program.getRootFileNames();

package/src/Utils/castArray.ts

@@ -0,0 +1,7 @@
+export function castArray<T>(input: undefined | T | T[]): undefined | T[] {
+    if (input === undefined) {
+        return undefined;
+    }
+
+    return Array.isArray(input) ? input : [input];
+}

package/ts-json-schema-generator.ts

@@ -11,7 +11,16 @@ import pkg from "./package.json";
 
 const args = new Command()
     .option("-p, --path <path>", "Source file path")
-    .option("-t, --type <name>", "Type name")
+    .option(
+        "-t, --type <name>",
+        "Type name (can be passed multiple times)",
+        (value: string, previous: string[] | undefined) => {
+            if (previous) {
+                return previous.concat(value);
+            }
+            return [value];
+        },
+    )
     .option("-i, --id <name>", "$id for generated schema")
     .option("-f, --tsconfig <path>", "Custom tsconfig.json path")
     .addOption(
@@ -84,7 +93,7 @@ const config: Config = {
 };
 
 try {
-    const schema = createGenerator(config).createSchema(args.type);
+    const schema = createGenerator(config).createSchema(config.type);
 
     const stringify = config.sortProps ? stableStringify : JSON.stringify;
     // need as string since TS can't figure out that the string | undefined case doesn't happen