ts-json-schema-generator 3.0.0-native.0 → 3.0.0-native.5

package/README.md

@@ -2,7 +2,7 @@
 
 Generate JSON schema from your TypeScript sources.
 
-Version 3 is a native binary built on [typescript-go](https://github.com/microsoft/typescript-go), the compiler that ships as TypeScript 7. It is **CLI-only** — there is no programmatic Node.js API. Projects that import `ts-json-schema-generator` as a library should stay on the 2.x line.
+Version 3 is a native binary built on [typescript-go](https://github.com/microsoft/typescript-go), the compiler released as TypeScript 7. The interface is the CLI; the package also exposes a thin [programmatic wrapper](#programmatic-usage) that runs it for you.
 
 Installing this package pulls in a small platform-specific package containing the binary for your OS and CPU (macOS, Linux, and Windows on x64 and arm64).
 
@@ -20,6 +20,42 @@ npx ts-json-schema-generator --path 'my/project/**/*.ts' --type 'My.Type.Name'
 
 The flags are the same as the 2.x CLI: `--path/-p`, `--type/-t`, `--tsconfig/-f`, `--id/-i`, `--expose/-e`, `--jsDoc/-j`, `--functions`, `--markdown-description`, `--full-description`, `--minify`, `--unstable`, `--strict-tuples`, `--no-top-ref`, `--no-type-check`, `--no-ref-encode`, `--additional-properties`, `--validation-keywords`, `--out/-o`. See [the options documentation](https://github.com/vega/ts-json-schema-generator#options) for what each one does.
 
+One flag is new in version 3: `--outdir <dir>` writes a separate `<dir>/<type>.schema.json` for every `--type`, parsing the sources once for the whole set instead of once per file.
+
+```bash
+npx ts-json-schema-generator --path 'src/**/*.ts' --outdir schemas --type Spec --type Config
+```
+
+Each file is exactly what that type's own `--out` run would have produced. `--outdir` cannot be combined with `--out`, and the types have to be listed explicitly (no `*`). Note that `--id` would then put the same `$id` on every file, which collides in resolvers that cache by `$id`. The programmatic API below is "config in, schema out" and has no `outdir` equivalent.
+
+## Programmatic usage
+
+`generateSchema` takes the same options as the 2.x `Config` type and resolves with the parsed schema, so code that was "config in, schema out" migrates by swapping the call:
+
+```js
+import { generateSchema } from "ts-json-schema-generator";
+
+const schema = await generateSchema({
+    path: "src/types.ts",
+    type: "MyType",
+    tsconfig: "tsconfig.json",
+});
+```
+
+`generateSchemaSync` is the same thing without the `await`:
+
+```js
+import { generateSchemaSync } from "ts-json-schema-generator";
+
+const schema = generateSchemaSync({ path: "src/types.ts", type: "MyType" });
+```
+
+Both spawn the native binary and throw (or reject) with an `Error` carrying the CLI's `stderr` when generation fails. TypeScript definitions ship with the package.
+
+Options that carry JavaScript values cannot cross the process boundary: an existing `tsProgram`, and augmentors such as custom node parsers, type formatters, or `SchemaGenerator` subclasses. Those are unsupported here, and passing them throws — projects that need them should stay on the 2.x line, which remains the Node.js library.
+
+Advanced: set `TS_JSON_SCHEMA_GENERATOR_BINARY` to run a specific binary instead of the one from the platform package. It applies to the CLI too, and is mainly useful for testing a local build.
+
 ## Links
 
 - Source: [vega/ts-json-schema-generator-go](https://github.com/vega/ts-json-schema-generator-go)

package/bin/ts-json-schema-generator.js

@@ -1,26 +1,16 @@
 #!/usr/bin/env node
-// Launcher for the native CLI. The binary itself lives in a per-platform
-// optional dependency; this script locates the one matching the host and
-// execs it. Dependency-free CommonJS so it runs before anything is built.
+// Launcher for the native CLI: locates the binary matching the host and execs
+// it. Dependency-free CommonJS so it runs before anything is built.
 "use strict";
 
 const { execFileSync } = require("node:child_process");
-
-const platform = process.platform;
-const arch = process.arch;
-const pkg = `ts-json-schema-generator-${platform}-${arch}`;
-const exe = platform === "win32" ? "bin/ts-json-schema-generator.exe" : "bin/ts-json-schema-generator";
+const { resolveBinary } = require("../resolve-binary.js");
 
 let binary;
 try {
-    binary = require.resolve(`${pkg}/${exe}`);
-} catch {
-    console.error(
-        `ts-json-schema-generator: no native binary for ${platform}-${arch}.\n` +
-            `The optional dependency "${pkg}" is not installed. It may not exist for this ` +
-            `platform, or the install skipped optional dependencies (--no-optional, --omit=optional).\n` +
-            `Supported platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64.`,
-    );
+    binary = resolveBinary();
+} catch (error) {
+    console.error(error.message);
     process.exit(1);
 }
 

package/index.d.ts

@@ -0,0 +1,56 @@
+export type Expose = "all" | "none" | "export";
+export type JsDoc = "none" | "basic" | "extended";
+export type FunctionOptions = "fail" | "comment" | "hide";
+
+/**
+ * Generator options. The keys mirror the `Config` type of
+ * ts-json-schema-generator 2.x; each one maps to a flag of the native CLI.
+ * Passing any other key throws.
+ */
+export interface Config {
+    /** Glob of source files to read, supporting `*` and `**`. */
+    path?: string;
+    /** Type name(s) to generate a schema for; `"*"` for all exposed types. */
+    type?: string | string[];
+    /** Path to the tsconfig.json to compile with. Defaults to the nearest one above the working directory. */
+    tsconfig?: string;
+    /** `$id` of the generated schema. */
+    schemaId?: string;
+    /** Which types get their own definition. Default `"export"`. */
+    expose?: Expose;
+    /** How much of the JSDoc annotations to read. Default `"extended"`. */
+    jsDoc?: JsDoc;
+    /** What to do with function types. Default `"comment"`. */
+    functions?: FunctionOptions;
+    /** Emit `markdownDescription` alongside `description`. Implies `jsDoc: "extended"`. */
+    markdownDescription?: boolean;
+    /** Emit the raw JSDoc comment as `fullDescription`. Implies `jsDoc: "extended"`. */
+    fullDescription?: boolean;
+    /** Sort object properties. Default `true`. */
+    sortProps?: boolean;
+    /** Emit a top-level `$ref` definition. Default `true`. */
+    topRef?: boolean;
+    /** Disallow additional items on tuples. Default `false`. */
+    strictTuples?: boolean;
+    /** Skip type checking, which is faster but reports no diagnostics. Default `false`. */
+    skipTypeCheck?: boolean;
+    /** Percent-encode characters in `$ref` values. Default `true`. */
+    encodeRefs?: boolean;
+    /** Allow additional properties on objects without an index signature. Default `false`. */
+    additionalProperties?: boolean;
+    /** Extra JSDoc tags to copy into the schema as validation keywords. */
+    extraTags?: string[];
+    /** Accepted and ignored: the schema is returned as an object. */
+    minify?: boolean;
+    /** Only `"json-schema"` is supported. */
+    discriminatorType?: "json-schema";
+}
+
+/**
+ * Generates a JSON schema by running the native CLI, resolving with the parsed
+ * schema. Rejects with an `Error` carrying the CLI's `stderr` when it fails.
+ */
+export function generateSchema(config: Config): Promise<Record<string, unknown>>;
+
+/** {@link generateSchema}, synchronously. Throws instead of rejecting. */
+export function generateSchemaSync(config: Config): Record<string, unknown>;

package/index.js

@@ -0,0 +1,155 @@
+// Programmatic wrapper around the native CLI: config in, parsed schema out.
+// Keys mirror the ts-json-schema-generator 2.x Config type so that "config in →
+// schema out" users can migrate by swapping createGenerator().createSchema()
+// for generateSchema(). Dependency-free CommonJS.
+"use strict";
+
+const { spawn, spawnSync } = require("node:child_process");
+const { resolveBinary } = require("./resolve-binary.js");
+
+// spawnSync buffers the whole schema in memory and defaults to 1 MiB, which
+// real projects exceed easily.
+const MAX_BUFFER = 512 * 1024 * 1024;
+
+// Each entry translates one config key into CLI arguments. Keys absent from
+// the config, or set to undefined/null, contribute nothing.
+const OPTIONS = {
+    path: (value, args) => args.push("--path", string("path", value)),
+    type: (value, args) => {
+        for (const type of Array.isArray(value) ? value : [value]) {
+            args.push("--type", string("type", type));
+        }
+    },
+    tsconfig: (value, args) => args.push("--tsconfig", string("tsconfig", value)),
+    schemaId: (value, args) => args.push("--id", string("schemaId", value)),
+    expose: (value, args) => args.push("--expose", string("expose", value)),
+    jsDoc: (value, args) => args.push("--jsDoc", string("jsDoc", value)),
+    functions: (value, args) => args.push("--functions", string("functions", value)),
+    markdownDescription: (value, args) => value && args.push("--markdown-description"),
+    fullDescription: (value, args) => value && args.push("--full-description"),
+    sortProps: (value, args) => value === false && args.push("--unstable"),
+    topRef: (value, args) => value === false && args.push("--no-top-ref"),
+    strictTuples: (value, args) => value === true && args.push("--strict-tuples"),
+    skipTypeCheck: (value, args) => value === true && args.push("--no-type-check"),
+    encodeRefs: (value, args) => value === false && args.push("--no-ref-encode"),
+    additionalProperties: (value, args) => value === true && args.push("--additional-properties"),
+    extraTags: (value, args) => {
+        for (const tag of Array.isArray(value) ? value : [value]) {
+            args.push("--validation-keywords", string("extraTags", tag));
+        }
+    },
+    // The schema is returned as an object, so whitespace in the CLI's output
+    // is immaterial.
+    minify: () => {},
+    discriminatorType: (value) => {
+        if (value !== "json-schema") {
+            throw new Error(
+                `ts-json-schema-generator: discriminatorType ${JSON.stringify(value)} is not supported; ` +
+                    `the native implementation always emits "json-schema" discriminators.`,
+            );
+        }
+    },
+};
+
+function string(key, value) {
+    if (typeof value !== "string") {
+        throw new Error(`ts-json-schema-generator: ${key} must be a string, got ${typeof value}`);
+    }
+    return value;
+}
+
+function toArgs(config) {
+    if (config === null || typeof config !== "object") {
+        const got = config === null ? "null" : typeof config;
+        throw new Error(`ts-json-schema-generator: config must be an object, got ${got}`);
+    }
+
+    const unsupported = Object.keys(config).filter((key) => !Object.hasOwn(OPTIONS, key));
+    if (unsupported.length > 0) {
+        throw new Error(
+            `ts-json-schema-generator: unsupported config ${unsupported.length === 1 ? "option" : "options"} ` +
+                `${unsupported.map((key) => JSON.stringify(key)).join(", ")}.\n` +
+                `Supported options: ${Object.keys(OPTIONS).join(", ")}.\n` +
+                `Because this package drives the native CLI in a separate process, options that carry ` +
+                `JavaScript values cannot work: an existing \`tsProgram\`, and augmentors such as custom ` +
+                `parsers, formatters, or SchemaGenerator subclasses. Stay on ts-json-schema-generator 2.x for those.`,
+        );
+    }
+
+    const args = [];
+    for (const [key, value] of Object.entries(config)) {
+        if (value !== undefined && value !== null) {
+            OPTIONS[key](value, args);
+        }
+    }
+    return args;
+}
+
+function parseSchema(stdout) {
+    try {
+        return JSON.parse(stdout);
+    } catch (error) {
+        throw new Error(`ts-json-schema-generator: could not parse the generated schema: ${error.message}`);
+    }
+}
+
+function failed(status, signal, stderr) {
+    const reason = signal ? `was killed by ${signal}` : `exited with code ${status}`;
+    const detail = stderr.trim();
+    const error = new Error(`ts-json-schema-generator ${reason}${detail ? `:\n${detail}` : ""}`);
+    error.exitCode = status;
+    error.signal = signal ?? null;
+    error.stderr = stderr;
+    return error;
+}
+
+// generateSchema runs the native CLI and resolves with the parsed schema.
+function generateSchema(config) {
+    let args;
+    let binary;
+    try {
+        args = toArgs(config);
+        binary = resolveBinary();
+    } catch (error) {
+        return Promise.reject(error);
+    }
+
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            reject(new Error(`ts-json-schema-generator: failed to run ${binary}: ${error.message}`));
+        });
+        child.on("close", (status, signal) => {
+            if (status !== 0 || signal) {
+                reject(failed(status, signal, Buffer.concat(stderr).toString()));
+                return;
+            }
+            try {
+                resolve(parseSchema(Buffer.concat(stdout)));
+            } catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+
+// generateSchemaSync is generateSchema without the event loop.
+function generateSchemaSync(config) {
+    const args = toArgs(config);
+    const binary = resolveBinary();
+
+    const result = spawnSync(binary, args, { maxBuffer: MAX_BUFFER });
+    if (result.error) {
+        throw new Error(`ts-json-schema-generator: failed to run ${binary}: ${result.error.message}`);
+    }
+    if (result.status !== 0 || result.signal) {
+        throw failed(result.status, result.signal, result.stderr.toString());
+    }
+    return parseSchema(result.stdout);
+}
+
+module.exports = { generateSchema, generateSchemaSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-json-schema-generator",
-  "version": "3.0.0-native.0",
+  "version": "3.0.0-native.5",
   "description": "Generate JSON schema from your TypeScript sources — native TypeScript 7 CLI",
   "license": "MIT",
   "repository": {
@@ -22,17 +22,22 @@
   "bin": {
     "ts-json-schema-generator": "bin/ts-json-schema-generator.js"
   },
+  "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "bin/ts-json-schema-generator.js",
+    "index.js",
+    "index.d.ts",
+    "resolve-binary.js",
     "README.md"
   ],
   "optionalDependencies": {
-    "ts-json-schema-generator-darwin-arm64": "3.0.0-native.0",
-    "ts-json-schema-generator-darwin-x64": "3.0.0-native.0",
-    "ts-json-schema-generator-linux-arm64": "3.0.0-native.0",
-    "ts-json-schema-generator-linux-x64": "3.0.0-native.0",
-    "ts-json-schema-generator-win32-arm64": "3.0.0-native.0",
-    "ts-json-schema-generator-win32-x64": "3.0.0-native.0"
+    "ts-json-schema-generator-darwin-arm64": "3.0.0-native.5",
+    "ts-json-schema-generator-darwin-x64": "3.0.0-native.5",
+    "ts-json-schema-generator-linux-arm64": "3.0.0-native.5",
+    "ts-json-schema-generator-linux-x64": "3.0.0-native.5",
+    "ts-json-schema-generator-win32-arm64": "3.0.0-native.5",
+    "ts-json-schema-generator-win32-x64": "3.0.0-native.5"
   },
   "engines": {
     "node": ">=20"

package/resolve-binary.js

@@ -0,0 +1,34 @@
+// Locates the native CLI binary for the host. The binary itself lives in a
+// per-platform optional dependency; TS_JSON_SCHEMA_GENERATOR_BINARY overrides
+// the lookup with an explicit path. Dependency-free CommonJS so it runs before
+// anything is built.
+"use strict";
+
+const SUPPORTED = "darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, win32-x64";
+
+// resolveBinary returns the absolute path of the native CLI, or throws an
+// Error whose message explains why no binary is available.
+function resolveBinary() {
+    const override = process.env.TS_JSON_SCHEMA_GENERATOR_BINARY;
+    if (override) {
+        return override;
+    }
+
+    const platform = process.platform;
+    const arch = process.arch;
+    const pkg = `ts-json-schema-generator-${platform}-${arch}`;
+    const exe = platform === "win32" ? "bin/ts-json-schema-generator.exe" : "bin/ts-json-schema-generator";
+
+    try {
+        return require.resolve(`${pkg}/${exe}`);
+    } catch {
+        throw new Error(
+            `ts-json-schema-generator: no native binary for ${platform}-${arch}.\n` +
+                `The optional dependency "${pkg}" is not installed. It may not exist for this ` +
+                `platform, or the install skipped optional dependencies (--no-optional, --omit=optional).\n` +
+                `Supported platforms: ${SUPPORTED}.`,
+        );
+    }
+}
+
+module.exports = { resolveBinary };