refactor: enforce mandatory brackets for composite values

Implements Phase 1 and 2 of the syntax rework plan:
- Brackets `[]` are now mandatory for all tuple and array values.
- Removed the `[Type][]` array syntax; arrays now only use `Type[]`.
- `[single]` is now strictly a 1-tuple rather than an array.
- Updated documentation and test fixtures to reflect these breaking
  changes.
This commit is contained in:
2026-08-06 09:19:39 +08:00
parent 7db0742f50
commit c969c7f6fc
11 changed files with 89 additions and 164 deletions
+9 -23
View File
@@ -35,14 +35,9 @@ numberSchema.validator(name); // false
```typescript
const tupleSchema = defineSchema('[string; number; boolean]');
// With brackets
const value1 = tupleSchema.parse('[hello; 42; true]');
// ["hello", 42, true]
// Without brackets (outermost brackets are optional)
const value2 = tupleSchema.parse('hello; 42; true');
// ["hello", 42, true]
tupleSchema.validator(value1); // true
tupleSchema.validator(['a', 'b', true]); // false (second element should be number)
```
@@ -50,16 +45,11 @@ tupleSchema.validator(['a', 'b', true]); // false (second element should be num
### Arrays
```typescript
// Array syntax: Type[] or [Type][]
// Array syntax: Type[]
const stringArray = defineSchema('string[]');
const numberArray = defineSchema('[number][]');
const numberArray = defineSchema('number[]');
// With brackets
const names1 = stringArray.parse('[alice; bob; charlie]');
// ["alice", "bob", "charlie"]
// Without brackets (outermost brackets are optional)
const names2 = stringArray.parse('alice; bob; charlie');
const names = stringArray.parse('[alice; bob; charlie]');
// ["alice", "bob", "charlie"]
const numbers = numberArray.parse('[1; 2; 3; 4; 5]');
@@ -71,12 +61,7 @@ const numbers = numberArray.parse('[1; 2; 3; 4; 5]');
```typescript
const schema = defineSchema('[string; number][]');
// With outer brackets
const data1 = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
// [["a", 1], ["b", 2], ["c", 3]]
// Without outer brackets
const data2 = schema.parse('[a; 1]; [b; 2]; [c; 3]');
const data = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
// [["a", 1], ["b", 2], ["c", 3]]
```
@@ -155,9 +140,9 @@ The following TypeScript types are exported:
| Float | `float` | `3.14` |
| Number | `number` | `42` or `3.14` |
| Boolean | `boolean` | `true` or `false` |
| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` or `hello; 42; true` |
| Array | `Type[]` or `[Type][]` | `[1; 2; 3]` or `1; 2; 3` |
| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` or `[a; 1]; [b; 2]` |
| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` |
| Array | `Type[]` | `[1; 2; 3]` |
| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` |
| Union | `Type1 \| Type2` | `hello` or `42` (matches first valid member) |
| String Literal | `'on' \| 'off'` or `"red"` | `on` or `off` |
| Reference | `@tablename` or `@tablename[]` | (resolved at CSV load time) |
@@ -166,7 +151,8 @@ The following TypeScript types are exported:
## Notes
- Semicolons `;` are used as separators instead of commas `,`
- Outermost brackets `[]` are optional for tuple and array values
- Tuple and array values **must** be wrapped in brackets `[]` (e.g. `[a; b]`)
- `[single]` is a 1-tuple, not an array — use `Type[]` for arrays
- Special characters can be escaped with backslash: `\;`, `\[`, `\]`, `\\`
- Empty arrays/tuples are not allowed
- For CSV loading with reference resolution, see [csv-loader.md](./csv-loader.md)