@atscript/typescript 0.1.19 → 0.1.20

package/skills/atscript-typescript/utilities.md

@@ -0,0 +1,323 @@
+# Utility Functions — @atscript/typescript
+
+> All publicly exported utility functions: serialization, flattening, JSON Schema, data creation, and type traversal.
+
+## Exports Overview
+
+All utilities are exported from `@atscript/typescript/utils`:
+
+```ts
+import {
+  // Type construction
+  defineAnnotatedType, annotate,
+  // Type checking
+  isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType,
+  // Type traversal
+  forAnnotatedType,
+  // Validation
+  Validator, ValidatorError,
+  // JSON Schema
+  buildJsonSchema, fromJsonSchema,
+  // Serialization
+  serializeAnnotatedType, deserializeAnnotatedType, SERIALIZE_VERSION,
+  // Flattening
+  flattenAnnotatedType,
+  // Data creation
+  createDataFromAnnotatedType,
+} from '@atscript/typescript/utils'
+```
+
+## `forAnnotatedType(def, handlers)` — Type-Safe Dispatch
+
+Dispatches over `TAtscriptAnnotatedType` by its `type.kind`, providing type-narrowed handlers:
+
+```ts
+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
+})
+```
+
+All handlers except `phantom` are required. Each handler receives the type with its `type` field narrowed to the specific kind.
+
+## `buildJsonSchema(type)` — Annotated Type → JSON Schema
+
+Converts an annotated type into a standard JSON Schema object, translating validation metadata:
+
+```ts
+import { buildJsonSchema } from '@atscript/typescript/utils'
+import { User } from './models/user.as'
+
+const schema = buildJsonSchema(User)
+// {
+//   type: 'object',
+//   properties: {
+//     name: { type: 'string', minLength: 2, maxLength: 100 },
+//     age: { type: 'integer', minimum: 0, maximum: 150 },
+//     email: { type: 'string', pattern: '...' },
+//   },
+//   required: ['name', 'age']
+// }
+```
+
+### 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` |
+| intersection | `allOf` |
+| tuple | `items` as array |
+| phantom | empty object `{}` (excluded) |
+
+## `fromJsonSchema(schema)` — JSON Schema → Annotated Type
+
+The inverse of `buildJsonSchema`. Creates a fully functional annotated type from a JSON Schema:
+
+```ts
+import { fromJsonSchema } from '@atscript/typescript/utils'
+
+const type = fromJsonSchema({
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1 },
+    age: { type: 'integer', minimum: 0 },
+  },
+  required: ['name', 'age']
+})
+
+// The resulting type has a working validator
+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`.
+
+Does **not** support `$ref` — dereference schemas first.
+
+## `serializeAnnotatedType(type, options?)` — Serialize to JSON
+
+Converts a runtime annotated type into a plain JSON-safe object for storage or transmission:
+
+```ts
+import { serializeAnnotatedType } from '@atscript/typescript/utils'
+
+const json = serializeAnnotatedType(User)
+// json is a plain object safe for JSON.stringify()
+const str = JSON.stringify(json)
+```
+
+### Serialization Options
+
+```ts
+serializeAnnotatedType(User, {
+  // Strip specific annotation keys
+  ignoreAnnotations: ['meta.sensitive', 'mongo.collection'],
+
+  // Advanced per-annotation transform
+  processAnnotation(ctx) {
+    // ctx.key    — annotation key (e.g. 'meta.label')
+    // ctx.value  — annotation value
+    // ctx.path   — property path (e.g. ['address', 'city'])
+    // ctx.kind   — type kind at this node
+
+    // Return { key, value } to keep (possibly transformed)
+    // Return undefined to strip
+    if (ctx.key.startsWith('mongo.')) return undefined
+    return { key: ctx.key, value: ctx.value }
+  },
+})
+```
+
+## `deserializeAnnotatedType(data)` — Restore from JSON
+
+Restores a fully functional annotated type from its serialized form:
+
+```ts
+import { deserializeAnnotatedType } from '@atscript/typescript/utils'
+
+const type = deserializeAnnotatedType(json)
+
+// Fully functional — validator works
+type.validator().validate(someData)
+
+// Metadata accessible
+type.metadata.get('meta.label')
+```
+
+Throws if the serialized version doesn't match `SERIALIZE_VERSION`.
+
+### `SERIALIZE_VERSION`
+
+Current serialization format version (currently `1`). Used for forward compatibility:
+
+```ts
+import { SERIALIZE_VERSION } from '@atscript/typescript/utils'
+```
+
+## `flattenAnnotatedType(type, options?)` — Flatten to Dot-Path Map
+
+Flattens a nested object type into a `Map<string, TAtscriptAnnotatedType>` keyed by dot-separated paths:
+
+```ts
+import { flattenAnnotatedType } from '@atscript/typescript/utils'
+
+const flat = flattenAnnotatedType(User)
+// Map {
+//   ''              → root object type
+//   'name'          → string type (with metadata)
+//   'age'           → number type
+//   'address'       → nested object type
+//   'address.street' → string type
+//   'address.city'  → string type
+// }
+
+for (const [path, type] of flat) {
+  const label = type.metadata.get('meta.label')
+  console.log(path || '(root)', label)
+}
+```
+
+### Flatten Options
+
+```ts
+flattenAnnotatedType(User, {
+  // Callback for each field (non-root)
+  onField(path, type, metadata) {
+    console.log(`Field: ${path}`)
+  },
+
+  // Tag top-level array fields with a metadata key
+  topLevelArrayTag: 'mongo.__topLevelArray',
+
+  // Skip phantom types
+  excludePhantomTypes: true,
+})
+```
+
+### How Flattening Handles Complex Types
+
+- **Objects**: recursed into — each property gets its own path
+- **Arrays**: recursed into — element type's properties share the array's path prefix
+- **Unions/Intersections/Tuples**: recursed into — if the same path appears in multiple branches, they're merged into a synthetic union
+- **Primitives**: added directly at their path
+
+## `createDataFromAnnotatedType(type, options?)` — Create Default Data
+
+Creates a data object matching the type's shape, using structural defaults or annotation values:
+
+```ts
+import { createDataFromAnnotatedType } from '@atscript/typescript/utils'
+
+// Empty structural defaults ('', 0, false, [], {})
+const empty = createDataFromAnnotatedType(User)
+// { name: '', age: 0, active: false, address: { street: '', city: '' } }
+
+// Use @meta.default annotations
+const defaults = createDataFromAnnotatedType(User, { mode: 'default' })
+
+// Use @meta.example annotations
+const example = createDataFromAnnotatedType(User, { mode: 'example' })
+
+// Custom resolver function
+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
+  }
+})
+```
+
+### 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 only included if annotated |
+| `function` | Custom resolver per field. Return `undefined` to fall through |
+
+### Behavior Notes
+
+- **Optional properties** are omitted unless the mode provides a value for them
+- **Complex types** (object, array): if a `@meta.default`/`@meta.example` annotation is set and passes validation, the entire subtree is replaced (no recursion into inner props)
+- **Annotation values**: strings are used as-is for string types; everything else is parsed via `JSON.parse`
+- **Unions/Intersections**: defaults to first item's value
+- **Phantom types**: skipped
+
+## `isAnnotatedType(value)` — Type Guard
+
+```ts
+import { isAnnotatedType } from '@atscript/typescript/utils'
+
+if (isAnnotatedType(value)) {
+  value.metadata  // safe
+  value.type      // safe
+}
+```
+
+## `isAnnotatedTypeOfPrimitive(type)` — Check if Primitive
+
+Returns `true` for final types and for unions/intersections/tuples whose all members are primitives:
+
+```ts
+import { isAnnotatedTypeOfPrimitive } from '@atscript/typescript/utils'
+
+isAnnotatedTypeOfPrimitive(stringType)                    // true
+isAnnotatedTypeOfPrimitive(objectType)                    // false
+isAnnotatedTypeOfPrimitive(unionOfStringAndNumber)        // true
+isAnnotatedTypeOfPrimitive(unionOfStringAndObject)        // false
+```
+
+## `isPhantomType(def)` — Check if Phantom
+
+```ts
+import { isPhantomType } from '@atscript/typescript/utils'
+
+isPhantomType(someProperty)  // true if designType === 'phantom'
+```
+
+## Type Exports
+
+Key types you may need to import:
+
+```ts
+import 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
+  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'
+```

