@atscript/typescript 0.1.26 → 0.1.28

package/skills/atscript-typescript/codegen.md

@@ -6,10 +6,10 @@
 
 Each `.as` file produces two outputs:
 
-| Output | Generated By | Contains |
-|--------|-------------|----------|
+| Output      | Generated By                   | Contains                                                                                             |
+| ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
 | `*.as.d.ts` | `npx asc -f dts` or build tool | TypeScript type declarations — interfaces become `declare class` with static type/metadata/validator |
-| `*.as.js` | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories |
+| `*.as.js`   | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories          |
 
 ## `.d.ts` Output
 
@@ -31,9 +31,12 @@ Generates `user.as.d.ts`:
 
 ```ts
 import type {
-  TAtscriptTypeObject, TAtscriptAnnotatedType,
-  TMetadataMap, Validator, TValidatorOptions
-} from "@atscript/typescript/utils"
+  TAtscriptTypeObject,
+  TAtscriptAnnotatedType,
+  TMetadataMap,
+  Validator,
+  TValidatorOptions,
+} from '@atscript/typescript/utils'
 
 export declare class User {
   name: string
@@ -48,7 +51,7 @@ export declare class User {
   static toExampleData?: () => any
 }
 
-export type Status = "active" | "inactive"
+export type Status = 'active' | 'inactive'
 declare namespace Status {
   const __is_atscript_annotated_type: true
   const type: TAtscriptTypeComplex<Status>
@@ -60,6 +63,7 @@ declare namespace Status {
 ```
 
 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()`, `toJsonSchema()`, and `toExampleData()` statics
@@ -92,7 +96,7 @@ declare global {
     'expect.minLength': { length: number; message?: string }
     // ... all annotations used in your project
   }
-  type AtscriptPrimitiveTags = "string" | "number" | "boolean" | "null"
+  type AtscriptPrimitiveTags = 'string' | 'number' | 'boolean' | 'null'
 }
 ```
 
@@ -108,8 +112,8 @@ This file is **auto-generated** based on the annotations actually used across al
 
 Generated files use these import paths:
 
-| Import | Source |
-|--------|--------|
+| Import                       | Source                                            |
+| ---------------------------- | ------------------------------------------------- |
 | `@atscript/typescript/utils` | Runtime utilities (used by generated `.js` files) |
 
 When importing from `.as` files in your TypeScript code:

package/skills/atscript-typescript/core.md

@@ -51,18 +51,18 @@ export default defineConfig({
 
 ### `TAtscriptConfig` Fields
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `rootDir` | `string` | Root directory for resolving files |
-| `entries` | `string[]` | Entry point globs for `.as` files |
-| `include` | `string[]` | Include globs |
-| `exclude` | `string[]` | Exclude globs |
-| `plugins` | `TAtscriptPlugin[]` | Build plugins (e.g. `tsPlugin()`) |
-| `primitives` | `Record<string, TPrimitiveConfig>` | Custom primitive type definitions |
-| `annotations` | `TAnnotationsTree` | Custom annotation definitions |
-| `unknownAnnotation` | `'allow' \| 'warn' \| 'error'` | Unknown annotation handling |
-| `format` | `string` | Output format (set by CLI or build tool) |
-| `outDir` | `string` | Output directory |
+| Field               | Type                               | Description                              |
+| ------------------- | ---------------------------------- | ---------------------------------------- |
+| `rootDir`           | `string`                           | Root directory for resolving files       |
+| `entries`           | `string[]`                         | Entry point globs for `.as` files        |
+| `include`           | `string[]`                         | Include globs                            |
+| `exclude`           | `string[]`                         | Exclude globs                            |
+| `plugins`           | `TAtscriptPlugin[]`                | Build plugins (e.g. `tsPlugin()`)        |
+| `primitives`        | `Record<string, TPrimitiveConfig>` | Custom primitive type definitions        |
+| `annotations`       | `TAnnotationsTree`                 | Custom annotation definitions            |
+| `unknownAnnotation` | `'allow' \| 'warn' \| 'error'`     | Unknown annotation handling              |
+| `format`            | `string`                           | Output format (set by CLI or build tool) |
+| `outDir`            | `string`                           | Output directory                         |
 
 ## TypeScript Plugin Options
 
@@ -84,7 +84,8 @@ Individual interfaces can override the JSON Schema setting with `@emit.jsonSchem
 ### `exampleData`
 
 Controls whether `toExampleData()` is generated on output classes:
-- `false` *(default)* — method is not rendered in `.js`; `.d.ts` marks it as optional + `@deprecated`
+
+- `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
@@ -96,7 +97,7 @@ Controls whether `toExampleData()` is generated on output classes:
 import atscript from 'unplugin-atscript/vite'
 
 export default {
-  plugins: [atscript()]
+  plugins: [atscript()],
 }
 ```
 
@@ -106,7 +107,7 @@ export default {
 // webpack.config.js
 const atscript = require('unplugin-atscript/webpack')
 module.exports = {
-  plugins: [atscript()]
+  plugins: [atscript()],
 }
 ```
 
@@ -136,6 +137,7 @@ npx asc --skipDiag
 ### Why run `npx asc -f dts`?
 
 This generates two things:
+
 1. **`*.as.d.ts`** files next to each `.as` file — TypeScript type declarations for all interfaces/types
 2. **`atscript.d.ts`** in the project root — global type declarations for `AtscriptMetadata` and `AtscriptPrimitiveTags`
 
@@ -143,12 +145,12 @@ The `atscript.d.ts` file is **crucial for type safety** — it tells TypeScript
 
 ### CLI Options
 
-| Option | Short | Description |
-|--------|-------|-------------|
-| `--config <path>` | `-c` | Path to config file |
-| `--format <fmt>` | `-f` | Output format: `dts`, `js` |
-| `--noEmit` | | Only check for errors |
-| `--skipDiag` | | Skip diagnostics, always emit |
+| Option            | Short | Description                   |
+| ----------------- | ----- | ----------------------------- |
+| `--config <path>` | `-c`  | Path to config file           |
+| `--format <fmt>`  | `-f`  | Output format: `dts`, `js`    |
+| `--noEmit`        |       | Only check for errors         |
+| `--skipDiag`      |       | Skip diagnostics, always emit |
 
 ## Project Structure Example
 

package/skills/atscript-typescript/runtime.md

@@ -8,12 +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
-  id?: string                            // stable type name (set by codegen or .id() builder)
-  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
 }
 ```
 
@@ -38,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>
 }
 ```
@@ -48,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>
 }
 ```
@@ -59,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>
 }
 ```
@@ -82,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()) {
@@ -104,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
@@ -148,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':
@@ -176,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`
+  },
 })
 ```
 
@@ -195,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.
@@ -221,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
@@ -238,41 +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 |
-| `.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` |
+| 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