@atscript/typescript 0.1.2 → 0.1.3

package/dist/cli.cjs

@@ -234,7 +234,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		this.writeln(" * Do not edit this file!");
 		this.writeln(" */");
 		this.writeln();
-		this.writeln("import type { TAtscriptTypeObject, TAtscriptTypeComplex, TAtscriptTypeFinal, TAtscriptTypeArray, TMetadataMap, Validator, TAtscriptAnnotatedTypeConstructor, TValidatorOptions } from \"@atscript/typescript/utils\"");
+		this.writeln("import type { TAtscriptTypeObject, TAtscriptTypeComplex, TAtscriptTypeFinal, TAtscriptTypeArray, TAtscriptAnnotatedType, TMetadataMap, Validator, TValidatorOptions } from \"@atscript/typescript/utils\"");
 	}
 	post() {
 		this.writeln("// prettier-ignore-end");
@@ -323,9 +323,10 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		}
 		if (asClass) {
 			this.writeln("static __is_atscript_annotated_type: true");
-			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}>`);
+			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}, ${asClass}>`);
 			this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
-			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = typeof ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+			this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
+			if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 			this.writeln("static toJsonSchema: () => any");
 		}
 		this.pop();
@@ -340,6 +341,12 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		if (struct?.entity === "structure") this.renderStructure(struct, node.id);
 else this.writeln("{}");
 		this.writeln();
+		const nsPrefix = exported ? "export declare" : "declare";
+		this.write(`${nsPrefix} namespace ${node.id} `);
+		this.blockln("{}");
+		this.writeln(`type DataType = ${node.id}`);
+		this.popln();
+		this.writeln();
 	}
 	renderType(node) {
 		this.writeln();
@@ -366,6 +373,11 @@ else this.writeln("{}");
 		} else {
 			this.write(exported ? "export declare " : "declare ");
 			this.writeln(`class ${node.id} extends ${targetName} {}`);
+			const nsPrefix = exported ? "export declare" : "declare";
+			this.write(`${nsPrefix} namespace ${node.id} `);
+			this.blockln("{}");
+			this.writeln(`type DataType = ${node.id}`);
+			this.popln();
 			this.writeln();
 		}
 	}
@@ -380,15 +392,17 @@ else this.writeln("{}");
 			let realDef = inputDef;
 			if ((0, __atscript_core.isRef)(inputDef)) realDef = this.doc.unwindType(inputDef.id, inputDef.chain)?.def || realDef;
 			realDef = this.doc.mergeIntersection(realDef);
