@atscript/typescript 0.1.20 → 0.1.22

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

@@ -48,11 +48,7 @@ interface TValidatorPluginContext {
  * @typeParam T - The annotated type definition.
  * @typeParam DataType - The TypeScript type that `validate` narrows to (auto-inferred).
  */
-declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = T extends {
-    type: {
-        __dataType?: infer D;
-    };
-} ? unknown extends D ? T extends new (...args: any[]) => infer I ? I : unknown : D : unknown> {
+declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
     protected readonly def: T;
     protected opts: TValidatorOptions;
     constructor(def: T, opts?: Partial<TValidatorOptions>);
@@ -148,6 +144,26 @@ interface TAtscriptTypeFinal<DataType = unknown> {
 type InferDataType<T> = T extends {
     __dataType?: infer D;
 } ? D : unknown;
+/**
+ * Extract the DataType from a {@link TAtscriptAnnotatedType}.
+ *
+ * Resolves the phantom `__dataType` carried by the type definition.
+ * When `__dataType` is `unknown` (unset), falls back to the constructor
+ * instance type if `T` is also a class (i.e. a generated interface).
+ *
+ * @example
+ * ```ts
+ * import type { TAtscriptDataType } from '@atscript/typescript/utils'
+ * import MyInterface from './my-interface.as'
+ *
+ * type Data = TAtscriptDataType<typeof MyInterface>
+ * ```
+ */
+type TAtscriptDataType<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> = T extends {
+    type: {
+        __dataType?: infer D;
+    };
+} ? unknown extends D ? T extends new (...args: any[]) => infer I ? I : unknown : D : unknown;
 /** Union of all possible type definition shapes. */
 type TAtscriptTypeDef<DataType = unknown> = TAtscriptTypeComplex<DataType> | TAtscriptTypeFinal<DataType> | TAtscriptTypeArray<DataType> | TAtscriptTypeObject<string, DataType>;
 /**
@@ -342,6 +358,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 +511,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 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 };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };
+export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, 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.22",
   "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.22"
   },
   "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:
@@ -294,6 +300,55 @@ import { isPhantomType } from '@atscript/typescript/utils'
 isPhantomType(someProperty)  // true if designType === 'phantom'
 ```
 
+## `TAtscriptDataType<T>` — Extract DataType from Annotated Type
+
+Utility type that extracts the underlying data shape from a `TAtscriptAnnotatedType`. This is the primary way to obtain a TypeScript data type from an Atscript-generated class, especially useful in generic contexts.
+
+```ts
+import type { TAtscriptDataType } from '@atscript/typescript/utils'
+import { Product } from './product.as'
+
+type ProductData = TAtscriptDataType<typeof Product>
+// ProductData = { name: string; price: number; tags: string[] }
+```
+
+### How It Resolves
+
+1. Extracts the phantom `__dataType` from the type definition
+2. If `__dataType` is `unknown` (unset), falls back to the constructor's instance type (`T extends new (...) => infer I`)
+3. Otherwise returns `unknown`
+
+### Use in Generics
+
+`TAtscriptDataType` is designed for generic code that needs to derive data types from annotated type parameters:
+
+```ts
+import type { TAtscriptAnnotatedType, TAtscriptDataType } from '@atscript/typescript/utils'
+
+// Generic repository that infers its entity type
+class Repository<T extends TAtscriptAnnotatedType> {
+  findOne(id: string): Promise<TAtscriptDataType<T>> { /* ... */ }
+  insertOne(data: TAtscriptDataType<T>): Promise<void> { /* ... */ }
+}
+
+// Usage — DataType is automatically inferred
+const repo = new Repository<typeof Product>()
+const product = await repo.findOne('123') // typed as Product
+
+// Generic function
+function validate<T extends TAtscriptAnnotatedType>(
+  schema: T,
+  data: unknown
+): data is TAtscriptDataType<T> {
+  return schema.validator().validate(data, true)
+}
+```
+
+### Difference from `InferDataType`
+
+- `TAtscriptDataType<T>` — operates on `TAtscriptAnnotatedType` (the full annotated wrapper). Use this for generated classes and generic code.
+- `InferDataType<T>` — operates on raw type definitions (`TAtscriptTypeDef`, `TAtscriptTypeObject`, etc.). Lower-level, extracts `__dataType` from the type def's phantom generic directly.
+
 ## Type Exports
 
 Key types you may need to import:
@@ -309,7 +364,8 @@ import type {
   TAtscriptTypeComplex,           // union/intersection/tuple type def
   TMetadataMap,                   // typed metadata map
   TAnnotatedTypeHandle,           // fluent builder handle
-  InferDataType,                  // extract DataType from a type def
+  InferDataType,                  // extract DataType from a type def's phantom generic
+  TAtscriptDataType,              // extract DataType from TAtscriptAnnotatedType
   TValidatorOptions,              // validator config
   TValidatorPlugin,               // plugin function type
   TValidatorPluginContext,         // plugin context