Quick Start

A minimal working example — from installing Atscript to validating data in TypeScript.

1. Install

npm install @atscript/typescript
npm install -D @atscript/core unplugin-atscript

@atscript/typescript is a regular dependency — it ships runtime utilities (validation, metadata access) that your code needs at runtime. @atscript/core and unplugin-atscript are dev-only (build tooling).

2. Create a .as File

Create src/user.as — this is your single source of truth for the data model, metadata, and validation constraints:

export interface User {
    @meta.label 'User Name'
    @expect.minLength 2
    name: string

    @meta.label 'Email Address'
    email: string.email

    @expect.min 0
    age: number
}

Here we define an interface with annotations like @meta.label and @expect.minLength, and a semantic type string.email that carries built-in validation. See Interfaces & Types for the full syntax.

3. Configure Atscript

Create atscript.config.js in your project root:

import { defineConfig } from '@atscript/core'
import ts from '@atscript/typescript'

export default defineConfig({
  rootDir: 'src',
  plugins: [ts()],
})

See Configuration for all available options and plugin settings.

4. Set Up Your Build

Install unplugin-atscript and configure your bundler. Here's a Vite example for a Node.js library:

// vite.config.js
import { defineConfig } from 'vite'
import atscript from 'unplugin-atscript'

export default defineConfig({
  plugins: [atscript.vite()],
  build: {
    lib: {
      entry: 'src/index.ts',
      formats: ['es'],
    },
    rollupOptions: {
      external: [/node_modules/],
    },
  },
})

The plugin compiles .as files automatically during the build. See Build Setup for Rollup, esbuild, and other bundlers.

5. Generate Type Definitions

Install the Atscript VSCode extension — it automatically generates .as.d.ts files on save, giving you IntelliSense and type checking. See the VSCode section for details.

Alternatively, use the CLI:

npx asc -f dts

This generates .as.d.ts files for each .as file and an atscript.d.ts file with annotation type definitions. Run this at least once so TypeScript knows about your annotation types. See CLI for all options.

Add atscript.d.ts to your tsconfig.json:

{
  "include": ["src/**/*", "atscript.d.ts"]
}

6. Use in TypeScript

Import your .as types — the imported User is a fully typed class whose data shape matches the interface you defined:

// The generated type is equivalent to:
declare class User {
  name: string
  email: string
  age: number
}

Beyond the data shape, it also carries static members that give you runtime access to everything declared in the .as file:

• User.type — the annotated type definition; traverse properties, access per-property metadata and tags
• User.metadata — top-level metadata map for the interface itself
• User.validator() — creates a Validator that enforces @expect.* annotations and semantic type rules
• User.toJsonSchema() — generates a JSON Schema from the type and its annotations

Here's a quick example:

// src/index.ts
import { User } from './user.as'

// Access metadata
const emailProp = User.type.props.get('email')
console.log(emailProp?.metadata.get('meta.label'))
// → 'Email Address'

// Validate data
const validator = User.validator()

const data: any = {
  name: 'A',
  email: 'not-an-email',
  age: -5,
}

if (validator.validate(data, true)) {
  console.log('Valid user:', data.name)
} else {
  console.log('Validation errors:')
  for (const err of validator.errors) {
    console.log(`  ${err.path}: ${err.message}`)
  }
}

Expected output:

Validation errors:
  name: Expected minimum length 2
  email: Expected valid email
  age: Expected minimum value 0

Next Steps

• Interfaces & Types — how interfaces and type aliases work in .as files
• Annotations — built-in annotations (@meta.*, @expect.*) and how to define custom ones
• Primitives — semantic type extensions like string.email, number.positive
• Configuration — custom annotations, primitives, and plugin options