@atscript/typescript 0.1.25 → 0.1.27

package/skills/atscript-typescript/runtime.md

@@ -8,11 +8,12 @@ Every generated interface/type is a `TAtscriptAnnotatedType` — the core runtim
 
 ```ts
 interface TAtscriptAnnotatedType<T extends TAtscriptTypeDef = TAtscriptTypeDef> {
-  __is_atscript_annotated_type: true    // brand for type checking
-  type: T                                // the type definition (shape)
-  metadata: TMetadataMap<AtscriptMetadata>  // annotation metadata
-  optional?: boolean                     // whether this type is optional
-  validator(opts?): Validator            // create a validator instance
+  __is_atscript_annotated_type: true // brand for type checking
+  type: T // the type definition (shape)
+  metadata: TMetadataMap<AtscriptMetadata> // annotation metadata
+  optional?: boolean // whether this type is optional
+  id?: string // stable type name (set by codegen or .id() builder)
+  validator(opts?): Validator // create a validator instance
 }
 ```
 
@@ -37,7 +38,7 @@ The `type` field describes the shape. There are 5 kinds:
 interface TAtscriptTypeFinal {
   kind: ''
   designType: 'string' | 'number' | 'boolean' | 'undefined' | 'null' | 'any' | 'never' | 'phantom'
-  value?: string | number | boolean   // for literal types
+  value?: string | number | boolean // for literal types
   tags: Set<AtscriptPrimitiveTags>
 }
 ```
@@ -47,8 +48,8 @@ interface TAtscriptTypeFinal {
 ```ts
 interface TAtscriptTypeObject<K extends string = string> {
   kind: 'object'
-  props: Map<K, TAtscriptAnnotatedType>                    // named properties
-  propsPatterns: Array<{ pattern: RegExp; def: TAtscriptAnnotatedType }>  // pattern properties
+  props: Map<K, TAtscriptAnnotatedType> // named properties
+  propsPatterns: Array<{ pattern: RegExp; def: TAtscriptAnnotatedType }> // pattern properties
   tags: Set<AtscriptPrimitiveTags>
 }
 ```
@@ -58,7 +59,7 @@ interface TAtscriptTypeObject<K extends string = string> {
 ```ts
 interface TAtscriptTypeArray {
   kind: 'array'
-  of: TAtscriptAnnotatedType        // element type
+  of: TAtscriptAnnotatedType // element type
   tags: Set<AtscriptPrimitiveTags>
 }
 ```
@@ -81,12 +82,12 @@ The `metadata` field is a typed `Map<keyof AtscriptMetadata, value>`:
 import { User } from './models/user.as'
 
 // Read annotations
-const label = User.metadata.get('meta.label')         // string | undefined
-const required = User.metadata.get('meta.required')    // { message?: string } | true | undefined
-const minLen = User.metadata.get('expect.minLength')   // { length: number; message?: string } | undefined
+const label = User.metadata.get('meta.label') // string | undefined
+const required = User.metadata.get('meta.required') // { message?: string } | true | undefined
+const minLen = User.metadata.get('expect.minLength') // { length: number; message?: string } | undefined
 
 // Check if annotation exists
-User.metadata.has('meta.sensitive')  // boolean
+User.metadata.has('meta.sensitive') // boolean
 
 // Iterate all annotations
 for (const [key, value] of User.metadata.entries()) {
@@ -103,11 +104,11 @@ Navigate into object properties via `type.props`:
 const nameProp = User.type.props.get('name')!
 
 // Read that property's metadata
-nameProp.metadata.get('meta.label')        // "Full Name"
-nameProp.metadata.get('meta.required')     // true or { message: "..." }
+nameProp.metadata.get('meta.label') // "Full Name"
+nameProp.metadata.get('meta.required') // true or { message: "..." }
 
 // Check if optional
-nameProp.optional  // boolean | undefined
+nameProp.optional // boolean | undefined
 ```
 
 ### Nested Properties
