@atscript/typescript 0.1.19 → 0.1.20

package/skills/atscript-typescript/runtime.md

@@ -0,0 +1,276 @@
+# Runtime Type System — @atscript/typescript
+
+> Understanding `TAtscriptAnnotatedType`, reading/writing metadata, walking type definitions, and type structure.
+
+## `TAtscriptAnnotatedType`
+
+Every generated interface/type is a `TAtscriptAnnotatedType` — the core runtime representation:
+
+```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
+}
+```
+
+### Checking if Something is an Annotated Type
+
+```ts
+import { isAnnotatedType } from '@atscript/typescript/utils'
+
+if (isAnnotatedType(value)) {
+  // value is TAtscriptAnnotatedType
+  value.metadata.get('meta.label')
+}
+```
+
+## Type Definitions (`type.kind`)
+
+The `type` field describes the shape. There are 5 kinds:
+
+### Final (Primitive) — `kind: ''`
+
+```ts
+interface TAtscriptTypeFinal {
+  kind: ''
+  designType: 'string' | 'number' | 'boolean' | 'undefined' | 'null' | 'any' | 'never' | 'phantom'
+  value?: string | number | boolean   // for literal types
+  tags: Set<AtscriptPrimitiveTags>
+}
+```
+
+### Object — `kind: 'object'`
+
+```ts
+interface TAtscriptTypeObject<K extends string = string> {
+  kind: 'object'
+  props: Map<K, TAtscriptAnnotatedType>                    // named properties
+  propsPatterns: Array<{ pattern: RegExp; def: TAtscriptAnnotatedType }>  // pattern properties
+  tags: Set<AtscriptPrimitiveTags>
+}
+```
+
+### Array — `kind: 'array'`
+
+```ts
+interface TAtscriptTypeArray {
+  kind: 'array'
+  of: TAtscriptAnnotatedType        // element type
+  tags: Set<AtscriptPrimitiveTags>
+}
+```
+
+### Complex (Union/Intersection/Tuple) — `kind: 'union' | 'intersection' | 'tuple'`
+
+```ts
+interface TAtscriptTypeComplex {
+  kind: 'union' | 'intersection' | 'tuple'
+  items: TAtscriptAnnotatedType[]
+  tags: Set<AtscriptPrimitiveTags>
+}
+```
+
+## Reading Metadata
+
+The `metadata` field is a typed `Map<keyof AtscriptMetadata, value>`:
+
+```ts
+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
+
+// Check if annotation exists
+User.metadata.has('meta.sensitive')  // boolean
+
+// Iterate all annotations
+for (const [key, value] of User.metadata.entries()) {
+  console.log(key, value)
+}
+```
+
+### Reading Property Metadata
+
+Navigate into object properties via `type.props`:
+
+```ts
+// Get a property's annotated type
+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: "..." }
+
+// Check if optional
+nameProp.optional  // boolean | undefined
+```
+
+### Nested Properties
+
+```ts
+const addressProp = User.type.props.get('address')!
+if (addressProp.type.kind === 'object') {
+  const cityProp = addressProp.type.props.get('city')!
+  cityProp.metadata.get('meta.label')
+}
+```
+
+## Writing Metadata at Runtime
+
+Use the `annotate()` function for safe metadata mutation:
+
+```ts
+import { annotate } from '@atscript/typescript/utils'
+
+// Set a single annotation value
+annotate(User.metadata, 'meta.label', 'Updated Label')
+
+// Append to an array annotation (asArray = true)
+annotate(User.metadata, 'expect.pattern', { pattern: '^[A-Z]' }, true)
+
+// Direct Map operations also work
+User.metadata.set('meta.label', 'Direct Set')
+User.metadata.delete('meta.sensitive')
+```
+
+The `annotate()` function handles array annotations correctly — if `asArray` is `true`, it appends to existing arrays or creates a new array.
+
+## Walking Type Definitions
+
+### Manual `switch` on `type.kind`
+
+```ts
+function inspect(def: TAtscriptAnnotatedType) {
+  switch (def.type.kind) {
+    case '':        // final/primitive
+      console.log('Primitive:', def.type.designType)
+      break
+    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
+      console.log('Array of:', def.type.of.type.kind)
+      break
+    case 'union':
+    case 'intersection':
+    case 'tuple':
+      console.log(`${def.type.kind} with ${def.type.items.length} items`)
+      break
+  }
+}
+```
+
+### Using `forAnnotatedType()` Helper
+
+A type-safe dispatch helper that covers all `kind` values:
+
+```ts
+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}` },
+  // Optional: handle phantom types separately from final
+  phantom(d)      { return `phantom` },
+})
+```
+
+If `phantom` handler is provided, phantom types (`designType === 'phantom'`) are dispatched there instead of `final`. This allows consumers to skip phantom props cleanly.
+
+## Tags
+
+Each type definition has a `tags` Set containing primitive tags (e.g. `"string"`, `"number"`):
+
+```ts
+const nameProp = User.type.props.get('name')!
+nameProp.type.tags.has('string')  // true
+```
+
+Tags come from primitive definitions and their extensions. They're useful for categorizing types at runtime.
+
+## Phantom Types
+
+Phantom types carry metadata but don't affect validation or data shape:
+
+```ts
+import { isPhantomType } from '@atscript/typescript/utils'
+
+for (const [name, prop] of User.type.props) {
+  if (isPhantomType(prop)) {
+    // Skip phantom props in data processing
+    continue
+  }
+}
+```
+
+## Checking Primitive Types
+
+```ts
+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
+```
+
+## Building Types at Runtime
+
+Use `defineAnnotatedType()` to construct types programmatically:
+
+```ts
+import { defineAnnotatedType } from '@atscript/typescript/utils'
+
+// Primitive
+const strType = defineAnnotatedType().designType('string').tags('string').$type
+
+// Object
+const userType = defineAnnotatedType('object')
+  .prop('name', defineAnnotatedType().designType('string').$type)
+  .prop('age', defineAnnotatedType().designType('number').$type)
+  .prop('email', defineAnnotatedType().optional().designType('string').$type)
+  .$type
+
+// Array
+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
+
+// With metadata
+const labeledType = defineAnnotatedType().designType('string')
+  .annotate('meta.label', 'My Label')
+  .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` |

package/skills/atscript-typescript/syntax.md

@@ -0,0 +1,252 @@
+# `.as` File Syntax — @atscript/typescript
+
+> Writing Atscript files — interfaces, types, annotations, imports, exports, and property syntax.
+
+## Overview
+
+`.as` files look similar to TypeScript but add annotations (metadata) directly on types and properties. They compile to both `.d.ts` (type declarations) and `.js` (runtime metadata).
+
+## Interfaces
+
+Interfaces define object shapes with typed properties:
+
+```as
+interface User {
+  name: string
+  age: number
+  email?: string          // optional property
+  active: boolean
+}
+```
+
+### Exported Interfaces
+
+```as
+export interface User {
+  name: string
+  age: number
+}
+```
+
+### Nested Objects
+
+```as
+interface User {
+  name: string
+  address: {
+    street: string
+    city: string
+    zip: number
+  }
+}
+```
+
+## Types
+
+Type aliases for unions, intersections, tuples, and primitives:
+
+```as
+type Status = "active" | "inactive" | "pending"
+
+type StringOrNumber = string | number
+
+type Pair = [string, number]
+
+type ID = string
+```
+
+## Annotations
+
+Annotations attach metadata to interfaces, types, or properties using `@` syntax:
+
+```as
+@meta.label "User Profile"
+@meta.description "A registered user in the system"
+interface User {
+  @meta.label "Full Name"
+  @meta.required
+  @expect.minLength 2
+  @expect.maxLength 100
+  name: string
+
+  @meta.label "Age"
+  @expect.min 0
+  @expect.max 150
+  @expect.int
+  age: number
+
+  @meta.label "Email Address"
+  @expect.pattern "^[^\s@]+@[^\s@]+\.[^\s@]+$"
+  email?: string
+
+  @meta.sensitive
+  password: string
+}
+```
+
+### Annotation Syntax Rules
+
+- Annotations go **above** the property or interface they annotate
+- String arguments: `@meta.label "some text"`
+- Number arguments: `@expect.min 0`
+- No arguments (boolean flag): `@meta.sensitive`
+- Multiple arguments: `@expect.pattern "^\\d+$" "i" "Must be digits"`
+- Multiple annotations stack on the same target
+
+### Annotate Blocks (Ad-hoc Annotations)
+
+Add annotations to an existing interface without modifying it:
+
+```as
+// Non-mutating: creates a new alias with extra annotations
+export annotate UserForm = User {
+  name {
+    @meta.placeholder "Enter your name"
+  }
+  email {
+    @meta.required
+  }
+}
+
+// Mutating: modifies the original interface's metadata
+annotate User {
+  name {
+    @meta.placeholder "Enter your name"
+  }
+}
+```
+
+## Primitive Types
+
+### 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 Extensions (Subtypes)
+
+Use dot notation for specialized variants:
+
+```as
+interface User {
+  email: string.email          // email pattern validation
+  phone: string.phone          // phone number pattern
+  created: string.isoDate      // ISO 8601 date
+  id: string.uuid              // UUID v4 format
+  username: string.required    // non-empty string
+
+  age: number.int              // integer only
+  score: number.positive       // >= 0
+  balance: number.negative     // <= 0
+  timestamp: number.timestamp  // integer timestamp
+
+  agreed: boolean.required     // must be true (checkbox)
+}
+```
+
+#### 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) |
+
+#### 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 |
+
+#### Boolean Extensions
+
+| Extension | Validation |
+|-----------|-----------|
+| `boolean.required` | Must be `true` |
+| `boolean.true` | Literal true |
+| `boolean.false` | Literal false |
+
+## Imports and Exports
+
+```as
+// Import from another .as file (no extension needed)
+import { User, Address } from "./models/user"
+
+// Export interfaces/types
+export interface PublicUser {
+  name: string
+  email: string
+}
+
+export type UserStatus = "active" | "inactive"
+```
+
+## Arrays
+
+```as
+interface Team {
+  members: User[]              // array of User
+  scores: number[]             // array of numbers
+  matrix: number[][]           // nested array
+  tags: (string | number)[]    // array of union
+}
+```
+
+## Pattern Properties (Dynamic Keys)
+
+```as
+interface Config {
+  // Regular properties
+  name: string
+
+  // Pattern property — any key matching the regex
+  /^data_/: string            // keys starting with "data_"
+  /^meta_/: number            // keys starting with "meta_"
+}
+```
+
+## Unions, Intersections, Tuples
+
+```as
+// Union types
+type Result = Success | Error
+
+// Intersection types
+type Admin = User & Permissions
+
+// Tuple types
+type Coordinate = [number, number]
+type Entry = [string, number, boolean]
+
+// Literal unions
+type Direction = "north" | "south" | "east" | "west"
+type HttpCode = 200 | 400 | 404 | 500
+```
+
+## Phantom Types
+
+Phantom properties are metadata-only — they appear in the type system for traversal but don't affect data shape, validation, or JSON Schema:
+
+```as
+interface User {
+  name: string
+  collectionName: phantom     // discoverable via type traversal, not validated
+}
+```