apify-schema-tools 3.0.0 → 3.2.0

package/src/cli/init.ts

@@ -0,0 +1,125 @@
+/** biome-ignore-all lint/style/useNamingConvention: the package `argparse` uses snake_case names */
+
+import { existsSync } from "node:fs";
+import { ArgumentDefaultsHelpFormatter, type SubParser } from "argparse";
+import { ACTOR_CONFIG_PATH, DATASET_SCHEMA_FIELD, getPathRelativeToActorConfig } from "../apify.js";
+import {
+	addCommonCliArgs,
+	type CommonCliArgs,
+	type Configuration,
+	writeConfigurationToPackageJson,
+} from "../configuration.js";
+import { readFile, writeFile } from "../utils/filesystem.js";
+import { readJsonSchema, readJsonSchemaField, writeJsonSchema } from "../utils/json-schemas.js";
+
+interface InitArgs extends CommonCliArgs {
+	no_config_file: boolean;
+	only_config_file: boolean;
+}
+
+export function setupInitParser(subparsers: SubParser, configuration: Configuration): void {
+	const initParser = subparsers.add_parser("init", {
+		help: "Initialize the Apify Schema Tools project with default settings.",
+		formatter_class: ArgumentDefaultsHelpFormatter,
+	});
+	addCommonCliArgs(initParser, configuration);
+	initParser.add_argument("--no-config-file", {
+		help: "do not create a configuration file in package.json",
+		action: "store_true",
+		default: false,
+	});
+	initParser.add_argument("--only-config-file", {
+		help: "create only the configuration file in package.json, without initializing schemas",
+		action: "store_true",
+		default: false,
+	});
+	initParser.set_defaults({ func: init });
+}
+
+function init(args: InitArgs): void {
+	if (args.only_config_file && args.no_config_file) {
+		throw new Error("The options --only-config-file and --no-config-file were defined together: doing nothing.");
+	}
+
+	console.log("Initializing Apify Schema Tools in the current project...");
+
+	if (!args.no_config_file) {
+		writeConfigurationToPackageJson(args);
+		console.log("Configuration written to package.json");
+	}
+
+	if (args.only_config_file) {
+		console.log("Only configuration file created, skipping schema initialization.");
+		return;
+	}
+
+	if (args.input.includes("input")) {
+		initializeInputSchema(args);
+	}
+
+	if (args.input.includes("dataset")) {
+		initializeDatasetSchema(args);
+	}
+}
+
+function initializeInputSchema(args: InitArgs): void {
+	if (existsSync(args.src_input)) {
+		console.log(`Input schema already exists at ${args.src_input}, skipping initialization.`);
+		return;
+	}
+	if (!existsSync(args.input_schema)) {
+		throw new Error("The current Actor does not have an input schema.");
+	}
+	const inputSchema = readJsonSchema(args.input_schema);
+	writeJsonSchema(args.src_input, inputSchema);
+	console.log(`Input schema initialized at ${args.src_input}`);
+	if (args.add_input) {
+		writeJsonSchema(args.add_input, { type: "object", properties: {} });
+		console.log(`Additional input schema initialized at ${args.add_input}`);
+	}
+}
+
+function initializeDatasetSchema(args: InitArgs): void {
+	if (!existsSync(ACTOR_CONFIG_PATH)) {
+		throw new Error(`The current Actor does not have an ${ACTOR_CONFIG_PATH} configuration file.`);
+	}
+	const actorConfig = JSON.parse(readFile(ACTOR_CONFIG_PATH));
+	const relativeDatasetPath = getPathRelativeToActorConfig(args.dataset_schema);
+	if (actorConfig.storages?.dataset !== relativeDatasetPath) {
+		writeFile(
+			ACTOR_CONFIG_PATH,
+			JSON.stringify(
+				{
+					...actorConfig,
+					storages: {
+						...actorConfig.storages,
+						dataset: relativeDatasetPath,
+					},
+				},
+				null,
+				4,
+			),
+		);
+		console.log(`Updated ${ACTOR_CONFIG_PATH} to use the dataset schema at ${args.dataset_schema}`);
+	}
+	if (!existsSync(args.dataset_schema)) {
+		writeFile(
+			args.dataset_schema,
+			JSON.stringify(
+				{
+					actorSpecification: 1,
+					[DATASET_SCHEMA_FIELD]: { type: "object", properties: {} },
+				},
+				null,
+				4,
+			),
+		);
+		console.log(`Dataset schema initialized at ${args.dataset_schema}`);
+	}
+	if (existsSync(args.src_dataset)) {
+		console.log(`Dataset schema already exists at ${args.src_dataset}, skipping initialization.`);
+		return;
+	}
+	const datasetItemSchema = readJsonSchemaField(args.dataset_schema, DATASET_SCHEMA_FIELD);
+	writeJsonSchema(args.src_dataset, datasetItemSchema);
+}