@@ -147,15 +148,15 @@ The `annotate()` function handles array annotations correctly — if `asArray` i
 ```ts
 function inspect(def: TAtscriptAnnotatedType) {
   switch (def.type.kind) {
-    case '':        // final/primitive
+    case '': // final/primitive
       console.log('Primitive:', def.type.designType)
       break
-    case 'object':  // object with props
+    case 'object': // object with props
       for (const [name, prop] of def.type.props) {
         console.log(`  ${name}:`, prop.type.kind || prop.type.designType)
       }
       break
-    case 'array':   // array
+    case 'array': // array
       console.log('Array of:', def.type.of.type.kind)
       break
     case 'union':
@@ -175,14 +176,28 @@ A type-safe dispatch helper that covers all `kind` values:
 import { forAnnotatedType } from '@atscript/typescript/utils'
 
 const result = forAnnotatedType(someType, {
-  final(d)        { return `primitive: ${d.type.designType}` },
-  object(d)       { return `object with ${d.type.props.size} props` },
-  array(d)        { return `array` },
-  union(d)        { return `union of ${d.type.items.length}` },
-  intersection(d) { return `intersection of ${d.type.items.length}` },
-  tuple(d)        { return `tuple of ${d.type.items.length}` },
+  final(d) {
+    return `primitive: ${d.type.designType}`
+  },
+  object(d) {
+    return `object with ${d.type.props.size} props`
+  },
+  array(d) {
+    return `array`
+  },
+  union(d) {
+    return `union of ${d.type.items.length}`
+  },
+  intersection(d) {
+    return `intersection of ${d.type.items.length}`
+  },
+  tuple(d) {
+    return `tuple of ${d.type.items.length}`
+  },
   // Optional: handle phantom types separately from final
-  phantom(d)      { return `phantom` },
+  phantom(d) {
+    return `phantom`
+  },
 })
 ```
 