-			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}>`;
-else if ((0, __atscript_core.isGroup)(realDef)) typeDef = "TAtscriptTypeComplex";
-else if ((0, __atscript_core.isArray)(realDef)) typeDef = "TAtscriptTypeArray";
-else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFinal";
+			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}, ${name}>`;
+else if ((0, __atscript_core.isGroup)(realDef)) typeDef = `TAtscriptTypeComplex<${name}>`;
+else if ((0, __atscript_core.isArray)(realDef)) typeDef = `TAtscriptTypeArray<${name}>`;
+else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFinal<${name}>`;
 		}
+		this.writeln(`type DataType = ${name}`);
 		this.writeln(`const __is_atscript_annotated_type: true`);
 		this.writeln(`const type: ${typeDef}`);
 		this.writeln(`const metadata: TMetadataMap<AtscriptMetadata>`);
-		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedTypeConstructor, ${name}>`);
+		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedType, ${name}>`);
+		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 		this.writeln("const toJsonSchema: () => any");
 		this.popln();
 	}
@@ -430,6 +444,20 @@ function renderPrimitiveTypeDef(def) {
 	}
 }
 
+//#endregion
+//#region packages/typescript/src/traverse.ts
+function forAnnotatedType(def, handlers) {
+	switch (def.type.kind) {
+		case "": return handlers.final(def);
+		case "object": return handlers.object(def);
+		case "array": return handlers.array(def);
+		case "union": return handlers.union(def);
+		case "intersection": return handlers.intersection(def);
+		case "tuple": return handlers.tuple(def);
+		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+	}
+}
+
 //#endregion
 //#region packages/typescript/src/validator.ts
 function _define_property$2(obj, key, value) {
@@ -475,7 +503,17 @@ var Validator = class {
 	throw() {
 		throw new ValidatorError(this.errors);
 	}
-	validate(value, safe) {
+	/**
+	* Validates a value against the type definition.
+	*
+	* Acts as a TypeScript type guard — when it returns `true`, the value
+	* is narrowed to `DataType`.
+	*
+	* @param value - The value to validate.
+	* @param safe - If `true`, returns `false` on failure instead of throwing.
+	* @returns `true` if the value matches the type definition.
+	* @throws {ValidatorError} When validation fails and `safe` is not `true`.
+	*/ validate(value, safe) {
 		this.push("");
 		this.errors = [];
 		this.stackErrors = [];
@@ -502,15 +540,14 @@ var Validator = class {
 		return this.stackPath.slice(1).join(".");
 	}
 	validateAnnotatedType(def, value) {
-		switch (def.type.kind) {
-			case "object": return this.validateObject(def, value);
-			case "union": return this.validateUnion(def, value);
-			case "intersection": return this.validateIntersection(def, value);
-			case "tuple": return this.validateTuple(def, value);
-			case "array": return this.validateArray(def, value);
-			case "": return this.validatePrimitive(def, value);
-			default: throw new Error(`Unknown type "${def.type.kind}"`);
-		}
+		return forAnnotatedType(def, {
+			final: (d) => this.validatePrimitive(d, value),
+			object: (d) => this.validateObject(d, value),
+			array: (d) => this.validateArray(d, value),
+			union: (d) => this.validateUnion(d, value),
+			intersection: (d) => this.validateIntersection(d, value),
+			tuple: (d) => this.validateTuple(d, value)
+		});
 	}
 	validateUnion(def, value) {
 		let i = 0;
@@ -742,7 +779,7 @@ else {
 	constructor(def, opts) {
 		_define_property$2(this, "def", void 0);
 		_define_property$2(this, "opts", void 0);
-		_define_property$2(this, "errors", void 0);
+		/** Validation errors collected during the last {@link validate} call. */ _define_property$2(this, "errors", void 0);
 		_define_property$2(this, "stackErrors", void 0);
 		_define_property$2(this, "stackPath", void 0);
 		this.def = def;
@@ -888,14 +925,12 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
 	const build$1 = (def) => {
-		const t = def.type;
 		const meta = def.metadata;
-		switch (t.kind) {
-			case "object": {
-				const obj = t;
+		return forAnnotatedType(def, {
+			object(d) {
 				const properties = {};
 				const required = [];
-				for (const [key, val] of obj.props.entries()) {
+				for (const [key, val] of d.type.props.entries()) {
 					properties[key] = build$1(val);
 					if (!val.optional) required.push(key);
 				}
@@ -905,41 +940,36 @@ function buildJsonSchema(type) {
 				};
 				if (required.length) schema.required = required;
 				return schema;
-			}
-			case "array": {
-				const arr = t;
+			},
+			array(d) {
 				const schema = {
 					type: "array",
-					items: build$1(arr.of)
+					items: build$1(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (typeof minLength === "number") schema.minItems = minLength;
 				const maxLength = meta.get("expect.maxLength");
 				if (typeof maxLength === "number") schema.maxItems = maxLength;
 				return schema;
-			}
-			case "union": {
-				const grp = t;
-				return { anyOf: grp.items.map(build$1) };
-			}
-			case "intersection": {
-				const grp = t;
-				return { allOf: grp.items.map(build$1) };
-			}
-			case "tuple": {
-				const grp = t;
+			},
+			union(d) {
+				return { anyOf: d.type.items.map(build$1) };
+			},
+			intersection(d) {
+				return { allOf: d.type.items.map(build$1) };
+			},
+			tuple(d) {
 				return {
 					type: "array",
-					items: grp.items.map(build$1),
+					items: d.type.items.map(build$1),
 					additionalItems: false
 				};
-			}
-			case "": {
-				const fin = t;
+			},
+			final(d) {
 				const schema = {};
-				if (fin.value !== undefined) schema.const = fin.value;
-				if (fin.designType && fin.designType !== "any") {
-					schema.type = fin.designType === "undefined" ? "null" : fin.designType;
+				if (d.type.value !== undefined) schema.const = d.type.value;
+				if (d.type.designType && d.type.designType !== "any") {
+					schema.type = d.type.designType === "undefined" ? "null" : d.type.designType;
 					if (schema.type === "number" && meta.get("expect.int")) schema.type = "integer";
 				}
 				if (schema.type === "string") {
@@ -959,8 +989,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 				}
 				return schema;
 			}
-			default: return {};
-		}
+		});
 	};
 	return build$1(type);
 }
@@ -982,7 +1011,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("// prettier-ignore-start");
 		this.writeln("/* eslint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (!this.opts?.preRenderJsonSchema) imports.push("buildJsonSchema as $$");
+		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1070,15 +1099,21 @@ else {
 		this.writeln();
 	}
 	renderJsonSchemaMethod(node) {
-		if (this.opts?.preRenderJsonSchema) {
+		const mode = resolveJsonSchemaMode(this.opts);
+		const hasAnnotation = node.countAnnotations("emit.jsonSchema") > 0;
+		if (hasAnnotation || mode === "bundle") {
 			const schema = JSON.stringify(buildJsonSchema(this.toAnnotatedType(node)));
 			this.writeln("static toJsonSchema() {");
 			this.indent().writeln(`return ${schema}`).unindent();
 			this.writeln("}");
-		} else {
+		} else if (mode === "lazy") {
 			this.writeln("static toJsonSchema() {");
 			this.indent().writeln("return this._jsonSchema ?? (this._jsonSchema = $$(this))").unindent();
 			this.writeln("}");
+		} else {
+			this.writeln("static toJsonSchema() {");
+			this.indent().writeln("throw new Error(\"JSON Schema support is disabled. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add @emit.jsonSchema annotation to individual interfaces.\")").unindent();
+			this.writeln("}");
 		}
 	}
 	toAnnotatedType(node) {
@@ -1521,6 +1556,10 @@ else {
 
 //#endregion
 //#region packages/typescript/src/plugin.ts
+function resolveJsonSchemaMode(opts) {
+	if (opts?.jsonSchema !== undefined) return opts.jsonSchema;
+	return false;
+}
 const tsPlugin = (opts) => {
 	return {
 		name: "typesccript",

package/dist/index.cjs

@@ -231,7 +231,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		this.writeln(" * Do not edit this file!");
 		this.writeln(" */");
 		this.writeln();
-		this.writeln("import type { TAtscriptTypeObject, TAtscriptTypeComplex, TAtscriptTypeFinal, TAtscriptTypeArray, TMetadataMap, Validator, TAtscriptAnnotatedTypeConstructor, TValidatorOptions } from \"@atscript/typescript/utils\"");
+		this.writeln("import type { TAtscriptTypeObject, TAtscriptTypeComplex, TAtscriptTypeFinal, TAtscriptTypeArray, TAtscriptAnnotatedType, TMetadataMap, Validator, TValidatorOptions } from \"@atscript/typescript/utils\"");
 	}
 	post() {
 		this.writeln("// prettier-ignore-end");
@@ -320,9 +320,10 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		}
 		if (asClass) {
 			this.writeln("static __is_atscript_annotated_type: true");
-			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}>`);
+			this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}, ${asClass}>`);
 			this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
-			this.writeln(`static validator: <TT extends TAtscriptAnnotatedTypeConstructor = typeof ${asClass}>(opts?: Partial<TValidatorOptions>) => Validator<TT>`);
+			this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
+			if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 			this.writeln("static toJsonSchema: () => any");
 		}
 		this.pop();
@@ -337,6 +338,12 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		if (struct?.entity === "structure") this.renderStructure(struct, node.id);
 else this.writeln("{}");
 		this.writeln();
+		const nsPrefix = exported ? "export declare" : "declare";
+		this.write(`${nsPrefix} namespace ${node.id} `);
+		this.blockln("{}");
+		this.writeln(`type DataType = ${node.id}`);
+		this.popln();
+		this.writeln();
 	}
 	renderType(node) {
 		this.writeln();
@@ -363,6 +370,11 @@ else this.writeln("{}");
 		} else {
 			this.write(exported ? "export declare " : "declare ");
 			this.writeln(`class ${node.id} extends ${targetName} {}`);
+			const nsPrefix = exported ? "export declare" : "declare";
+			this.write(`${nsPrefix} namespace ${node.id} `);
+			this.blockln("{}");
+			this.writeln(`type DataType = ${node.id}`);
+			this.popln();
 			this.writeln();
 		}
 	}
@@ -377,15 +389,17 @@ else this.writeln("{}");
 			let realDef = inputDef;
 			if ((0, __atscript_core.isRef)(inputDef)) realDef = this.doc.unwindType(inputDef.id, inputDef.chain)?.def || realDef;
 			realDef = this.doc.mergeIntersection(realDef);
-			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}>`;
-else if ((0, __atscript_core.isGroup)(realDef)) typeDef = "TAtscriptTypeComplex";
-else if ((0, __atscript_core.isArray)(realDef)) typeDef = "TAtscriptTypeArray";
-else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = "TAtscriptTypeFinal";
+			if ((0, __atscript_core.isStructure)(realDef) || (0, __atscript_core.isInterface)(realDef)) typeDef = `TAtscriptTypeObject<keyof ${name}, ${name}>`;
+else if ((0, __atscript_core.isGroup)(realDef)) typeDef = `TAtscriptTypeComplex<${name}>`;
+else if ((0, __atscript_core.isArray)(realDef)) typeDef = `TAtscriptTypeArray<${name}>`;
+else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFinal<${name}>`;
 		}
+		this.writeln(`type DataType = ${name}`);
 		this.writeln(`const __is_atscript_annotated_type: true`);
 		this.writeln(`const type: ${typeDef}`);
 		this.writeln(`const metadata: TMetadataMap<AtscriptMetadata>`);
-		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedTypeConstructor, ${name}>`);
+		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<TAtscriptAnnotatedType, ${name}>`);
+		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
 		this.writeln("const toJsonSchema: () => any");
 		this.popln();
 	}
@@ -427,6 +441,20 @@ function renderPrimitiveTypeDef(def) {
 	}
 }
 
+//#endregion
+//#region packages/typescript/src/traverse.ts
+function forAnnotatedType(def, handlers) {
+	switch (def.type.kind) {
+		case "": return handlers.final(def);
+		case "object": return handlers.object(def);
+		case "array": return handlers.array(def);
+		case "union": return handlers.union(def);
+		case "intersection": return handlers.intersection(def);
+		case "tuple": return handlers.tuple(def);
+		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+	}
+}
+
 //#endregion
 //#region packages/typescript/src/validator.ts
 function _define_property$1(obj, key, value) {
@@ -472,7 +500,17 @@ var Validator = class {
 	throw() {
 		throw new ValidatorError(this.errors);
 	}
-	validate(value, safe) {
+	/**
+	* Validates a value against the type definition.
+	*
+	* Acts as a TypeScript type guard — when it returns `true`, the value
+	* is narrowed to `DataType`.
+	*
+	* @param value - The value to validate.
+	* @param safe - If `true`, returns `false` on failure instead of throwing.
+	* @returns `true` if the value matches the type definition.
+	* @throws {ValidatorError} When validation fails and `safe` is not `true`.
+	*/ validate(value, safe) {
 		this.push("");
 		this.errors = [];
 		this.stackErrors = [];
@@ -499,15 +537,14 @@ var Validator = class {
 		return this.stackPath.slice(1).join(".");
 	}
 	validateAnnotatedType(def, value) {
-		switch (def.type.kind) {
-			case "object": return this.validateObject(def, value);
-			case "union": return this.validateUnion(def, value);
-			case "intersection": return this.validateIntersection(def, value);
-			case "tuple": return this.validateTuple(def, value);
-			case "array": return this.validateArray(def, value);
-			case "": return this.validatePrimitive(def, value);
-			default: throw new Error(`Unknown type "${def.type.kind}"`);
-		}
+		return forAnnotatedType(def, {
+			final: (d) => this.validatePrimitive(d, value),
+			object: (d) => this.validateObject(d, value),
+			array: (d) => this.validateArray(d, value),
+			union: (d) => this.validateUnion(d, value),
+			intersection: (d) => this.validateIntersection(d, value),
+			tuple: (d) => this.validateTuple(d, value)
+		});
 	}
 	validateUnion(def, value) {
 		let i = 0;
@@ -739,7 +776,7 @@ else {
 	constructor(def, opts) {
 		_define_property$1(this, "def", void 0);
 		_define_property$1(this, "opts", void 0);
-		_define_property$1(this, "errors", void 0);
+		/** Validation errors collected during the last {@link validate} call. */ _define_property$1(this, "errors", void 0);
 		_define_property$1(this, "stackErrors", void 0);
 		_define_property$1(this, "stackPath", void 0);
 		this.def = def;
@@ -885,14 +922,12 @@ else if (!newBase) throw new Error(`"${typeName}" is not annotated type`);
 //#region packages/typescript/src/json-schema.ts
 function buildJsonSchema(type) {
 	const build = (def) => {
-		const t = def.type;
 		const meta = def.metadata;
-		switch (t.kind) {
-			case "object": {
-				const obj = t;
+		return forAnnotatedType(def, {
+			object(d) {
 				const properties = {};
 				const required = [];
-				for (const [key, val] of obj.props.entries()) {
+				for (const [key, val] of d.type.props.entries()) {
 					properties[key] = build(val);
 					if (!val.optional) required.push(key);
 				}
@@ -902,41 +937,36 @@ function buildJsonSchema(type) {
 				};
 				if (required.length) schema.required = required;
 				return schema;
-			}
-			case "array": {
-				const arr = t;
+			},
+			array(d) {
 				const schema = {
 					type: "array",
-					items: build(arr.of)
+					items: build(d.type.of)
 				};
 				const minLength = meta.get("expect.minLength");
 				if (typeof minLength === "number") schema.minItems = minLength;
 				const maxLength = meta.get("expect.maxLength");
 				if (typeof maxLength === "number") schema.maxItems = maxLength;
 				return schema;
-			}
-			case "union": {
-				const grp = t;
-				return { anyOf: grp.items.map(build) };
-			}
-			case "intersection": {
-				const grp = t;
-				return { allOf: grp.items.map(build) };
-			}
-			case "tuple": {
-				const grp = t;
+			},
+			union(d) {
+				return { anyOf: d.type.items.map(build) };
+			},
+			intersection(d) {
+				return { allOf: d.type.items.map(build) };
+			},
+			tuple(d) {
 				return {
 					type: "array",
-					items: grp.items.map(build),
+					items: d.type.items.map(build),
 					additionalItems: false
 				};
-			}
-			case "": {
-				const fin = t;
+			},
+			final(d) {
 				const schema = {};
-				if (fin.value !== undefined) schema.const = fin.value;
-				if (fin.designType && fin.designType !== "any") {
-					schema.type = fin.designType === "undefined" ? "null" : fin.designType;
+				if (d.type.value !== undefined) schema.const = d.type.value;
+				if (d.type.designType && d.type.designType !== "any") {
+					schema.type = d.type.designType === "undefined" ? "null" : d.type.designType;
 					if (schema.type === "number" && meta.get("expect.int")) schema.type = "integer";
 				}
 				if (schema.type === "string") {
@@ -956,8 +986,7 @@ else schema.allOf = (schema.allOf || []).concat(patterns.map((p) => ({ pattern:
 				}
 				return schema;
 			}
-			default: return {};
-		}
+		});
 	};
 	return build(type);
 }
@@ -979,7 +1008,7 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("// prettier-ignore-start");
 		this.writeln("/* eslint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (!this.opts?.preRenderJsonSchema) imports.push("buildJsonSchema as $$");
+		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1067,15 +1096,21 @@ else {
 		this.writeln();
 	}
 	renderJsonSchemaMethod(node) {
-		if (this.opts?.preRenderJsonSchema) {
+		const mode = resolveJsonSchemaMode(this.opts);
+		const hasAnnotation = node.countAnnotations("emit.jsonSchema") > 0;
+		if (hasAnnotation || mode === "bundle") {
 			const schema = JSON.stringify(buildJsonSchema(this.toAnnotatedType(node)));
 			this.writeln("static toJsonSchema() {");
 			this.indent().writeln(`return ${schema}`).unindent();
 			this.writeln("}");
-		} else {
+		} else if (mode === "lazy") {
 			this.writeln("static toJsonSchema() {");
 			this.indent().writeln("return this._jsonSchema ?? (this._jsonSchema = $$(this))").unindent();
 			this.writeln("}");
+		} else {
+			this.writeln("static toJsonSchema() {");
+			this.indent().writeln("throw new Error(\"JSON Schema support is disabled. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add @emit.jsonSchema annotation to individual interfaces.\")").unindent();
+			this.writeln("}");
 		}
 	}
 	toAnnotatedType(node) {
@@ -1518,6 +1553,10 @@ else {
 
 //#endregion
 //#region packages/typescript/src/plugin.ts
+function resolveJsonSchemaMode(opts) {
+	if (opts?.jsonSchema !== undefined) return opts.jsonSchema;
+	return false;
+}
 const tsPlugin = (opts) => {
 	return {
 		name: "typesccript",

package/dist/index.d.ts

@@ -2,9 +2,15 @@ import { TAtscriptPlugin } from '@atscript/core';
 
 interface TTsPluginOptions {
     /**
-     * Render JSON schemas at build-time
+     * JSON Schema support mode:
+     * - `false` — No support. `toJsonSchema()` throws at runtime. No `buildJsonSchema` import. *(default)*
+     * - `'lazy'` — Import `buildJsonSchema`, compute on demand, cache in type object.
+     * - `'bundle'` — Pre-compute at build time, embed static JSON in output. No import.
+     *
+     * Individual interfaces can override this with `@emit.jsonSchema` annotation
+     * to force build-time embedding regardless of this setting.
      */
-    preRenderJsonSchema?: boolean;
+    jsonSchema?: false | 'lazy' | 'bundle';
 }
 declare const tsPlugin: (opts?: TTsPluginOptions) => TAtscriptPlugin;