package/src/cli/sync.ts

@@ -0,0 +1,164 @@
+/** biome-ignore-all lint/style/useNamingConvention: the package `argparse` uses snake_case names */
+
+import { join } from "node:path";
+import { ArgumentDefaultsHelpFormatter, type SubParser } from "argparse";
+import {
+	DATASET_SCHEMA_FIELD,
+	DESCRIPTION_FIELDS,
+	filterValidInputSchemaProperties,
+	generateInputDefaultsTsFileContent,
+} from "../apify.js";
+import { addCommonCliArgs, type CommonCliArgs, type Configuration } from "../configuration.js";
+import { serializeMiddleObjectToTypeScript, writeTypeScriptFile } from "../middle-schema/generate-typescript.js";
+import { jsonSchemaToMiddleObject } from "../middle-schema/parse-json-schema.js";
+import {
+	mergeObjectSchemas,
+	type ObjectSchema,
+	readJsonSchema,
+	readJsonSchemaField,
+	writeJsonSchema,
+	writeSchemaToField,
+} from "../utils/json-schemas.js";
+import { type ConflictResolutionStrategy, checkConflicts } from "../utils/json-schemas-interactive-conflict.js";
+
+interface SyncArgs extends CommonCliArgs {
+	include_input_utils: string;
+	force: boolean;
+	fail_on_conflict: boolean;
+}
+
+export function setupSyncParser(subparsers: SubParser, configuration: Configuration): void {
+	const syncParser = subparsers.add_parser("sync", {
+		help: `Generate JSON schemas and TypeScript files from the source schemas. \
+    By default, if conflicts are detected, the user will be prompted to resolve them.`,
+		formatter_class: ArgumentDefaultsHelpFormatter,
+	});
+	addCommonCliArgs(syncParser, configuration);
+	syncParser.add_argument("--include-input-utils", {
+		help: "include input utilities in the generated TypeScript files: 'input' input and 'ts-types' output are required",
+		choices: ["true", "false"],
+		default: "true",
+	});
+	syncParser.add_argument("--force", {
+		help: "force the sync operation, even if conflicts are detected",
+		action: "store_true",
+		default: false,
+	});
+	syncParser.add_argument("--fail-on-conflict", {
+		help: "fail the sync operation if conflicts are detected",
+		action: "store_true",
+		default: false,
+	});
+	syncParser.set_defaults({ func: sync });
+}
+
+function sync(args: SyncArgs): void {
+	console.log("Syncing schemas...");
+
+	if (args.input.includes("input")) {
+		handleInputSync(args);
+	}
+
+	if (args.input.includes("dataset")) {
+		handleDatasetSync(args);
+	}
+}
+
+async function handleInputSync(args: SyncArgs): Promise<void> {
+	let inputSchemas = {
+		sourceSchema: readJsonSchema(args.src_input),
+		additionalSchema: args.add_input ? readJsonSchema(args.add_input) : undefined,
+	};
+	let resultingInputSchema: ObjectSchema | undefined;
+	if (args.output.includes("json-schemas")) {
+		const conflictResolutionStrategy = getConflictResolutionStrategy(args);
+		const existingInputSchema = readJsonSchema(args.input_schema);
+		inputSchemas = await checkConflicts(
+			inputSchemas.sourceSchema,
+			args.src_input,
+			inputSchemas.additionalSchema,
+			args.add_input,
+			existingInputSchema,
+			args.deep_merge,
+			DESCRIPTION_FIELDS,
+			conflictResolutionStrategy,
+		);
+		resultingInputSchema = inputSchemas.additionalSchema
+			? mergeObjectSchemas(inputSchemas.sourceSchema, inputSchemas.additionalSchema, args.deep_merge)
+			: inputSchemas.sourceSchema;
+		writeJsonSchema(args.input_schema, filterValidInputSchemaProperties(resultingInputSchema));
+	}
+	if (args.output.includes("ts-types")) {
+		resultingInputSchema ??= inputSchemas.additionalSchema
+			? mergeObjectSchemas(inputSchemas.sourceSchema, inputSchemas.additionalSchema, args.deep_merge)
+			: inputSchemas.sourceSchema;
+		writeTypeScriptFile(
+			join(args.output_ts_dir, "input.ts"),
+			serializeMiddleObjectToTypeScript("Input", jsonSchemaToMiddleObject(resultingInputSchema)),
+		);
+		if (args.include_input_utils === "true") {
+			writeTypeScriptFile(
+				join(args.output_ts_dir, "input-utils.ts"),
+				generateInputDefaultsTsFileContent(resultingInputSchema),
+			);
+		}
+	}
+	// Update the source schemas, which may have been modified by the conflict resolution
+	writeJsonSchema(args.src_input, inputSchemas.sourceSchema);
+	if (args.add_input && inputSchemas.additionalSchema) {
+		writeJsonSchema(args.add_input, inputSchemas.additionalSchema);
+	}
+}
+
+async function handleDatasetSync(args: SyncArgs): Promise<void> {
+	let datasetSchemas = {
+		sourceSchema: readJsonSchema(args.src_dataset),
+		additionalSchema: args.add_dataset ? readJsonSchema(args.add_dataset) : undefined,
+	};
+	let resultingDatasetSchema: ObjectSchema | undefined;
+	if (args.output.includes("json-schemas")) {
+		const conflictResolutionStrategy = getConflictResolutionStrategy(args);
+		const existingDatasetSchema = readJsonSchemaField(args.dataset_schema, DATASET_SCHEMA_FIELD);
+		datasetSchemas = await checkConflicts(
+			datasetSchemas.sourceSchema,
+			args.src_dataset,
+			datasetSchemas.additionalSchema,
+			args.add_dataset,
+			existingDatasetSchema,
+			args.deep_merge,
+			DESCRIPTION_FIELDS,
+			conflictResolutionStrategy,
+		);
+		resultingDatasetSchema = datasetSchemas.additionalSchema
+			? mergeObjectSchemas(datasetSchemas.sourceSchema, datasetSchemas.additionalSchema, args.deep_merge)
+			: datasetSchemas.sourceSchema;
+		writeSchemaToField(args.dataset_schema, resultingDatasetSchema, DATASET_SCHEMA_FIELD);
+	}
+	if (args.output.includes("ts-types")) {
+		resultingDatasetSchema ??= datasetSchemas.additionalSchema
+			? mergeObjectSchemas(datasetSchemas.sourceSchema, datasetSchemas.additionalSchema, args.deep_merge)
+			: datasetSchemas.sourceSchema;
+		writeTypeScriptFile(
+			join(args.output_ts_dir, "dataset.ts"),
+			serializeMiddleObjectToTypeScript("DatasetItem", jsonSchemaToMiddleObject(resultingDatasetSchema)),
+		);
+	}
+	// Update the source schemas, which may have been modified by the conflict resolution
+	writeJsonSchema(args.src_dataset, datasetSchemas.sourceSchema);
+	if (args.add_dataset && datasetSchemas.additionalSchema) {
+		writeJsonSchema(args.add_dataset, datasetSchemas.additionalSchema);
+	}
+}
+
+function getConflictResolutionStrategy(args: SyncArgs): ConflictResolutionStrategy {
+	if (args.fail_on_conflict && args.force) {
+		throw new Error("The options --force and --fail-on-conflict cannot be defined together.");
+	}
+	if (args.force) {
+		return "log";
+	}
+	if (args.fail_on_conflict) {
+		return "error";
+	}
+	return "interactive";
+}

