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 を出力します）。ランタイム用の .js を生成するには -f js を指定します（または、バンドル時に unplugin-atscript に生成させます）。
5. @atscript/typescript/utils はランタイムのエントリーポイントです。@atscript/typescript のデフォルトエクスポートは tsPlugin()（ビルド時のファクトリー）です。
6. コンパイル済みの .as 成果物を import type でインポートしてはいけません。 .as のエクスポートはクラスであり、1つの名前で値と型の両方を持ち、ランタイムで使用されます（.validator()、.metadata、デコレーター、design:paramtypes によるパラメーター型を使った DI）。型のみのインポートでは値が取り除かれ、デコレーターのメタデータが Object を出力し、検証、DI、フォームバインディングが何も通知せずに機能しなくなります。.as ファイルをインポートするプロジェクトでは、型のみのインポートを強制するリンタールール（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	インターフェース／型、ユニオン、交差型、タプル、配列、インポート、パターンプロパティ、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、グローバルな AtscriptMetadata を定義する atscript.d.ts
ランタイム	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.* アノテーション）、@atscript/typescript/utils の optimizeDeps による事前バンドル（「最適化された依存関係が変更されました。再読み込みしています」）、モデルの移動／型変更後の古い .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.