@atscript/typescript 0.1.20 → 0.1.21

package/dist/cli.cjs

@@ -334,6 +334,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			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");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -397,6 +399,8 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${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");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1081,7 +1085,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1127,6 +1134,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1182,7 +1190,14 @@ else {
 			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.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/index.cjs

@@ -331,6 +331,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			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");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -394,6 +396,8 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${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");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1078,7 +1082,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1124,6 +1131,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1179,7 +1187,14 @@ else {
 			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.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/index.d.ts

@@ -11,6 +11,12 @@ interface TTsPluginOptions {
      * to force build-time embedding regardless of this setting.
      */
     jsonSchema?: false | 'lazy' | 'bundle';
+    /**
+     * Example data support:
+     * - `false` — No support. `toExampleData` is not rendered. *(default)*
+     * - `true` — Import `createDataFromAnnotatedType`, create example data on each call.
+     */
+    exampleData?: boolean;
 }
 declare const tsPlugin: (opts?: TTsPluginOptions) => TAtscriptPlugin;
 

package/dist/index.mjs

@@ -307,6 +307,8 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			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");
+			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+			this.writeln("static toExampleData?: () => any");
 		}
 		this.pop();
 	}
@@ -370,6 +372,8 @@ else if (isPrimitive(realDef)) typeDef = `TAtscriptTypeFinal<${name}>`;
 		this.writeln(`const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${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");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
 	phantomPropType(def) {
@@ -1054,7 +1058,10 @@ var JsRenderer = class extends BaseRenderer {
 		this.writeln("/* eslint-disable */");
 		this.writeln("/* oxlint-disable */");
 		const imports = ["defineAnnotatedType as $", "annotate as $a"];
-		if (resolveJsonSchemaMode(this.opts) === "lazy") imports.push("buildJsonSchema as $$");
+		const jsonSchemaMode = resolveJsonSchemaMode(this.opts);
+		if (jsonSchemaMode === "lazy") imports.push("buildJsonSchema as $$");
+		if (this.opts?.exampleData) imports.push("createDataFromAnnotatedType as $e");
+		if (jsonSchemaMode === false) imports.push("throwFeatureDisabled as $d");
 		this.writeln(`import { ${imports.join(", ")} } from "@atscript/typescript/utils"`);
 	}
 	buildAdHocMap(annotateNodes) {
@@ -1100,6 +1107,7 @@ else {
 		this.writeln("static type = {}");
 		this.writeln("static metadata = new Map()");
 		this.renderJsonSchemaMethod(node);
+		this.renderExampleDataMethod(node);
 	}
 	renderInterface(node) {
 		this.writeln();
@@ -1155,7 +1163,14 @@ else {
 			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.indent().writeln("$d(\"JSON Schema\", \"jsonSchema\", \"emit.jsonSchema\")").unindent();
+			this.writeln("}");
+		}
+	}
+	renderExampleDataMethod(_node) {
+		if (this.opts?.exampleData) {
+			this.writeln("static toExampleData() {");
+			this.indent().writeln("return $e(this, { mode: \"example\" })").unindent();
 			this.writeln("}");
 		}
 	}

package/dist/utils.cjs

@@ -799,6 +799,12 @@ function build(def, path, mode) {
 	});
 }
 
+//#endregion
+//#region packages/typescript/src/throw-disabled.ts
+function throwFeatureDisabled(feature, option, annotation) {
+	throw new Error(`${feature} support is disabled. To enable, set \`${option}: 'lazy'\` or \`${option}: 'bundle'\` in tsPlugin options, or add @${annotation} annotation to individual interfaces.`);
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -1058,4 +1064,5 @@ exports.fromJsonSchema = fromJsonSchema
 exports.isAnnotatedType = isAnnotatedType
 exports.isAnnotatedTypeOfPrimitive = isAnnotatedTypeOfPrimitive
 exports.isPhantomType = isPhantomType
-exports.serializeAnnotatedType = serializeAnnotatedType
+exports.serializeAnnotatedType = serializeAnnotatedType
+exports.throwFeatureDisabled = throwFeatureDisabled

package/dist/utils.d.ts

@@ -342,6 +342,12 @@ interface TCreateDataOptions {
  */
 declare function createDataFromAnnotatedType(type: TAtscriptAnnotatedType, opts?: TCreateDataOptions): unknown;
 
+/**
+ * Throws a runtime error indicating that a feature is disabled.
+ * Used by generated JS files to avoid duplicating the error message string.
+ */
+declare function throwFeatureDisabled(feature: string, option: string, annotation: string): never;
+
 /**
  * Options for controlling the flattening process.
  */
@@ -489,5 +495,5 @@ declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?:
  */
 declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };
 export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/dist/utils.mjs

@@ -798,6 +798,12 @@ function build(def, path, mode) {
 	});
 }
 
