atscript

atscript

.as = 类型、元数据和校验的唯一事实来源。@atscript/typescript 会将 .as 编译为 .d.ts（类型）和 .js（运行时元数据）。使用者可利用这些文件进行校验、JSON Schema 生成、序列化和 ORM 映射。

语言无关。核心仅提供 @meta.*、@expect.*、@emit.*；@db.*、@ui.* 和自定义命名空间由插件提供。

快速开始

npm install @atscript/typescript @atscript/core

在项目根目录创建 atscript.config.{ts,mts,cts,js,mjs,cjs}：

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

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

构建：

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

完整操作指南涵盖第一个 .as 文件、使用示例和故障排查 → getting-started.md。

关键导入

// 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

不变量

1. @meta.id 不接受参数。在不同属性上使用多个 @meta.id = 复合主键。绝不要写成 @meta.id(...)。
2. 绝不手动编辑生成的文件（*.as.d.ts、*.as.js、atscript.d.ts）。请修复 .as 源文件或插件，然后使用 npx asc -f dts 重新生成。
3. 核心仅提供 @meta.*、@expect.*、@emit.*。其他所有命名空间都由插件提供。
4. 不带 -f 的 asc 会运行每个插件的默认输出（TS 插件会生成 .d.ts）。传入 -f js 以生成运行时 .js（也可以在打包时由 unplugin-atscript 生成）。
5. @atscript/typescript/utils 是运行时入口；@atscript/typescript 的默认导出是 tsPlugin()（构建时工厂）。
6. 绝不要对已编译的 .as 产物使用 import type。 .as 导出的是类，同一个名称兼作值和类型，并在运行时使用（.validator()、.metadata、装饰器、通过参数类型进行的 DI，即 design:paramtypes）。仅类型导入会消除值：装饰器元数据会输出 Object，导致校验、DI 和表单绑定静默失效。在导入 .as 文件的项目中，关闭强制仅类型导入的 lint 规则（typescript/consistent-type-imports 及同类规则）——create-moost 预设和生态仓库已将其禁用。

依赖链

@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 层（@atscript/db、db-sqlite、db-mongo、db-mysql、moost-db、@db.*、架构同步、关系、视图）：位于独立仓库 https://db.atscript.dev。 UI 层（@atscript/ui、vue-form、vue-table、Moost 工作流、@ui.*）：位于独立仓库。

配套技能：

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

参考 — 仅加载所需内容

领域	文件	适用场景
初次使用	getting-started.md	安装、首个 .as 文件、首次运行代码生成、使用代码片段、故障排除
.as 语法	as-syntax.md	interface/type、联合类型、交叉类型、元组、数组、导入、模式属性、annotate 块
注解	annotations.md	@meta.*、@expect.*、合并、自定义 AnnotationSpec、query / expr / order 参数（反引号表达式、算术、排序、括号内的运算符、“字段引用后应有运算符”）、参数上的编辑器钩子（fieldScope、refFilter — 参数内部的补全/悬停/F12）
基本类型	primitives.md	内置类型、语义扩展、decimal、phantom、通过配置扩展
配置	config.md	atscript.config.*、defineConfig、条目/glob、插件接入、输出、models（用于 db sync 的打包模型、models: () => import(...)）
asc CLI	asc-cli.md	asc、-f、-c、--noEmit、--skipDiag、脚本、“未生成任何内容”/错误会阻止输出、原子写入、db sync 标志（--check、--format）、完整清单规则（“无法加载 N 个已编译模型模块”、ERR_MODULE_NOT_FOUND、嵌套 .as 导入）+ 说明
代码生成	codegen.md	.as → .d.ts/.js、atscript.d.ts 全局 AtscriptMetadata
运行时	runtime.md	defineAnnotatedType、TAtscriptAnnotatedType、forAnnotatedType、序列化、refDepth
验证	validation.md	Validator、ValidatorError、coerceForType、JSON Schema 助手、插件
构建集成	unplugin.md	Vite/Rollup/Rolldown/Webpack/esbuild/Rspack/Farm、HMR、strict、root（从错误的 cwd 发现配置、pnpm -C、未知的 @db.*/@ui.* 注解）、optimizeDeps 对 @atscript/typescript/utils 的预打包（“优化的依赖项已更改，正在重新加载”）、移动/重新定义模型类型后过期的 .as 导入（开发服务器保留旧字段类型，重新加载时提示“需要 string”，但 asc/tsc 通过，watchChange 缓存失效）、.as 重新导出的 dts 打包（tsdown/rolldown-plugin-dts）
Moost 集成	moost-validator.md	Moost 管道（验证 + 参数/查询强制转换）、错误转换
VSCode	vscode.md	扩展、LSP 功能、配置自动发现
插件开发	plugin-development.md	TAtscriptPlugin、AnnotationSpec、render/buildEnd

完整文档：https://atscript.dev。