@@ -194,7 +209,7 @@ Each type definition has a `tags` Set containing primitive tags (e.g. `"string"`
 
 ```ts
 const nameProp = User.type.props.get('name')!
-nameProp.type.tags.has('string')  // true
+nameProp.type.tags.has('string') // true
 ```
 
 Tags come from primitive definitions and their extensions. They're useful for categorizing types at runtime.
@@ -220,7 +235,7 @@ for (const [name, prop] of User.type.props) {
 import { isAnnotatedTypeOfPrimitive } from '@atscript/typescript/utils'
 
 // Returns true for final types and unions/intersections/tuples of all primitives
-isAnnotatedTypeOfPrimitive(someType)  // true if no objects or arrays
+isAnnotatedTypeOfPrimitive(someType) // true if no objects or arrays
 ```
 
 ## Building Types at Runtime
@@ -237,40 +252,39 @@ const strType = defineAnnotatedType().designType('string').tags('string').$type
 const userType = defineAnnotatedType('object')
   .prop('name', defineAnnotatedType().designType('string').$type)
   .prop('age', defineAnnotatedType().designType('number').$type)
-  .prop('email', defineAnnotatedType().optional().designType('string').$type)
-  .$type
+  .prop('email', defineAnnotatedType().optional().designType('string').$type).$type
 
 // Array
-const listType = defineAnnotatedType('array')
-  .of(defineAnnotatedType().designType('string').$type)
-  .$type
+const listType = defineAnnotatedType('array').of(
+  defineAnnotatedType().designType('string').$type
+).$type
 
 // Union
 const statusType = defineAnnotatedType('union')
   .item(defineAnnotatedType().designType('string').value('active').$type)
-  .item(defineAnnotatedType().designType('string').value('inactive').$type)
-  .$type
+  .item(defineAnnotatedType().designType('string').value('inactive').$type).$type
 
 // With metadata
-const labeledType = defineAnnotatedType().designType('string')
+const labeledType = defineAnnotatedType()
+  .designType('string')
   .annotate('meta.label', 'My Label')
-  .annotate('expect.minLength', { length: 3 })
-  .$type
+  .annotate('expect.minLength', { length: 3 }).$type
 ```
 
 ### `TAnnotatedTypeHandle` Fluent API
 
-| Method | Description |
-|--------|-------------|
-| `.designType(dt)` | Set primitive design type |
-| `.value(v)` | Set literal value |
-| `.tags(...tags)` | Add primitive tags |
-| `.prop(name, type)` | Add named property (object kind) |
-| `.propPattern(regex, type)` | Add pattern property (object kind) |
-| `.of(type)` | Set element type (array kind) |
-| `.item(type)` | Add item (union/intersection/tuple kind) |
-| `.optional(flag?)` | Mark as optional |
-| `.annotate(key, value, asArray?)` | Set metadata annotation |
-| `.copyMetadata(from, ignore?)` | Copy metadata from another type |
-| `.refTo(type, chain?)` | Reference another annotated type's definition |
-| `.$type` | Get the final `TAtscriptAnnotatedType` |
+| Method                            | Description                                                           |
+| --------------------------------- | --------------------------------------------------------------------- |
+| `.designType(dt)`                 | Set primitive design type                                             |
+| `.value(v)`                       | Set literal value                                                     |
+| `.tags(...tags)`                  | Add primitive tags                                                    |
+| `.prop(name, type)`               | Add named property (object kind)                                      |
+| `.propPattern(regex, type)`       | Add pattern property (object kind)                                    |
+| `.of(type)`                       | Set element type (array kind)                                         |
+| `.item(type)`                     | Add item (union/intersection/tuple kind)                              |
+| `.optional(flag?)`                | Mark as optional                                                      |
+| `.annotate(key, value, asArray?)` | Set metadata annotation                                               |
+| `.copyMetadata(from, ignore?)`    | Copy metadata from another type                                       |
+| `.id(name)`                       | Set a stable type name (used by `buildJsonSchema` for `$defs`/`$ref`) |
+| `.refTo(type, chain?)`            | Reference another annotated type's definition (carries `id`)          |
+| `.$type`                          | Get the final `TAtscriptAnnotatedType`                                |

package/skills/atscript-typescript/syntax.md

@@ -120,15 +120,15 @@ annotate User {
 
 ### Built-in Primitives
 
-| Primitive | Description |
-|-----------|-------------|
-| `string` | Text data |
-| `number` | Numeric data |
-| `boolean` | True/false |
-| `null` | Null value |
-| `void` / `undefined` | No value |
-| `never` | Impossible type |
-| `phantom` | Metadata-only type (no runtime/schema impact) |
+| Primitive            | Description                                   |
+| -------------------- | --------------------------------------------- |
+| `string`             | Text data                                     |
+| `number`             | Numeric data                                  |
+| `boolean`            | True/false                                    |
+| `null`               | Null value                                    |
+| `void` / `undefined` | No value                                      |
+| `never`              | Impossible type                               |
+| `phantom`            | Metadata-only type (no runtime/schema impact) |
 
 ### Primitive Extensions (Subtypes)
 
@@ -153,35 +153,35 @@ interface User {
 
 #### String Extensions
 
-| Extension | Validation |
-|-----------|-----------|
-| `string.email` | Email format (`^[^\s@]+@[^\s@]+\.[^\s@]+$`) |
-| `string.phone` | Phone format (`^\+?[0-9\s-]{10,15}$`) |
-| `string.date` | Date string (YYYY-MM-DD, MM/DD/YYYY, etc.) |
-| `string.isoDate` | ISO 8601 date/time |
-| `string.uuid` | UUID v4 format |
-| `string.required` | Non-empty (trimmed length >= 1) |
+| Extension         | Validation                                  |
+| ----------------- | ------------------------------------------- |
+| `string.email`    | Email format (`^[^\s@]+@[^\s@]+\.[^\s@]+$`) |
+| `string.phone`    | Phone format (`^\+?[0-9\s-]{10,15}$`)       |
+| `string.date`     | Date string (YYYY-MM-DD, MM/DD/YYYY, etc.)  |
+| `string.isoDate`  | ISO 8601 date/time                          |
+| `string.uuid`     | UUID v4 format                              |
+| `string.required` | Non-empty (trimmed length >= 1)             |
 
 #### Number Extensions
 
-| Extension | Validation |
-|-----------|-----------|
-| `number.int` | Integer (no decimals) |
-| `number.positive` | >= 0 |
-| `number.negative` | <= 0 |
-| `number.single` | Single-precision float |
-| `number.double` | Double-precision float |
-| `number.timestamp` | Integer timestamp |
-| `number.int.positive` | Integer >= 0 |
-| `number.int.negative` | Integer <= 0 |
+| Extension             | Validation             |
+| --------------------- | ---------------------- |
+| `number.int`          | Integer (no decimals)  |
+| `number.positive`     | >= 0                   |
+| `number.negative`     | <= 0                   |
+| `number.single`       | Single-precision float |
+| `number.double`       | Double-precision float |
+| `number.timestamp`    | Integer timestamp      |
+| `number.int.positive` | Integer >= 0           |
+| `number.int.negative` | Integer <= 0           |
 
 #### Boolean Extensions
 
-| Extension | Validation |
-|-----------|-----------|
+| Extension          | Validation     |
+| ------------------ | -------------- |
 | `boolean.required` | Must be `true` |
-| `boolean.true` | Literal true |
-| `boolean.false` | Literal false |
+| `boolean.true`     | Literal true   |
+| `boolean.false`    | Literal false  |
 
 ## Imports and Exports
 

package/skills/atscript-typescript/utilities.md

@@ -9,17 +9,25 @@ All utilities are exported from `@atscript/typescript/utils`:
 ```ts
 import {
   // Type construction
-  defineAnnotatedType, annotate,
+  defineAnnotatedType,
+  annotate,
   // Type checking
-  isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType,
+  isAnnotatedType,
+  isAnnotatedTypeOfPrimitive,
+  isPhantomType,
   // Type traversal
   forAnnotatedType,
   // Validation
-  Validator, ValidatorError,
+  Validator,
+  ValidatorError,
   // JSON Schema
-  buildJsonSchema, fromJsonSchema,
+  buildJsonSchema,
+  fromJsonSchema,
+  mergeJsonSchemas,
   // Serialization
-  serializeAnnotatedType, deserializeAnnotatedType, SERIALIZE_VERSION,
+  serializeAnnotatedType,
+  deserializeAnnotatedType,
+  SERIALIZE_VERSION,
   // Flattening
   flattenAnnotatedType,
   // Data creation
@@ -41,13 +49,27 @@ Dispatches over `TAtscriptAnnotatedType` by its `type.kind`, providing type-narr
 import { forAnnotatedType } from '@atscript/typescript/utils'
 
 const description = forAnnotatedType(someType, {
-  final(d)        { return `${d.type.designType}` },
-  object(d)       { return `object(${d.type.props.size} props)` },
-  array(d)        { return `array` },
-  union(d)        { return `union(${d.type.items.length})` },
-  intersection(d) { return `intersection(${d.type.items.length})` },
-  tuple(d)        { return `[${d.type.items.length}]` },
-  phantom(d)      { return `phantom` },  // optional — without it, phantoms go to final
+  final(d) {
+    return `${d.type.designType}`
+  },
+  object(d) {
+    return `object(${d.type.props.size} props)`
+  },
+  array(d) {
+    return `array`
+  },
+  union(d) {
+    return `union(${d.type.items.length})`
+  },
+  intersection(d) {
+    return `intersection(${d.type.items.length})`
+  },
+  tuple(d) {
+    return `[${d.type.items.length}]`
+  },
+  phantom(d) {
+    return `phantom`
+  }, // optional — without it, phantoms go to final
 })
 ```
 
@@ -55,7 +77,7 @@ All handlers except `phantom` are required. Each handler receives the type with
 
 ## `buildJsonSchema(type)` — Annotated Type → JSON Schema
 
-Converts an annotated type into a standard JSON Schema object, translating validation metadata:
+Converts an annotated type into a standard JSON Schema object, translating validation metadata. Named object types (those with an `id`) are automatically extracted into `$defs` and referenced via `$ref`:
 
 ```ts
 import { buildJsonSchema } from '@atscript/typescript/utils'
@@ -73,29 +95,51 @@ const schema = buildJsonSchema(User)
 // }
 ```
 
+### `$defs` and `$ref`
+
+Types compiled from `.as` files carry a stable `id` (the type name). When `buildJsonSchema` encounters named object types nested inside other types (unions, properties), it extracts them into `$defs` and references via `$ref`:
+
+```ts
+import { CatOrDog } from './pets.as'
+const schema = buildJsonSchema(CatOrDog)
+// {
+//   $defs: { Cat: { type: 'object', ... }, Dog: { type: 'object', ... } },
+//   oneOf: [{ $ref: '#/$defs/Cat' }, { $ref: '#/$defs/Dog' }],
+//   discriminator: { propertyName: 'petType', mapping: { cat: '#/$defs/Cat', dog: '#/$defs/Dog' } }
+// }
+```
+
+Key behaviors:
+
+- Only **named object types** (with `id`) are extracted to `$defs`. Primitives, unions, arrays stay inline.
+- The **root type** is never extracted — it IS the schema.
+- Same `id` referenced multiple times → one `$defs` entry, all occurrences become `$ref`.
+- Types without `id` (inline/anonymous) produce inline schemas.
+- For programmatic types, use `.id('Name')` on the builder to enable `$defs` extraction.
+
 ### Metadata → JSON Schema Mapping
 
-| Annotation | JSON Schema |
-|-----------|-------------|
-| `@expect.minLength` on string | `minLength` |
-| `@expect.maxLength` on string | `maxLength` |
-| `@expect.minLength` on array | `minItems` |
-| `@expect.maxLength` on array | `maxItems` |
-| `@expect.min` | `minimum` |
-| `@expect.max` | `maximum` |
-| `@expect.int` | `type: 'integer'` (instead of `'number'`) |
-| `@expect.pattern` (single) | `pattern` |
-| `@expect.pattern` (multiple) | `allOf: [{ pattern }, ...]` |
-| `@meta.required` on string | `minLength: 1` |
-| optional property | not in `required` array |
-| union | `anyOf` (or `oneOf` + `discriminator` for discriminated unions) |
-| intersection | `allOf` |
-| tuple | `items` as array |
-| phantom | empty object `{}` (excluded) |
+| Annotation                    | JSON Schema                                                     |
+| ----------------------------- | --------------------------------------------------------------- |
+| `@expect.minLength` on string | `minLength`                                                     |
+| `@expect.maxLength` on string | `maxLength`                                                     |
+| `@expect.minLength` on array  | `minItems`                                                      |
+| `@expect.maxLength` on array  | `maxItems`                                                      |
+| `@expect.min`                 | `minimum`                                                       |
+| `@expect.max`                 | `maximum`                                                       |
+| `@expect.int`                 | `type: 'integer'` (instead of `'number'`)                       |
+| `@expect.pattern` (single)    | `pattern`                                                       |
+| `@expect.pattern` (multiple)  | `allOf: [{ pattern }, ...]`                                     |
+| `@meta.required` on string    | `minLength: 1`                                                  |
+| optional property             | not in `required` array                                         |
+| union                         | `anyOf` (or `oneOf` + `discriminator` for discriminated unions) |
+| intersection                  | `allOf`                                                         |
+| tuple                         | `items` as array                                                |
+| phantom                       | empty object `{}` (excluded)                                    |
 
 ### Discriminated Unions
 
-When all union items are objects sharing exactly one property with distinct const/literal values, `buildJsonSchema` auto-detects it and emits `oneOf` with a `discriminator` object (including `propertyName` and `mapping`) instead of `anyOf`. No annotations needed — detection is automatic.
+When all union items are objects sharing exactly one property with distinct const/literal values, `buildJsonSchema` auto-detects it and emits `oneOf` with a `discriminator` object (including `propertyName` and `mapping`) instead of `anyOf`. When items have `id`, the mapping uses `$ref` paths into `$defs`. No annotations needed — detection is automatic.
 
 ## `fromJsonSchema(schema)` — JSON Schema → Annotated Type
 
@@ -110,16 +154,33 @@ const type = fromJsonSchema({
     name: { type: 'string', minLength: 1 },
     age: { type: 'integer', minimum: 0 },
   },
-  required: ['name', 'age']
+  required: ['name', 'age'],
 })
 
 // The resulting type has a working validator
-type.validator().validate({ name: 'Alice', age: 30 })  // passes
+type.validator().validate({ name: 'Alice', age: 30 }) // passes
 ```
 
-Supports: `type`, `properties`, `required`, `items`, `anyOf`, `oneOf`, `allOf`, `enum`, `const`, `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `minItems`, `maxItems`.
+Supports: `type`, `properties`, `required`, `items`, `anyOf`, `oneOf`, `allOf`, `enum`, `const`, `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `minItems`, `maxItems`, `$ref`/`$defs`.
+
+`$ref` paths are automatically resolved from `$defs` or `definitions` in the schema. Unresolvable `$ref` throws an error.
+
+## `mergeJsonSchemas(types)` — Combine Schemas for OpenAPI
+
+Combines multiple annotated types into a single schema map with shared `$defs` — useful for building OpenAPI `components/schemas`:
+
+```ts
+import { mergeJsonSchemas } from '@atscript/typescript/utils'
+import { CatOrDog } from './pets.as'
+import { Order } from './orders.as'
+
+const merged = mergeJsonSchemas([CatOrDog, Order])
+// merged.schemas.CatOrDog — the CatOrDog schema (oneOf with $ref)
+// merged.schemas.Order    — the Order schema
+// merged.$defs: { Cat, Dog, ... } — shared definitions, deduplicated
+```
 
-Does **not** support `$ref` — dereference schemas first.
+All types must have an `id` (all types compiled from `.as` files do). The function calls `buildJsonSchema` on each, hoists `$defs` into a shared pool, and returns individual schemas alongside merged definitions.
 
 ## `serializeAnnotatedType(type, options?)` — Serialize to JSON
 
@@ -171,7 +232,7 @@ type.validator().validate(someData)
 type.metadata.get('meta.label')
 ```
 
-Throws if the serialized version doesn't match `SERIALIZE_VERSION`.
+Throws if the serialized version doesn't match `SERIALIZE_VERSION`. The `id` field is preserved through serialization/deserialization.
 
 ### `SERIALIZE_VERSION`
 
@@ -250,19 +311,19 @@ const custom = createDataFromAnnotatedType(User, {
   mode: (prop, path) => {
     if (path === 'name') return 'John Doe'
     if (path === 'age') return 25
-    return undefined  // fall through to structural default
-  }
+    return undefined // fall through to structural default
+  },
 })
 ```
 
 ### Modes
 
-| Mode | Behavior |
-|------|----------|
-| `'empty'` (default) | Structural defaults: `''`, `0`, `false`, `[]`, `{}`. Optional props omitted |
-| `'default'` | Uses `@meta.default` annotations. Optional props only included if annotated |
-| `'example'` | Uses `@meta.example` annotations. Optional props always included. Arrays get one sample item |
-| `function` | Custom resolver per field. Return `undefined` to fall through |
+| Mode                | Behavior                                                                                     |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| `'empty'` (default) | Structural defaults: `''`, `0`, `false`, `[]`, `{}`. Optional props omitted                  |
+| `'default'`         | Uses `@meta.default` annotations. Optional props only included if annotated                  |
+| `'example'`         | Uses `@meta.example` annotations. Optional props always included. Arrays get one sample item |
+| `function`          | Custom resolver per field. Return `undefined` to fall through                                |
 
 ### Behavior Notes
 
@@ -279,8 +340,8 @@ const custom = createDataFromAnnotatedType(User, {
 import { isAnnotatedType } from '@atscript/typescript/utils'
 
 if (isAnnotatedType(value)) {
-  value.metadata  // safe
-  value.type      // safe
+  value.metadata // safe
+  value.type // safe
 }
 ```
 
@@ -291,10 +352,10 @@ Returns `true` for final types and for unions/intersections/tuples whose all mem
 ```ts
 import { isAnnotatedTypeOfPrimitive } from '@atscript/typescript/utils'
 
-isAnnotatedTypeOfPrimitive(stringType)                    // true
-isAnnotatedTypeOfPrimitive(objectType)                    // false
-isAnnotatedTypeOfPrimitive(unionOfStringAndNumber)        // true
-isAnnotatedTypeOfPrimitive(unionOfStringAndObject)        // false
+isAnnotatedTypeOfPrimitive(stringType) // true
+isAnnotatedTypeOfPrimitive(objectType) // false
+isAnnotatedTypeOfPrimitive(unionOfStringAndNumber) // true
+isAnnotatedTypeOfPrimitive(unionOfStringAndObject) // false
 ```
 
 ## `isPhantomType(def)` — Check if Phantom
@@ -302,7 +363,7 @@ isAnnotatedTypeOfPrimitive(unionOfStringAndObject)        // false
 ```ts
 import { isPhantomType } from '@atscript/typescript/utils'
 
-isPhantomType(someProperty)  // true if designType === 'phantom'
+isPhantomType(someProperty) // true if designType === 'phantom'
 ```
 
 ## `TAtscriptDataType<T>` — Extract DataType from Annotated Type
@@ -332,8 +393,12 @@ import type { TAtscriptAnnotatedType, TAtscriptDataType } from '@atscript/typesc
 
 // Generic repository that infers its entity type
 class Repository<T extends TAtscriptAnnotatedType> {
-  findOne(id: string): Promise<TAtscriptDataType<T>> { /* ... */ }
-  insertOne(data: TAtscriptDataType<T>): Promise<void> { /* ... */ }
+  findOne(id: string): Promise<TAtscriptDataType<T>> {
+    /* ... */
+  }
+  insertOne(data: TAtscriptDataType<T>): Promise<void> {
+    /* ... */
+  }
 }
 
 // Usage — DataType is automatically inferred
@@ -360,25 +425,25 @@ Key types you may need to import:
 
 ```ts
 import type {
-  TAtscriptAnnotatedType,         // core annotated type
+  TAtscriptAnnotatedType, // core annotated type
   TAtscriptAnnotatedTypeConstructor, // annotated type that's also a class
-  TAtscriptTypeDef,                // union of all type def shapes
-  TAtscriptTypeFinal,             // primitive/literal type def
-  TAtscriptTypeObject,            // object type def
-  TAtscriptTypeArray,             // array type def
-  TAtscriptTypeComplex,           // union/intersection/tuple type def
-  TMetadataMap,                   // typed metadata map
-  TAnnotatedTypeHandle,           // fluent builder handle
-  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
-  TSerializedAnnotatedType,       // serialized type (top-level)
-  TSerializeOptions,              // serialization options
-  TFlattenOptions,                // flatten options
-  TCreateDataOptions,             // createData options
-  TValueResolver,                 // custom resolver for createData
-  TJsonSchema,                    // JSON Schema object
+  TAtscriptTypeDef, // union of all type def shapes
+  TAtscriptTypeFinal, // primitive/literal type def
+  TAtscriptTypeObject, // object type def
+  TAtscriptTypeArray, // array type def
+  TAtscriptTypeComplex, // union/intersection/tuple type def
+  TMetadataMap, // typed metadata map
+  TAnnotatedTypeHandle, // fluent builder handle
+  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
+  TSerializedAnnotatedType, // serialized type (top-level)
+  TSerializeOptions, // serialization options
+  TFlattenOptions, // flatten options
+  TCreateDataOptions, // createData options
+  TValueResolver, // custom resolver for createData
+  TJsonSchema, // JSON Schema object
 } from '@atscript/typescript/utils'
 ```