@atscript/core 0.1.27 → 0.1.28
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/dist/index.cjs +427 -134
- package/dist/index.d.ts +7 -12
- package/dist/index.mjs +427 -134
- package/package.json +9 -3
- package/scripts/setup-skills.js +77 -0
- package/skills/atscript-core/.gitkeep +0 -0
- package/skills/atscript-core/SKILL.md +32 -0
- package/skills/atscript-core/annotations.md +157 -0
- package/skills/atscript-core/core.md +125 -0
- package/skills/atscript-core/plugins.md +206 -0
- package/skills/atscript-core/primitives.md +156 -0
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Primitives Reference — @atscript/core
|
|
2
|
+
|
|
3
|
+
> Built-in primitive types, their extensions, and how to define custom primitives.
|
|
4
|
+
|
|
5
|
+
## Built-in Primitives
|
|
6
|
+
|
|
7
|
+
### `string`
|
|
8
|
+
|
|
9
|
+
Base type for textual data. Extensions accessed via dot notation in `.as` files.
|
|
10
|
+
|
|
11
|
+
| Primitive | Description | Validation |
|
|
12
|
+
| ------------------ | --------------------------------------------- | ----------------------------------- |
|
|
13
|
+
| `string` | Plain text | — |
|
|
14
|
+
| `string.email` | Email address | Pattern: `^[^\s@]+@[^\s@]+\.[^\s@]+$` |
|
|
15
|
+
| `string.phone` | Phone number | Pattern: `^\+?[0-9\s-]{10,15}$` |
|
|
16
|
+
| `string.date` | Date string (multiple formats) | YYYY-MM-DD, MM/DD/YYYY, etc. |
|
|
17
|
+
| `string.isoDate` | ISO 8601 date | UTC and timezone variants |
|
|
18
|
+
| `string.uuid` | UUID | Standard UUID format (case-insensitive) |
|
|
19
|
+
| `string.required` | Non-empty string | `@meta.required` applied |
|
|
20
|
+
|
|
21
|
+
### `number`
|
|
22
|
+
|
|
23
|
+
Base type for numeric data.
|
|
24
|
+
|
|
25
|
+
| Primitive | Description | Validation |
|
|
26
|
+
| -------------------------- | ----------------------------- | ------------------------- |
|
|
27
|
+
| `number` | Any number | — |
|
|
28
|
+
| `number.positive` | >= 0 | `@expect.min 0` |
|
|
29
|
+
| `number.negative` | <= 0 | `@expect.max 0` |
|
|
30
|
+
| `number.int` | Integer | `@expect.int` |
|
|
31
|
+
| `number.int.positive` | Positive integer | `@expect.int` + `@expect.min 0` |
|
|
32
|
+
| `number.int.negative` | Negative integer | `@expect.int` + `@expect.max 0` |
|
|
33
|
+
| `number.single` | Single-precision float | — |
|
|
34
|
+
| `number.double` | Double-precision float | — |
|
|
35
|
+
| `number.timestamp` | Timestamp (integer) | `@expect.int` |
|
|
36
|
+
| `number.timestamp.created` | Auto-set on creation | `@db.default.fn "now"`, tag: `created` |
|
|
37
|
+
| `number.timestamp.updated` | Auto-updated on write | tag: `updated` |
|
|
38
|
+
|
|
39
|
+
### `boolean`
|
|
40
|
+
|
|
41
|
+
| Primitive | Description |
|
|
42
|
+
| ------------------- | ------------------------ |
|
|
43
|
+
| `boolean` | true/false |
|
|
44
|
+
| `boolean.required` | Must be `true` |
|
|
45
|
+
| `boolean.true` | Literal `true` |
|
|
46
|
+
| `boolean.false` | Literal `false` |
|
|
47
|
+
|
|
48
|
+
### Other
|
|
49
|
+
|
|
50
|
+
| Primitive | Description |
|
|
51
|
+
| ----------- | --------------------------------------------------------------------- |
|
|
52
|
+
| `null` | NULL value |
|
|
53
|
+
| `void` | No value |
|
|
54
|
+
| `undefined` | No value (alias for `void`) |
|
|
55
|
+
| `never` | Impossible type |
|
|
56
|
+
| `phantom` | Non-data type. Excluded from validation/schema but discoverable at runtime |
|
|
57
|
+
|
|
58
|
+
## Custom Primitives
|
|
59
|
+
|
|
60
|
+
Define in `atscript.config.ts` under `primitives`:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { defineConfig } from '@atscript/core'
|
|
64
|
+
|
|
65
|
+
export default defineConfig({
|
|
66
|
+
primitives: {
|
|
67
|
+
// Simple: string with validation
|
|
68
|
+
currency: {
|
|
69
|
+
type: 'string',
|
|
70
|
+
tags: ['string'],
|
|
71
|
+
documentation: 'Currency amount (e.g., "12.50")',
|
|
72
|
+
annotations: {
|
|
73
|
+
'expect.pattern': { pattern: '^\\d+\\.\\d{2}$', message: 'Must be format 0.00' },
|
|
74
|
+
},
|
|
75
|
+
},
|
|
76
|
+
|
|
77
|
+
// With extensions: url.https, url.relative
|
|
78
|
+
url: {
|
|
79
|
+
type: 'string',
|
|
80
|
+
tags: ['string'],
|
|
81
|
+
annotations: {
|
|
82
|
+
'expect.pattern': { pattern: '^https?://.+' },
|
|
83
|
+
},
|
|
84
|
+
extensions: {
|
|
85
|
+
https: {
|
|
86
|
+
annotations: { 'expect.pattern': { pattern: '^https://.+' } },
|
|
87
|
+
},
|
|
88
|
+
relative: {
|
|
89
|
+
annotations: { 'expect.pattern': { pattern: '^/.+' } },
|
|
90
|
+
},
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
|
|
94
|
+
// Object-shaped primitive
|
|
95
|
+
point: {
|
|
96
|
+
type: {
|
|
97
|
+
kind: 'object',
|
|
98
|
+
props: { x: 'number', y: 'number' },
|
|
99
|
+
},
|
|
100
|
+
},
|
|
101
|
+
},
|
|
102
|
+
})
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### `TPrimitiveConfig` Options
|
|
106
|
+
|
|
107
|
+
| Field | Type | Description |
|
|
108
|
+
| --------------- | ------------------------------------------- | ---------------------------------------------------- |
|
|
109
|
+
| `type` | `string \| TPrimitiveTypeDef` | Base type: `'string'`, `'number'`, `'boolean'`, `'void'`, `'null'`, `'phantom'`, or complex |
|
|
110
|
+
| `tags` | `string[]` | Semantic tags (available at runtime via `type.tags`) |
|
|
111
|
+
| `documentation` | `string` | Documentation shown in IDE |
|
|
112
|
+
| `annotations` | `Record<string, TPrimitiveAnnotationValue>` | Annotations auto-applied when this primitive is used |
|
|
113
|
+
| `extensions` | `Record<string, Partial<TPrimitiveConfig>>` | Sub-types via dot notation (e.g., `string.email`) |
|
|
114
|
+
|
|
115
|
+
### Primitive Annotations
|
|
116
|
+
|
|
117
|
+
Primitives use a generic `annotations` map to apply any registered annotation. The `applyAnnotations()` method resolves annotation specs, respects `multiple` flags, and maps object values by spec argument names.
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
// Single value — maps to the first argument
|
|
121
|
+
annotations: { 'expect.min': 0 }
|
|
122
|
+
|
|
123
|
+
// Object — maps keys to named arguments
|
|
124
|
+
annotations: { 'expect.pattern': { pattern: '^\\d+$', message: 'Numbers only' } }
|
|
125
|
+
|
|
126
|
+
// Array of objects — for multiple: true + append annotations
|
|
127
|
+
annotations: {
|
|
128
|
+
'expect.pattern': [
|
|
129
|
+
{ pattern: '^\\d{4}-\\d{2}-\\d{2}$', message: 'YYYY-MM-DD' },
|
|
130
|
+
{ pattern: '^\\d{2}/\\d{2}/\\d{4}$', message: 'MM/DD/YYYY' },
|
|
131
|
+
],
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
// Boolean true — flag annotation
|
|
135
|
+
annotations: { 'meta.required': true }
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Usage in `.as` Files
|
|
139
|
+
|
|
140
|
+
```atscript
|
|
141
|
+
export interface User {
|
|
142
|
+
id: string.uuid
|
|
143
|
+
email: string.email
|
|
144
|
+
age: number.int.positive
|
|
145
|
+
createdAt: number.timestamp.created
|
|
146
|
+
bio?: string
|
|
147
|
+
loginLink: phantom // non-data UI element
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Best Practices
|
|
152
|
+
|
|
153
|
+
- Set `tags` to match the base type (e.g., `tags: ['string']`) so runtime type checks work correctly
|
|
154
|
+
- Use `extensions` for sub-types rather than creating separate top-level primitives
|
|
155
|
+
- Use `annotations` to encode validation rules — they flow into validators and JSON Schema automatically
|
|
156
|
+
- Keep `documentation` concise — it appears in IDE hover
|