@atscript/typescript 0.1.25 → 0.1.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -0
- package/dist/cli.cjs +140 -46
- package/dist/index.cjs +143 -51
- package/dist/index.d.ts +1 -1
- package/dist/index.mjs +141 -51
- package/dist/utils.cjs +163 -39
- package/dist/utils.d.ts +24 -2
- package/dist/utils.mjs +162 -40
- package/package.json +5 -5
- package/scripts/setup-skills.js +23 -13
- package/skills/atscript-typescript/SKILL.md +22 -14
- package/skills/atscript-typescript/annotations.md +51 -50
- package/skills/atscript-typescript/codegen.md +15 -10
- package/skills/atscript-typescript/core.md +23 -21
- package/skills/atscript-typescript/runtime.md +66 -52
- package/skills/atscript-typescript/syntax.md +31 -31
- package/skills/atscript-typescript/utilities.md +137 -72
- package/skills/atscript-typescript/validation.md +39 -39
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atscript/typescript",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.27",
|
|
4
4
|
"description": "Atscript: typescript-gen support.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"annotations",
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
},
|
|
21
21
|
"bin": {
|
|
22
22
|
"asc": "./cli.cjs",
|
|
23
|
-
"
|
|
23
|
+
"atscript-typescript-skill": "./scripts/setup-skills.js"
|
|
24
24
|
},
|
|
25
25
|
"files": [
|
|
26
26
|
"dist",
|
|
@@ -57,14 +57,14 @@
|
|
|
57
57
|
"./package.json": "./package.json"
|
|
58
58
|
},
|
|
59
59
|
"dependencies": {
|
|
60
|
-
"@moostjs/event-cli": "^0.
|
|
61
|
-
"moost": "^0.
|
|
60
|
+
"@moostjs/event-cli": "^0.6.0",
|
|
61
|
+
"moost": "^0.6.0"
|
|
62
62
|
},
|
|
63
63
|
"devDependencies": {
|
|
64
64
|
"vitest": "3.2.4"
|
|
65
65
|
},
|
|
66
66
|
"peerDependencies": {
|
|
67
|
-
"@atscript/core": "^0.1.
|
|
67
|
+
"@atscript/core": "^0.1.27"
|
|
68
68
|
},
|
|
69
69
|
"build": [
|
|
70
70
|
{},
|
package/scripts/setup-skills.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/* prettier-ignore */
|
|
3
3
|
import fs from 'fs'
|
|
4
|
-
import path from 'path'
|
|
5
4
|
import os from 'os'
|
|
5
|
+
import path from 'path'
|
|
6
6
|
import { fileURLToPath } from 'url'
|
|
7
7
|
|
|
8
8
|
const __dirname = path.dirname(fileURLToPath(import.meta.url))
|
|
@@ -17,17 +17,18 @@ if (!fs.existsSync(SKILL_SRC)) {
|
|
|
17
17
|
}
|
|
18
18
|
|
|
19
19
|
const AGENTS = {
|
|
20
|
-
'Claude Code': { dir: '.claude/skills',
|
|
21
|
-
'Cursor':
|
|
22
|
-
'Windsurf':
|
|
23
|
-
'Codex':
|
|
24
|
-
'OpenCode':
|
|
20
|
+
'Claude Code': { dir: '.claude/skills', global: path.join(os.homedir(), '.claude', 'skills') },
|
|
21
|
+
'Cursor': { dir: '.cursor/skills', global: path.join(os.homedir(), '.cursor', 'skills') },
|
|
22
|
+
'Windsurf': { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
|
|
23
|
+
'Codex': { dir: '.codex/skills', global: path.join(os.homedir(), '.codex', 'skills') },
|
|
24
|
+
'OpenCode': { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
|
|
25
25
|
}
|
|
26
26
|
|
|
27
27
|
const args = process.argv.slice(2)
|
|
28
28
|
const isGlobal = args.includes('--global') || args.includes('-g')
|
|
29
29
|
const isPostinstall = args.includes('--postinstall')
|
|
30
|
-
let installed = 0,
|
|
30
|
+
let installed = 0,
|
|
31
|
+
skipped = 0
|
|
31
32
|
const installedDirs = []
|
|
32
33
|
|
|
33
34
|
for (const [agentName, cfg] of Object.entries(AGENTS)) {
|
|
@@ -36,7 +37,10 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
|
|
|
36
37
|
|
|
37
38
|
// In postinstall mode: silently skip agents that aren't set up globally
|
|
38
39
|
if (isPostinstall || isGlobal) {
|
|
39
|
-
if (!fs.existsSync(agentRootDir)) {
|
|
40
|
+
if (!fs.existsSync(agentRootDir)) {
|
|
41
|
+
skipped++
|
|
42
|
+
continue
|
|
43
|
+
}
|
|
40
44
|
}
|
|
41
45
|
|
|
42
46
|
const dest = path.join(targetBase, SKILL_NAME)
|
|
@@ -55,13 +59,17 @@ for (const [agentName, cfg] of Object.entries(AGENTS)) {
|
|
|
55
59
|
if (!isGlobal && installedDirs.length > 0) {
|
|
56
60
|
const gitignorePath = path.join(process.cwd(), '.gitignore')
|
|
57
61
|
let gitignoreContent = ''
|
|
58
|
-
try {
|
|
62
|
+
try {
|
|
63
|
+
gitignoreContent = fs.readFileSync(gitignorePath, 'utf8')
|
|
64
|
+
} catch {}
|
|
59
65
|
const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
|
|
60
66
|
if (linesToAdd.length > 0) {
|
|
61
67
|
const hasHeader = gitignoreContent.includes('# AI agent skills')
|
|
62
|
-
const block =
|
|
63
|
-
|
|
64
|
-
|
|
68
|
+
const block =
|
|
69
|
+
(gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '') +
|
|
70
|
+
(hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n') +
|
|
71
|
+
linesToAdd.join('\n') +
|
|
72
|
+
'\n'
|
|
65
73
|
fs.appendFileSync(gitignorePath, block)
|
|
66
74
|
console.log(`📝 Added ${linesToAdd.length} entries to .gitignore`)
|
|
67
75
|
}
|
|
@@ -70,7 +78,9 @@ if (!isGlobal && installedDirs.length > 0) {
|
|
|
70
78
|
if (installed === 0 && isPostinstall) {
|
|
71
79
|
// Silence is fine — no agents present, nothing to do
|
|
72
80
|
} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
|
|
73
|
-
console.log(
|
|
81
|
+
console.log(
|
|
82
|
+
'No agent directories detected. Try --global or run without it for project-local install.'
|
|
83
|
+
)
|
|
74
84
|
} else if (installed === 0) {
|
|
75
85
|
console.log('Nothing installed. Run without --global to install project-locally.')
|
|
76
86
|
} else {
|
|
@@ -11,15 +11,15 @@ Atscript is a universal type and metadata description language. `@atscript/types
|
|
|
11
11
|
|
|
12
12
|
Read the domain file that matches the task. Do not load all files — only what you need.
|
|
13
13
|
|
|
14
|
-
| Domain
|
|
15
|
-
|
|
16
|
-
| Setup & configuration
|
|
17
|
-
| `.as` file syntax
|
|
14
|
+
| Domain | File | Load when… |
|
|
15
|
+
| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
16
|
+
| Setup & configuration | [core.md](core.md) | Installing, configuring `atscript.config.ts`, using the `tsPlugin`, running the CLI |
|
|
17
|
+
| `.as` file syntax | [syntax.md](syntax.md) | Writing `.as` files — interfaces, types, imports/exports, property syntax |
|
|
18
18
|
| Annotations & primitives | [annotations.md](annotations.md) | Using built-in `@meta.*`/`@expect.*` annotations, defining custom annotations or primitives |
|
|
19
|
-
| Code generation
|
|
20
|
-
| Runtime type system
|
|
21
|
-
| Validation
|
|
22
|
-
| Utility functions
|
|
19
|
+
| Code generation | [codegen.md](codegen.md) | Understanding what `.d.ts` and `.js` files are generated, `atscript.d.ts` global types |
|
|
20
|
+
| Runtime type system | [runtime.md](runtime.md) | Reading/writing metadata, walking type definitions, understanding `TAtscriptAnnotatedType` |
|
|
21
|
+
| Validation | [validation.md](validation.md) | Validating data, type guards, error handling, custom validator plugins |
|
|
22
|
+
| Utility functions | [utilities.md](utilities.md) | Serialization, flattening, JSON Schema, `createDataFromAnnotatedType`, `forAnnotatedType` |
|
|
23
23
|
|
|
24
24
|
## Quick reference
|
|
25
25
|
|
|
@@ -29,12 +29,20 @@ import tsPlugin from '@atscript/typescript'
|
|
|
29
29
|
|
|
30
30
|
// Runtime utilities (used in app code)
|
|
31
31
|
import {
|
|
32
|
-
defineAnnotatedType,
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
32
|
+
defineAnnotatedType,
|
|
33
|
+
isAnnotatedType,
|
|
34
|
+
annotate,
|
|
35
|
+
Validator,
|
|
36
|
+
ValidatorError,
|
|
37
|
+
buildJsonSchema,
|
|
38
|
+
fromJsonSchema,
|
|
39
|
+
mergeJsonSchemas,
|
|
40
|
+
serializeAnnotatedType,
|
|
41
|
+
deserializeAnnotatedType,
|
|
42
|
+
flattenAnnotatedType,
|
|
43
|
+
createDataFromAnnotatedType,
|
|
44
|
+
forAnnotatedType,
|
|
45
|
+
throwFeatureDisabled,
|
|
38
46
|
} from '@atscript/typescript/utils'
|
|
39
47
|
|
|
40
48
|
// CLI
|
|
@@ -6,36 +6,36 @@
|
|
|
6
6
|
|
|
7
7
|
### `@meta.*` — Metadata Annotations
|
|
8
8
|
|
|
9
|
-
| Annotation
|
|
10
|
-
|
|
11
|
-
| `@meta.label`
|
|
12
|
-
| `@meta.id`
|
|
13
|
-
| `@meta.description`
|
|
14
|
-
| `@meta.documentation` | `text: string`
|
|
15
|
-
| `@meta.placeholder`
|
|
16
|
-
| `@meta.sensitive`
|
|
17
|
-
| `@meta.readonly`
|
|
18
|
-
| `@meta.required`
|
|
19
|
-
| `@meta.default`
|
|
20
|
-
| `@meta.example`
|
|
21
|
-
| `@meta.isKey`
|
|
9
|
+
| Annotation | Arguments | Description |
|
|
10
|
+
| --------------------- | -------------------------- | ------------------------------------------------------------------ |
|
|
11
|
+
| `@meta.label` | `text: string` | Human-readable label for UI, logs, documentation |
|
|
12
|
+
| `@meta.id` | `name?: string` (optional) | Mark field as unique identifier; optional custom name |
|
|
13
|
+
| `@meta.description` | `text: string` | Detailed description of a field or entity |
|
|
14
|
+
| `@meta.documentation` | `text: string` | Multi-line docs (Markdown). Multiple allowed — each appends |
|
|
15
|
+
| `@meta.placeholder` | `text: string` | Placeholder for UI input fields (props/types only) |
|
|
16
|
+
| `@meta.sensitive` | _(none)_ | Mark as sensitive (passwords, API keys). Strips from serialization |
|
|
17
|
+
| `@meta.readonly` | _(none)_ | Mark as read-only |
|
|
18
|
+
| `@meta.required` | `message?: string` | Required field. Strings: non-whitespace. Booleans: must be `true` |
|
|
19
|
+
| `@meta.default` | `value: string` | Default value (strings as-is, others parsed as JSON) |
|
|
20
|
+
| `@meta.example` | `value: string` | Example value (strings as-is, others parsed as JSON) |
|
|
21
|
+
| `@meta.isKey` | _(none)_ | Mark field as key inside array (string/number types only) |
|
|
22
22
|
|
|
23
23
|
### `@expect.*` — Validation Constraints
|
|
24
24
|
|
|
25
|
-
| Annotation
|
|
26
|
-
|
|
27
|
-
| `@expect.minLength` | `length: number`, `message?: string`
|
|
28
|
-
| `@expect.maxLength` | `length: number`, `message?: string`
|
|
29
|
-
| `@expect.min`
|
|
30
|
-
| `@expect.max`
|
|
31
|
-
| `@expect.int`
|
|
32
|
-
| `@expect.pattern`
|
|
25
|
+
| Annotation | Arguments | Applies To | Description |
|
|
26
|
+
| ------------------- | ------------------------------------------------------- | ------------- | ------------------------------------------------------ |
|
|
27
|
+
| `@expect.minLength` | `length: number`, `message?: string` | string, array | Minimum length |
|
|
28
|
+
| `@expect.maxLength` | `length: number`, `message?: string` | string, array | Maximum length |
|
|
29
|
+
| `@expect.min` | `minValue: number`, `message?: string` | number | Minimum value |
|
|
30
|
+
| `@expect.max` | `maxValue: number`, `message?: string` | number | Maximum value |
|
|
31
|
+
| `@expect.int` | _(none)_ | number | Must be integer |
|
|
32
|
+
| `@expect.pattern` | `pattern: string`, `flags?: string`, `message?: string` | string | Regex validation. **Multiple allowed** (all must pass) |
|
|
33
33
|
|
|
34
34
|
### `@emit.*` — Build-time Directives
|
|
35
35
|
|
|
36
|
-
| Annotation
|
|
37
|
-
|
|
38
|
-
| `@emit.jsonSchema` | interface
|
|
36
|
+
| Annotation | Applies To | Description |
|
|
37
|
+
| ------------------ | ---------- | ----------------------------------------------- |
|
|
38
|
+
| `@emit.jsonSchema` | interface | Pre-compute and embed JSON Schema at build time |
|
|
39
39
|
|
|
40
40
|
## Custom Annotations
|
|
41
41
|
|
|
@@ -102,10 +102,10 @@ new AnnotationSpec({
|
|
|
102
102
|
],
|
|
103
103
|
|
|
104
104
|
// Allow multiple instances on the same target
|
|
105
|
-
multiple: true,
|
|
105
|
+
multiple: true, // default: false
|
|
106
106
|
|
|
107
107
|
// How duplicates merge: 'replace' (last wins) or 'append' (collect into array)
|
|
108
|
-
mergeStrategy: 'append',
|
|
108
|
+
mergeStrategy: 'append', // default: 'replace'
|
|
109
109
|
|
|
110
110
|
// Human-readable description
|
|
111
111
|
description: 'What this annotation does',
|
|
@@ -124,13 +124,13 @@ new AnnotationSpec({
|
|
|
124
124
|
|
|
125
125
|
Each argument accepts:
|
|
126
126
|
|
|
127
|
-
| Field
|
|
128
|
-
|
|
129
|
-
| `name`
|
|
130
|
-
| `type`
|
|
131
|
-
| `optional`
|
|
132
|
-
| `description` | `string`
|
|
133
|
-
| `values`
|
|
127
|
+
| Field | Type | Description |
|
|
128
|
+
| ------------- | ----------------------------------- | ------------------------------------------- |
|
|
129
|
+
| `name` | `string` | Argument name (used in metadata object key) |
|
|
130
|
+
| `type` | `'string' \| 'number' \| 'boolean'` | Expected type |
|
|
131
|
+
| `optional` | `boolean` | Whether the argument can be omitted |
|
|
132
|
+
| `description` | `string` | Human-readable description |
|
|
133
|
+
| `values` | `string[]` | Allowed values (enum-like constraint) |
|
|
134
134
|
|
|
135
135
|
### How Annotations Map to Runtime Metadata
|
|
136
136
|
|
|
@@ -140,6 +140,7 @@ Each argument accepts:
|
|
|
140
140
|
- **`multiple: true`** → metadata value is an array
|
|
141
141
|
|
|
142
142
|
Example: `@api.endpoint "/users" "GET"` becomes:
|
|
143
|
+
|
|
143
144
|
```ts
|
|
144
145
|
metadata.get('api.endpoint') // → { path: "/users", method: "GET" }
|
|
145
146
|
```
|
|
@@ -200,26 +201,26 @@ export default defineConfig({
|
|
|
200
201
|
|
|
201
202
|
### `TPrimitiveConfig` Options
|
|
202
203
|
|
|
203
|
-
| Field
|
|
204
|
-
|
|
205
|
-
| `type`
|
|
206
|
-
| `tags`
|
|
207
|
-
| `documentation` | `string`
|
|
208
|
-
| `expect`
|
|
209
|
-
| `extensions`
|
|
204
|
+
| Field | Type | Description |
|
|
205
|
+
| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
206
|
+
| `type` | `TPrimitiveTypeDef` | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex type |
|
|
207
|
+
| `tags` | `string[]` | Custom tags for categorization |
|
|
208
|
+
| `documentation` | `string` | Documentation string |
|
|
209
|
+
| `expect` | object | Built-in validation constraints |
|
|
210
|
+
| `extensions` | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types accessible via dot notation |
|
|
210
211
|
|
|
211
212
|
### `expect` Validation on Primitives
|
|
212
213
|
|
|
213
|
-
| Field
|
|
214
|
-
|
|
215
|
-
| `min`
|
|
216
|
-
| `max`
|
|
217
|
-
| `int`
|
|
218
|
-
| `minLength` | string, array
|
|
219
|
-
| `maxLength` | string, array
|
|
220
|
-
| `pattern`
|
|
221
|
-
| `required`
|
|
222
|
-
| `message`
|
|
214
|
+
| Field | Applies To | Description |
|
|
215
|
+
| ----------- | --------------- | -------------------------------- |
|
|
216
|
+
| `min` | number | Minimum value |
|
|
217
|
+
| `max` | number | Maximum value |
|
|
218
|
+
| `int` | number | Must be integer |
|
|
219
|
+
| `minLength` | string, array | Minimum length |
|
|
220
|
+
| `maxLength` | string, array | Maximum length |
|
|
221
|
+
| `pattern` | string | Regex pattern(s) |
|
|
222
|
+
| `required` | string, boolean | Non-empty / must be true |
|
|
223
|
+
| `message` | any | Custom error message for pattern |
|
|
223
224
|
|
|
224
225
|
### Usage in `.as` Files
|
|
225
226
|
|
|
@@ -6,10 +6,10 @@
|
|
|
6
6
|
|
|
7
7
|
Each `.as` file produces two outputs:
|
|
8
8
|
|
|
9
|
-
| Output
|
|
10
|
-
|
|
9
|
+
| Output | Generated By | Contains |
|
|
10
|
+
| ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
11
11
|
| `*.as.d.ts` | `npx asc -f dts` or build tool | TypeScript type declarations — interfaces become `declare class` with static type/metadata/validator |
|
|
12
|
-
| `*.as.js`
|
|
12
|
+
| `*.as.js` | Build tool (unplugin-atscript) | Runtime module — classes with full type definitions, metadata maps, and validator factories |
|
|
13
13
|
|
|
14
14
|
## `.d.ts` Output
|
|
15
15
|
|
|
@@ -31,9 +31,12 @@ Generates `user.as.d.ts`:
|
|
|
31
31
|
|
|
32
32
|
```ts
|
|
33
33
|
import type {
|
|
34
|
-
TAtscriptTypeObject,
|
|
35
|
-
|
|
36
|
-
|
|
34
|
+
TAtscriptTypeObject,
|
|
35
|
+
TAtscriptAnnotatedType,
|
|
36
|
+
TMetadataMap,
|
|
37
|
+
Validator,
|
|
38
|
+
TValidatorOptions,
|
|
39
|
+
} from '@atscript/typescript/utils'
|
|
37
40
|
|
|
38
41
|
export declare class User {
|
|
39
42
|
name: string
|
|
@@ -48,7 +51,7 @@ export declare class User {
|
|
|
48
51
|
static toExampleData?: () => any
|
|
49
52
|
}
|
|
50
53
|
|
|
51
|
-
export type Status =
|
|
54
|
+
export type Status = 'active' | 'inactive'
|
|
52
55
|
declare namespace Status {
|
|
53
56
|
const __is_atscript_annotated_type: true
|
|
54
57
|
const type: TAtscriptTypeComplex<Status>
|
|
@@ -60,6 +63,7 @@ declare namespace Status {
|
|
|
60
63
|
```
|
|
61
64
|
|
|
62
65
|
Key points:
|
|
66
|
+
|
|
63
67
|
- **Interfaces** become `declare class` — so they work both as types and runtime values
|
|
64
68
|
- **Types** become a `type` alias + a companion `namespace` with runtime statics
|
|
65
69
|
- Each has `type`, `metadata`, `validator()`, `toJsonSchema()`, and `toExampleData()` statics
|
|
@@ -70,6 +74,7 @@ Key points:
|
|
|
70
74
|
The JS module creates actual classes with runtime type definitions and metadata:
|
|
71
75
|
|
|
72
76
|
- Uses `defineAnnotatedType` (aliased as `$`) to build the type tree
|
|
77
|
+
- Each class gets a `static id` field with the stable type name (collision-safe via `__N` suffix)
|
|
73
78
|
- Populates metadata maps with all annotation values
|
|
74
79
|
- Wires up `validator()` and `toJsonSchema()` methods
|
|
75
80
|
- When `exampleData: true`, adds `toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })` (aliased as `$e`)
|
|
@@ -91,7 +96,7 @@ declare global {
|
|
|
91
96
|
'expect.minLength': { length: number; message?: string }
|
|
92
97
|
// ... all annotations used in your project
|
|
93
98
|
}
|
|
94
|
-
type AtscriptPrimitiveTags =
|
|
99
|
+
type AtscriptPrimitiveTags = 'string' | 'number' | 'boolean' | 'null'
|
|
95
100
|
}
|
|
96
101
|
```
|
|
97
102
|
|
|
@@ -107,8 +112,8 @@ This file is **auto-generated** based on the annotations actually used across al
|
|
|
107
112
|
|
|
108
113
|
Generated files use these import paths:
|
|
109
114
|
|
|
110
|
-
| Import
|
|
111
|
-
|
|
115
|
+
| Import | Source |
|
|
116
|
+
| ---------------------------- | ------------------------------------------------- |
|
|
112
117
|
| `@atscript/typescript/utils` | Runtime utilities (used by generated `.js` files) |
|
|
113
118
|
|
|
114
119
|
When importing from `.as` files in your TypeScript code:
|
|
@@ -51,18 +51,18 @@ export default defineConfig({
|
|
|
51
51
|
|
|
52
52
|
### `TAtscriptConfig` Fields
|
|
53
53
|
|
|
54
|
-
| Field
|
|
55
|
-
|
|
56
|
-
| `rootDir`
|
|
57
|
-
| `entries`
|
|
58
|
-
| `include`
|
|
59
|
-
| `exclude`
|
|
60
|
-
| `plugins`
|
|
61
|
-
| `primitives`
|
|
62
|
-
| `annotations`
|
|
63
|
-
| `unknownAnnotation` | `'allow' \| 'warn' \| 'error'`
|
|
64
|
-
| `format`
|
|
65
|
-
| `outDir`
|
|
54
|
+
| Field | Type | Description |
|
|
55
|
+
| ------------------- | ---------------------------------- | ---------------------------------------- |
|
|
56
|
+
| `rootDir` | `string` | Root directory for resolving files |
|
|
57
|
+
| `entries` | `string[]` | Entry point globs for `.as` files |
|
|
58
|
+
| `include` | `string[]` | Include globs |
|
|
59
|
+
| `exclude` | `string[]` | Exclude globs |
|
|
60
|
+
| `plugins` | `TAtscriptPlugin[]` | Build plugins (e.g. `tsPlugin()`) |
|
|
61
|
+
| `primitives` | `Record<string, TPrimitiveConfig>` | Custom primitive type definitions |
|
|
62
|
+
| `annotations` | `TAnnotationsTree` | Custom annotation definitions |
|
|
63
|
+
| `unknownAnnotation` | `'allow' \| 'warn' \| 'error'` | Unknown annotation handling |
|
|
64
|
+
| `format` | `string` | Output format (set by CLI or build tool) |
|
|
65
|
+
| `outDir` | `string` | Output directory |
|
|
66
66
|
|
|
67
67
|
## TypeScript Plugin Options
|
|
68
68
|
|
|
@@ -84,7 +84,8 @@ Individual interfaces can override the JSON Schema setting with `@emit.jsonSchem
|
|
|
84
84
|
### `exampleData`
|
|
85
85
|
|
|
86
86
|
Controls whether `toExampleData()` is generated on output classes:
|
|
87
|
-
|
|
87
|
+
|
|
88
|
+
- `false` _(default)_ — method is not rendered in `.js`; `.d.ts` marks it as optional + `@deprecated`
|
|
88
89
|
- `true` — each class gets `static toExampleData()` that calls `createDataFromAnnotatedType(this, { mode: 'example' })`, creating a new example data object on each call (no caching)
|
|
89
90
|
|
|
90
91
|
## Build Tool Integration
|
|
@@ -96,7 +97,7 @@ Controls whether `toExampleData()` is generated on output classes:
|
|
|
96
97
|
import atscript from 'unplugin-atscript/vite'
|
|
97
98
|
|
|
98
99
|
export default {
|
|
99
|
-
plugins: [atscript()]
|
|
100
|
+
plugins: [atscript()],
|
|
100
101
|
}
|
|
101
102
|
```
|
|
102
103
|
|
|
@@ -106,7 +107,7 @@ export default {
|
|
|
106
107
|
// webpack.config.js
|
|
107
108
|
const atscript = require('unplugin-atscript/webpack')
|
|
108
109
|
module.exports = {
|
|
109
|
-
plugins: [atscript()]
|
|
110
|
+
plugins: [atscript()],
|
|
110
111
|
}
|
|
111
112
|
```
|
|
112
113
|
|
|
@@ -136,6 +137,7 @@ npx asc --skipDiag
|
|
|
136
137
|
### Why run `npx asc -f dts`?
|
|
137
138
|
|
|
138
139
|
This generates two things:
|
|
140
|
+
|
|
139
141
|
1. **`*.as.d.ts`** files next to each `.as` file — TypeScript type declarations for all interfaces/types
|
|
140
142
|
2. **`atscript.d.ts`** in the project root — global type declarations for `AtscriptMetadata` and `AtscriptPrimitiveTags`
|
|
141
143
|
|
|
@@ -143,12 +145,12 @@ The `atscript.d.ts` file is **crucial for type safety** — it tells TypeScript
|
|
|
143
145
|
|
|
144
146
|
### CLI Options
|
|
145
147
|
|
|
146
|
-
| Option
|
|
147
|
-
|
|
148
|
-
| `--config <path>` | `-c`
|
|
149
|
-
| `--format <fmt>`
|
|
150
|
-
| `--noEmit`
|
|
151
|
-
| `--skipDiag`
|
|
148
|
+
| Option | Short | Description |
|
|
149
|
+
| ----------------- | ----- | ----------------------------- |
|
|
150
|
+
| `--config <path>` | `-c` | Path to config file |
|
|
151
|
+
| `--format <fmt>` | `-f` | Output format: `dts`, `js` |
|
|
152
|
+
| `--noEmit` | | Only check for errors |
|
|
153
|
+
| `--skipDiag` | | Skip diagnostics, always emit |
|
|
152
154
|
|
|
153
155
|
## Project Structure Example
|
|
154
156
|
|