+//#endregion
+//#region packages/typescript/src/throw-disabled.ts
+function throwFeatureDisabled(feature, option, annotation) {
+	throw new Error(`${feature} support is disabled. To enable, set \`${option}: 'lazy'\` or \`${option}: 'bundle'\` in tsPlugin options, or add @${annotation} annotation to individual interfaces.`);
+}
+
 //#endregion
 //#region packages/typescript/src/flatten.ts
 function flattenAnnotatedType(type, options) {
@@ -1043,4 +1049,4 @@ function deserializeTypeDef(t) {
 }
 
 //#endregion
-export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -64,7 +64,7 @@
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.20"
+    "@atscript/core": "^0.1.21"
   },
   "build": [
     {},
@@ -85,7 +85,6 @@
   "scripts": {
     "pub": "pnpm publish --access public",
     "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js",
-    "postinstall": "node ./scripts/setup-skills.js --postinstall"
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/skills/atscript-typescript/SKILL.md

@@ -34,7 +34,7 @@ import {
   buildJsonSchema, fromJsonSchema,
   serializeAnnotatedType, deserializeAnnotatedType,
   flattenAnnotatedType, createDataFromAnnotatedType,
-  forAnnotatedType,
+  forAnnotatedType, throwFeatureDisabled,
 } from '@atscript/typescript/utils'
 
 // CLI

package/skills/atscript-typescript/codegen.md

@@ -44,6 +44,8 @@ export declare class User {
   static metadata: TMetadataMap<AtscriptMetadata>
   static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof User>
   static toJsonSchema: () => any
+  /** When exampleData is disabled (default), marked @deprecated + optional */
+  static toExampleData?: () => any
 }
 
 export type Status = "active" | "inactive"
@@ -53,13 +55,15 @@ declare namespace Status {
   const metadata: TMetadataMap<AtscriptMetadata>
   const validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof Status>
   const toJsonSchema: () => any
+  const toExampleData: (() => any) | undefined
 }
 ```
 
 Key points:
 - **Interfaces** become `declare class` — so they work both as types and runtime values
 - **Types** become a `type` alias + a companion `namespace` with runtime statics
-- Each has `type`, `metadata`, `validator()`, and `toJsonSchema()` statics
+- Each has `type`, `metadata`, `validator()`, `toJsonSchema()`, and `toExampleData()` statics
+- `toExampleData` is always optional in `.d.ts`. When `exampleData: true`, it's rendered without deprecation; when disabled, it's marked `@deprecated`
 
 ## `.js` Output
 
@@ -68,6 +72,8 @@ The JS module creates actual classes with runtime type definitions and metadata:
 - Uses `defineAnnotatedType` (aliased as `$`) to build the type tree
 - Populates metadata maps with all annotation values
 - Wires up `validator()` and `toJsonSchema()` methods
+- When `exampleData: true`, adds `toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })` (aliased as `$e`)
+- When `jsonSchema: false` (default), `toJsonSchema()` calls `throwFeatureDisabled()` (aliased as `$d`) instead of inlining the error message
 
 You don't normally read or modify generated JS — the build tool handles it.
 

package/skills/atscript-typescript/core.md

@@ -71,10 +71,21 @@ tsPlugin({
   jsonSchema: false    // default — toJsonSchema() throws at runtime
   // jsonSchema: 'lazy'   — import buildJsonSchema, compute on demand, cache
   // jsonSchema: 'bundle' — pre-compute at build time, embed in output
+
+  exampleData: false   // default — toExampleData() not rendered
+  // exampleData: true  — render toExampleData() using createDataFromAnnotatedType
 })
 ```
 
-Individual interfaces can override this with `@emit.jsonSchema` annotation to force build-time embedding regardless of plugin setting.
+### `jsonSchema`
+
+Individual interfaces can override the JSON Schema setting with `@emit.jsonSchema` annotation to force build-time embedding regardless of plugin setting.
+
+### `exampleData`
+
+Controls whether `toExampleData()` is generated on output classes:
+- `false` *(default)* — method is not rendered in `.js`; `.d.ts` marks it as optional + `@deprecated`
+- `true` — each class gets `static toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })`, creating a new example data object on each call (no caching)
 
 ## Build Tool Integration
 

package/skills/atscript-typescript/utilities.md

@@ -24,9 +24,15 @@ import {
   flattenAnnotatedType,
   // Data creation
   createDataFromAnnotatedType,
+  // Feature gating (used by generated code)
+  throwFeatureDisabled,
 } from '@atscript/typescript/utils'
 ```
 
+### `throwFeatureDisabled(feature, option, annotation)`
+
+Throws a runtime error indicating a feature is disabled. Used by generated `.js` files to avoid duplicating the error message string across all classes. Called as `$d("JSON Schema", "jsonSchema", "emit.jsonSchema")` in generated code when `jsonSchema: false`.
+
 ## `forAnnotatedType(def, handlers)` — Type-Safe Dispatch
 
 Dispatches over `TAtscriptAnnotatedType` by its `type.kind`, providing type-narrowed handlers: