Atscript

atscript

.as = single source of truth for types + metadata + validation. @atscript/typescript compiles .as → .d.ts (types) + .js (runtime metadata). Consumers use those for validation, JSON Schema, serialization, ORM mapping.

Language-agnostic. Core ships @meta.*, @expect.*, @emit.*; @db.*, @ui.*, and custom namespaces come from plugins.

Quick start

npm install @atscript/typescript @atscript/core

atscript.config.{ts,mts,cts,js,mjs,cjs} at project root:

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

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

Build:

npx asc            # emits .d.ts (default) + project-wide atscript.d.ts
npx asc -f js      # emits runtime .js metadata

Full walkthrough with a first .as file, consume snippet, and troubleshooting → getting-started.md.

Key imports

// Config
import { defineConfig, AnnotationSpec } from '@atscript/core'
import type { TAtscriptPlugin, TAtscriptConfig } from '@atscript/core'

// Plugin factory (build-time only)
import ts from '@atscript/typescript'

// Runtime helpers (used by generated .as.js — also available to consumers)
import {
  defineAnnotatedType,             // fluent builder (in generated code)
  forAnnotatedType,                // kind-dispatched walker
  Validator, ValidatorError,
  buildJsonSchema, fromJsonSchema, mergeJsonSchemas, detectDiscriminator,
  serializeAnnotatedType, deserializeAnnotatedType, SERIALIZE_VERSION,
  isAnnotatedType, isAnnotatedTypeOfPrimitive,
} from '@atscript/typescript/utils'
import type { TAtscriptAnnotatedType, TValidatorPlugin } from '@atscript/typescript/utils'

// Test fixtures (compile .as at test-time, inject tsPlugin automatically)
import { prepareFixtures } from '@atscript/typescript/test-utils'

// Moost HTTP integration
import { coercionPipe, validatorPipe, validationErrorTransform } from '@atscript/moost-validator'

// Bundler integration (pick one)
import atscript from 'unplugin-atscript/vite'      // or /rollup /rolldown /webpack /esbuild /rspack /farm

Invariants

1. @meta.id takes no arguments. Multiple @meta.id on different props = composite PK. Never @meta.id(...).
2. Generated files (*.as.d.ts, *.as.js, atscript.d.ts) are never hand-edited. Fix the .as source or plugin. Regenerate with npx asc -f dts.
3. Core ships @meta.*, @expect.*, @emit.* only. All other namespaces come from plugins.
4. asc without -f runs every plugin's default output (TS plugin emits .d.ts). Pass -f js for runtime .js (or let unplugin-atscript produce it at bundle time).
5. @atscript/typescript/utils is the runtime entry; @atscript/typescript default export is tsPlugin() (build-time factory).
6. Never import type a compiled .as artifact. .as exports are classes — value AND type in one name — consumed at runtime (.validator(), .metadata, decorators, DI by param type via design:paramtypes). A type-only import elides the value: decorator metadata emits Object and validation/DI/form binding break silently. Keep lint rules that force type-only imports (typescript/consistent-type-imports and equivalents) off in projects importing .as files — the create-moost preset and ecosystem repos already disable it.

Dependency chain

@atscript/core          parser, AST, plugin system, diagnostics
  └─ @atscript/typescript    codegen + runtime + asc CLI
       ├─ @atscript/moost-validator   Moost pipe + error transform
       └─ unplugin-atscript           Vite/Rollup/Rolldown/Webpack/esbuild/Rspack/Farm
  └─ @atscript/vscode     LSP, syntax, completions, go-to-def

DB layer (@atscript/db, db-sqlite, db-mongo, db-mysql, moost-db, @db.*, schema sync, relations, views): separate repo at https://db.atscript.dev. UI layer (@atscript/ui, vue-form, vue-table, Moost workflow, @ui.*): separate repo.

Companion skills:

npx skills add moostjs/atscript      # this skill (core/typescript/unplugin/vscode/moost-validator)
npx skills add moostjs/atscript-db   # DB layer
npx skills add moostjs/atscript-ui   # UI layer

References — load only what's needed

Full docs: https://atscript.dev.