package/skills/atscript-typescript/validation.md

@@ -0,0 +1,293 @@
+# Validation — @atscript/typescript
+
+> Runtime data validation, type guards, error handling, and custom validator plugins.
+
+## Basic Usage
+
+Every generated `.as` interface/type has a `.validator()` factory:
+
+```ts
+import { User } from './models/user.as'
+
+// Create a validator
+const validator = User.validator()
+
+// Validate — throws ValidatorError on failure
+validator.validate(data)
+
+// Safe mode — returns boolean, no throw
+if (validator.validate(data, true)) {
+  // data is narrowed to User (type guard)
+  data.name  // TypeScript knows this exists
+}
+```
+
+## The `Validator` Class
+
+```ts
+import { Validator } from '@atscript/typescript/utils'
+
+// Create from any annotated type
+const validator = new Validator(someAnnotatedType, {
+  // Options (all optional):
+  partial: false,           // allow missing required props
+  unknownProps: 'error',    // 'error' | 'strip' | 'ignore'
+  errorLimit: 10,           // max errors before stopping
+  plugins: [],              // custom validator plugins
+  skipList: new Set(),      // property paths to skip
+})
+```
+
+### `validate(value, safe?, context?)`
+
+```ts
+// Throwing mode (default) — throws ValidatorError on failure
+validator.validate(data)
+
+// Safe mode — returns false instead of throwing
+const isValid = validator.validate(data, true)
+
+// With external context — passed to plugins
+validator.validate(data, true, { userId: '123' })
+```
+
+The `validate` method is a **TypeScript type guard** — when it returns `true`, the value is narrowed to the interface's data type.
+
+## Validator Options
+
+### `partial` — Allow Missing Properties
+
+```ts
+// Top-level properties only
+User.validator({ partial: true }).validate(data, true)
+
+// All levels (deep partial)
+User.validator({ partial: 'deep' }).validate(data, true)
+
+// Custom function — decide per object type
+User.validator({
+  partial: (objectType, path) => {
+    return path === '' // only root object is partial
+  }
+}).validate(data, true)
+```
+
+### `unknownProps` — Handle Extra Properties
+
+```ts
+// Error on unknown properties (default)
+User.validator({ unknownProps: 'error' }).validate(data, true)
+
+// Silently remove unknown properties from the value
+User.validator({ unknownProps: 'strip' }).validate(data, true)
+
+// Ignore unknown properties
+User.validator({ unknownProps: 'ignore' }).validate(data, true)
+```
+
+**Note**: `'strip'` mutates the input object — it deletes unknown keys.
+
+### `skipList` — Skip Specific Paths
+
+```ts
+User.validator({
+  skipList: new Set(['password', 'address.zip'])
+}).validate(data, true)
+```
+
+### `replace` — Substitute Type at Runtime
+
+```ts
+User.validator({
+  replace: (type, path) => {
+    if (path === 'status') return customStatusType
+    return type
+  }
+}).validate(data, true)
+```
+
+## Error Handling
+
+### `ValidatorError`
+
+When `validate()` throws (non-safe mode), it throws a `ValidatorError`:
+
+```ts
+import { ValidatorError } from '@atscript/typescript/utils'
+
+try {
+  validator.validate(data)
+} catch (e) {
+  if (e instanceof ValidatorError) {
+    // e.message — first error message (with path prefix)
+    // e.errors — full structured error array
+    console.log(e.errors)
+  }
+}
+```
+
+### Error Structure
+
+```ts
+interface TError {
+  path: string        // dot-separated path, e.g. "address.city"
+  message: string     // human-readable error message
+  details?: TError[]  // nested errors (for unions — shows why each branch failed)
+}
+```
+
+### Reading Errors in Safe Mode
+
+```ts
+const validator = User.validator()
+if (!validator.validate(data, true)) {
+  // Errors are on the validator instance
+  for (const error of validator.errors) {
+    console.log(`${error.path}: ${error.message}`)
+  }
+}
+```
+
+### Error Examples
+
+```ts
+// Missing required property
+{ path: 'name', message: 'Expected string, got undefined' }
+
+// Wrong type
+{ path: 'age', message: 'Expected number, got string' }
+
+// Pattern validation
+{ path: 'email', message: 'Value is expected to match pattern "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"' }
+
+// Custom annotation message
+{ path: 'name', message: 'Name is required' }  // from @meta.required "Name is required"
+
+// Unknown property
+{ path: 'foo', message: 'Unexpected property' }
+
+// Union — shows why each branch failed
+{
+  path: 'data',
+  message: 'Value does not match any of the allowed types: [string(0)], [number(1)]',
+  details: [
+    { path: 'data', message: 'Expected string, got boolean' },
+    { path: 'data', message: 'Expected number, got boolean' },
+  ]
+}
+
+// Array validation
+{ path: '2.name', message: 'Expected string, got number' }  // 3rd element's name is wrong
+```
+
+### Error Limit
+
+By default, the validator stops collecting errors after 10. Customize:
+
+```ts
+User.validator({ errorLimit: 50 }).validate(data, true)
+```
+
+## What Gets Validated
+
+| Type Kind | Validation |
+|-----------|-----------|
+| `string` | Type check + `@meta.required` (non-empty) + `@expect.minLength/maxLength` + `@expect.pattern` |
+| `number` | Type check + `@expect.int` + `@expect.min/max` |
+| `boolean` | Type check + `@meta.required` (must be true) |
+| `null` | Exact `null` check |
+| `undefined` | Exact `undefined` check |
+| `any` | Always passes |
+| `never` | Always fails |
+| `phantom` | Always passes (skipped) |
+| `object` | Recursively validates all props, handles unknown props, pattern props |
+| `array` | Type check + `@expect.minLength/maxLength` + recursively validates each element |
+| `union` | At least one branch must pass |
+| `intersection` | All branches must pass |
+| `tuple` | Array length must match + each element validated against its position |
+| `literal` | Exact value match |
+| `optional` | `undefined` is accepted; if value is present, validated against inner type |
+
+## Custom Validator Plugins
+
+Plugins intercept validation at every node in the type tree. They can accept, reject, or defer to default validation.
+
+### Plugin Signature
+
+```ts
+type TValidatorPlugin = (
+  ctx: TValidatorPluginContext,
+  def: TAtscriptAnnotatedType,
+  value: any
+) => boolean | undefined
+//    ↑ true = accept, false = reject, undefined = fall through to default
+```
+
+### Plugin Context
+
+```ts
+interface TValidatorPluginContext {
+  opts: TValidatorOptions                // current validator options
+  validateAnnotatedType(def, value)      // call default validation for a specific type
+  error(message, path?, details?)        // report an error
+  path: string                           // current dot-separated path
+  context: unknown                       // external context from validate(data, safe, context)
+}
+```
+
+### Plugin Example — Custom Date Validation
+
+```ts
+const datePlugin: TValidatorPlugin = (ctx, def, value) => {
+  // Only intercept string types tagged as dates
+  if (def.type.kind === '' && def.type.tags.has('date')) {
+    if (typeof value !== 'string') {
+      ctx.error('Expected date string')
+      return false
+    }
+    const parsed = Date.parse(value)
+    if (isNaN(parsed)) {
+      ctx.error(`Invalid date: "${value}"`)
+      return false
+    }
+    return true
+  }
+  // Return undefined to fall through to default validation
+  return undefined
+}
+
+User.validator({ plugins: [datePlugin] }).validate(data, true)
+```
+
+### Plugin Return Values
+
+| Return | Meaning |
+|--------|---------|
+| `true` | Value is accepted — skip all further validation for this node |
+| `false` | Value is rejected — error should be reported via `ctx.error()` before returning |
+| `undefined` | Plugin doesn't handle this type — fall through to next plugin or default validation |
+
+### Plugin Example — Coerce String to Number
+
+```ts
+const coercePlugin: TValidatorPlugin = (ctx, def, value) => {
+  if (def.type.kind === '' && def.type.designType === 'number' && typeof value === 'string') {
+    const num = Number(value)
+    if (!isNaN(num)) {
+      // Validate the coerced value against the full type (respects @expect.min etc.)
+      return ctx.validateAnnotatedType(def, num)
+    }
+  }
+  return undefined
+}
+```
+
+### Multiple Plugins
+
+Plugins run in order. The first plugin to return `true` or `false` wins — subsequent plugins and default validation are skipped for that node:
+
+```ts
+User.validator({
+  plugins: [authPlugin, datePlugin, coercePlugin]
+}).validate(data, true)
+```