package/src/configuration.ts

@@ -2,12 +2,13 @@
 
 import { existsSync } from "node:fs";
 import type { ArgumentParser } from "argparse";
-import { array, enum as enum_, object, string, type infer as zodInfer } from "zod/v4";
-import { readFile, writeFile } from "./filesystem.js";
+import { array, boolean, enum as enum_, object, string, type infer as zodInfer } from "zod/v4";
+import { readFile, writeFile } from "./utils/filesystem.js";
 
 const zod = {
 	object,
 	array,
+	boolean,
 	enum: enum_,
 	string,
 };
@@ -18,6 +19,10 @@ const OUTPUTS = ["json-schemas", "ts-types"] as const;
 type Input = (typeof INPUTS)[number];
 type Output = (typeof OUTPUTS)[number];
 
+/**
+ * These CLI arguments are also available in the configuration file.
+ * They are in snake_case because `argparse` uses it for argument names.
+ */
 export interface CommonCliArgs {
 	input: Input[];
 	output: Output[];
@@ -25,27 +30,35 @@ export interface CommonCliArgs {
 	src_dataset: string;
 	add_input?: string;
 	add_dataset?: string;
+	deep_merge: boolean;
 	input_schema: string;
 	dataset_schema: string;
 	output_ts_dir: string;
 }
 
-export const Configuration = zod.object({
+/**
+ * Zod schema for the configuration file.
+ * Since the configuration is in JSON format, we use camelCase.
+ */
+export const CONFIGURATION_SCHEMA = zod.object({
 	input: zod.array(zod.enum(INPUTS)).default([...INPUTS]),
 	output: zod.array(zod.enum(OUTPUTS)).default([...OUTPUTS]),
 	srcInput: zod.string().default("src-schemas/input.json"),
 	srcDataset: zod.string().default("src-schemas/dataset-item.json"),
 	addInput: zod.string().optional(),
 	addDataset: zod.string().optional(),
+	deepMerge: zod.boolean().default(false),
 	inputSchema: zod.string().default(".actor/input_schema.json"),
 	datasetSchema: zod.string().default(".actor/dataset_schema.json"),
 	outputTSDir: zod.string().default("src/generated"),
 });
 
-export function parseConfigurationFromFileOrDefault(): zodInfer<typeof Configuration> {
+export type Configuration = zodInfer<typeof CONFIGURATION_SCHEMA>;
+
+export function parseConfigurationFromFileOrDefault(): Configuration {
 	const packageJsonContent = existsSync("package.json") ? readFile("package.json") : undefined;
 	const rawConfig = packageJsonContent ? (JSON.parse(packageJsonContent)["apify-schema-tools"] ?? {}) : {};
-	return Configuration.parse(rawConfig);
+	return CONFIGURATION_SCHEMA.parse(rawConfig);
 }
 
 export function writeConfigurationToPackageJson(args: CommonCliArgs): void {
@@ -61,6 +74,7 @@ export function writeConfigurationToPackageJson(args: CommonCliArgs): void {
 		srcDataset: args.src_dataset,
 		addInput: args.add_input,
 		addDataset: args.add_dataset,
+		deepMerge: args.deep_merge,
 		inputSchema: args.input_schema,
 		datasetSchema: args.dataset_schema,
 		outputTSDir: args.output_ts_dir,
@@ -69,10 +83,10 @@ export function writeConfigurationToPackageJson(args: CommonCliArgs): void {
 }
 
 /**
- * This function will set as default values the configuration from package.json, or the default one.
- * In this way, the CLI arguments can override the configuration.
+ * This function will set as default values the configuration file, or the default one.
+ * In this way, the CLI arguments can override the configuration file.
  */
-export function addCommonCLIArgs(parser: ArgumentParser, configuration: zodInfer<typeof Configuration>): void {
+export function addCommonCliArgs(parser: ArgumentParser, configuration: zodInfer<typeof CONFIGURATION_SCHEMA>): void {
 	parser.add_argument("-i", "--input", {
 		help: "specify which sources to use for generation",
 		choices: [...INPUTS],
@@ -103,6 +117,11 @@ export function addCommonCLIArgs(parser: ArgumentParser, configuration: zodInfer
 		help: "path to an additional schema to merge into the dataset schema",
 		default: configuration.addDataset,
 	});
+	parser.add_argument("--deep-merge", {
+		help: "whether to deep merge additional schemas into the main schema",
+		action: "store_true",
+		default: configuration.deepMerge,
+	});
 
 	parser.add_argument("--input-schema", {
 		help: "the path of the destination input schema file",

package/src/main.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/** biome-ignore-all lint/style/useNamingConvention: the package `argparse` uses snake_case names */
+
+import { ArgumentDefaultsHelpFormatter, ArgumentParser } from "argparse";
+import { setupCheckParser } from "./cli/check.js";
+import { setupInitParser } from "./cli/init.js";
+import { setupSyncParser } from "./cli/sync.js";
+import { parseConfigurationFromFileOrDefault } from "./configuration.js";
+
+const configuration = parseConfigurationFromFileOrDefault();
+
+const rootParser = new ArgumentParser({
+	description: "Apify Schema Tools - Generate JSON schemas and TypeScript files for Actor input and output dataset.",
+	formatter_class: ArgumentDefaultsHelpFormatter,
+});
+
+const subparsers = rootParser.add_subparsers();
+
+setupInitParser(subparsers, configuration);
+setupSyncParser(subparsers, configuration);
+setupCheckParser(subparsers, configuration);
+
+const parsedArgs = rootParser.parse_args();
+parsedArgs.func(parsedArgs);

package/src/middle-schema/compare-schemas.ts

@@ -0,0 +1,113 @@
+import { equals } from "ramda";
+import {
+	isMiddleBasicVar,
+	isMiddleEnum,
+	isMiddleObject,
+	type MiddleBasicVar,
+	type MiddleEnum,
+	type MiddleObject,
+	type MiddleSchema,
+} from "./schema-types.js";
+
+function compareObjectProperties(key: string, propA: MiddleObject, propB: MiddleSchema, ignoreDocs?: boolean): boolean {
+	if (!isMiddleObject(propB)) {
+		console.error(`Property "${key}" is an interface in one schema but not in the other.`);
+		return false;
+	}
+	if (!compareMiddleObjects(propA, propB, ignoreDocs)) {
+		console.error(`Property "${key}" interfaces do not match.`);
+		return false;
+	}
+	return true;
+}
+
+function compareEnumProperties(key: string, propA: MiddleSchema, propB: MiddleSchema): boolean {
+	if (!isMiddleEnum(propB)) {
+		console.error(`Property "${key}" is an enum in one schema but not in the other.`);
+		return false;
+	}
+	if (JSON.stringify((propA as MiddleEnum).enum) !== JSON.stringify((propB as MiddleEnum).enum)) {
+		console.error(
+			`Property "${key}" enums do not match: ${JSON.stringify((propA as MiddleEnum).enum)} vs ${JSON.stringify((propB as MiddleEnum).enum)}`,
+		);
+		return false;
+	}
+	return true;
+}
+
+function compareBasicVarProperties(key: string, propA: MiddleSchema, propB: MiddleSchema): boolean {
+	if (!isMiddleBasicVar(propB)) {
+		console.error(`Property "${key}" is a basic var in one schema but not in the other.`);
+		return false;
+	}
+	if (!equals((propA as MiddleBasicVar).type, (propB as MiddleBasicVar).type)) {
+		console.error(
+			`Property "${key}" types do not match: ${JSON.stringify((propA as MiddleBasicVar).type)} vs ${JSON.stringify((propB as MiddleBasicVar).type)}`,
+		);
+		return false;
+	}
+	return true;
+}
+
+function compareProperties(key: string, propA: MiddleSchema, propB: MiddleSchema, ignoreDocs?: boolean): boolean {
+	if (propA.isArray !== propB.isArray) {
+		console.error(`Property "${key}" has different array status: ${propA.isArray} vs ${propB.isArray}`);
+		return false;
+	}
+
+	if (propA.isRequired !== propB.isRequired) {
+		console.error(`Property "${key}" has different required status: ${propA.isRequired} vs ${propB.isRequired}`);
+		return false;
+	}
+
+	if (!ignoreDocs && propA.doc !== propB.doc) {
+		console.error(`Property "${key}" has different documentation: "${propA.doc}" vs "${propB.doc}"`);
+		return false;
+	}
+
+	if (isMiddleObject(propA)) {
+		return compareObjectProperties(key, propA, propB, ignoreDocs);
+	}
+	if (isMiddleEnum(propA)) {
+		return compareEnumProperties(key, propA, propB);
+	}
+	return compareBasicVarProperties(key, propA, propB);
+}
+
+function compareAdditionalProperties(a: MiddleObject, b: MiddleObject, ignoreDocs?: boolean): boolean {
+	if (!(a.additionalProperties || b.additionalProperties)) {
+		return true; // Both have no additional properties
+	}
+	if (!(a.additionalProperties && b.additionalProperties)) {
+		console.error(`One interface has additionalProperties defined, but the other does not.
+If you generated an interface from a JSON schema, pay attention that "additionalProperties" is set to an empty schema by default.`);
+		return false;
+	}
+	return compareProperties("[key: string]", a.additionalProperties, b.additionalProperties, ignoreDocs);
+}
+
+export function compareMiddleObjects(a: MiddleObject, b: MiddleObject, ignoreDocs?: boolean): boolean {
+	if (Object.keys(a.properties).length !== Object.keys(b.properties).length) {
+		console.error("Interfaces have different number of properties.");
+		return false;
+	}
+
+	for (const key in a.properties) {
+		if (Object.hasOwn(a.properties, key)) {
+			if (!(key in b.properties)) {
+				return false;
+			}
+			const propA = a.properties[key];
+			const propB = b.properties[key];
+			if (!compareProperties(key, propA, propB, ignoreDocs)) {
+				return false;
+			}
+		}
+	}
+
+	if (!compareAdditionalProperties(a, b, ignoreDocs)) {
+		return false;
+	}
+
+	return true;
+}

package/src/middle-schema/generate-typescript.ts

@@ -0,0 +1,88 @@
+import { readFile, writeFile } from "../utils/filesystem.js";
+import {
+	isMiddleBasicVar,
+	isMiddleEnum,
+	isMiddleObject,
+	type MiddleBasicVar,
+	type MiddleEnum,
+	type MiddleObject,
+	type MiddleSchema,
+} from "./schema-types.js";
+
+export const TYPESCRIPT_FILE_HEADER = `\
+/**
+ * This file was automatically generated by apify-schema-tools.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run apify-schema-tools' "sync" command to regenerate this file.
+ */
+
+`;
+
+function serializeInterfaceSchema(schema: MiddleObject, indentLevel: number): string {
+	const indent = "\t".repeat(indentLevel);
+	const properties = Object.entries(schema.properties);
+	if (properties.length === 0 && !schema.additionalProperties) {
+		return "{}";
+	}
+	const innerIndentLevel = indentLevel + 1;
+	const innerIndent = "\t".repeat(innerIndentLevel);
+	let result = "{";
+	for (const [key, value] of properties) {
+		if (value.doc) {
+			result += `\n${innerIndent}/**\n${innerIndent} * ${value.doc}\n${innerIndent} */`;
+		}
+		result += `\n${innerIndent}${key}${
+			value.isRequired ? "" : "?"
+		}: ${serializeMiddleSchemaToTypeScript(value, innerIndentLevel)};`;
+	}
+	if (schema.additionalProperties) {
+		result += `\n${innerIndent}[key: string]: ${serializeMiddleSchemaToTypeScript(
+			schema.additionalProperties,
+			innerIndentLevel,
+		)};`;
+	}
+	result += `\n${indent}}`;
+	return result;
+}
+
+function serializeEnumSchema(schema: MiddleEnum): string {
+	const serializedEnum = JSON.stringify(schema.enum).replace(/\[|\]/g, "").replace(/,/g, " | ");
+	return schema.isArray && schema.enum.length > 1 ? `(${serializedEnum})` : serializedEnum;
+}
+
+function serializeBasicVarSchema(schema: MiddleBasicVar): string {
+	if (Array.isArray(schema.type)) {
+		return schema.isArray ? `(${schema.type.join(" | ")})` : schema.type.join(" | ");
+	}
+	return schema.type;
+}
+
+export function serializeMiddleSchemaToTypeScript(schema: MiddleSchema, indentLevel = 0): string {
+	let result = "";
+	if (isMiddleObject(schema)) {
+		result = serializeInterfaceSchema(schema, indentLevel);
+	} else if (isMiddleEnum(schema)) {
+		result = serializeEnumSchema(schema);
+	} else if (isMiddleBasicVar(schema)) {
+		result = serializeBasicVarSchema(schema);
+	}
+	if (schema.isArray) {
+		result += "[]";
+	}
+	return result;
+}
+
+export function serializeMiddleObjectToTypeScript(name: string, schema: MiddleObject): string {
+	const serializedSchema = serializeMiddleSchemaToTypeScript(schema);
+	const docComment = schema.doc ? `/**\n * ${schema.doc}\n */\n` : "";
+	return `${docComment}export interface ${name} ${serializedSchema}${schema.isRequired ? "" : " | undefined"}`;
+}
+
+export function writeTypeScriptFile(filePath: string, content: string): void {
+	writeFile(filePath, TYPESCRIPT_FILE_HEADER + content);
+}
+
+export function readGeneratedTypeScriptFile(filePath: string): string {
+	const content = readFile(filePath);
+	return content.replace(TYPESCRIPT_FILE_HEADER, "");
+}