chore: bump version to 2.0.0

Extract `loadReferenceTableData` to separate the raw file loading
logic from the primary key lookup construction. This prevents
unnecessary Map creation during reverse reference resolution.

AGENTS.md

@@ -13,12 +13,12 @@ No linter or formatter is configured. No CI pipeline exists.
 
 Single-package TypeScript library with two runtime entry points:
 
-- **`inline-schema`** (`src/index.ts`) — core schema parser, value parser, and validator
+- **`typed-csv`** (`src/index.ts`) — core schema parser, value parser, and validator
   - `src/parser.ts` — `parseSchema()` turns schema strings into AST (`Schema` type)
   - `src/validator.ts` — `parseValue()` and `createValidator()` operate on the AST
   - `src/types.ts` — union type `Schema = Primitive | Tuple | Array | Reference | StringLiteral | Union`
 
-- **`inline-schema/csv-loader`** (`src/csv-loader/loader.ts`) — CSV loader with `@table` reference resolution
+- **`typed-csv/csv-loader`** (`src/csv-loader/loader.ts`) — CSV loader with `@table` reference resolution
   - `loader.ts` — `parseCsv()` (eager resolution) and `csvToModule()` (accessor-based output with lazy resolution); `resolveReferences: false` mode stores IDs instead of resolved objects
   - `webpack.ts`, `rollup.ts`, `esbuild.ts` — bundler plugin wrappers around `csvToModule`
 
@@ -28,6 +28,7 @@ Build produces separate bundles per entry point (see `tsup.config.ts`). The csv-
 
 - Schema syntax uses **semicolons** (`;`) as separators, not commas
 - Unknown identifiers throw a `ParseError` — only recognized keywords (`string`, `number`, `int`, `float`, `boolean`) and string literals (`"on"`, `'off'`) are valid types
+- 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
 - `@tablename` / `@tablename[]` are reference schemas resolved at CSV load time
 - `csvToModule()` emits accessor functions (`getData()`) for tables with references, and static JSON for tables without; bundler loaders all use `csvToModule`
 - `parseCsv({ resolveReferences: false })` stores reference IDs instead of resolved objects — used by `csvToModule` to emit import-based lazy resolution
@@ -37,6 +38,6 @@ Build produces separate bundles per entry point (see `tsup.config.ts`). The csv-
 
 - **Circular references** between CSV tables are supported in `csvToModule` output via accessor-based lazy resolution. `parseCsv()` with `resolveReferences: true` (default) still detects and throws on circular references via an in-progress loading set.
 - **Run `npm run typecheck` before committing** to catch type errors.
-- **Union member ordering matters** — `parseValue` tries union members in order; the first one that parses wins. This affects references in unions (e.g., `@users[] | string` will try `@users[]` first).
+- **Union member ordering** — In unions containing references, **reference members are tried before non-reference members** (regardless of author order), so `@users | string` resolves `1` to the user object and falls back to a plain string only when the reference doesn't match. `parseValue` (no references) still tries members in author order; the first that parses wins.
 - **csv-parse quote handling** — Double-quoted schema values like `"active" | "inactive"` in CSV rows confuse the csv-parse library. Use single-quoted string literals (`'on' | 'off'`) or unquoted identifiers in the schema row of CSV data when possible.
 - **Module imports use `.js` extension** — source files import from `../index.js` etc. (ESM convention), not `../index.ts`.

README.md

@@ -1,11 +1,11 @@
-# inline-schema
+# typed-csv
 
-A TypeScript library for parsing and validating inline schemas with a TypeScript-like syntax using `;` instead of `,`.
+A TypeScript library for typed CSV data with inline schema validation using a TypeScript-like syntax with `;` instead of `,`.
 
 ## Installation
 
 ```bash
-npm install inline-schema
+npm install typed-csv
 ```
 
 ## Usage
@@ -13,7 +13,7 @@ npm install inline-schema
 ### Basic Example
 
 ```typescript
-import { defineSchema } from 'inline-schema';
+import { defineSchema } from 'typed-csv';
 
 // Define a schema
 const stringSchema = defineSchema('string');
@@ -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 names = stringArray.parse('[alice; bob; charlie]');
-const names1 = stringArray.parse('[alice; bob; charlie]');
-// ["alice", "bob", "charlie"]
-
-// Without brackets (outermost brackets are optional)
-const names2 = 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 data = schema.parse('[[a; 1]; [b; 2]; [c; 3]]');
-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]');
 // [["a", 1], ["b", 2], ["c", 3]]
 ```
 
@@ -128,27 +113,63 @@ Parses a value string according to the given schema.
 
 Creates a validation function for the given schema.
 
+### `schemaToTypeString(schema: Schema): string`
+
+Converts a schema AST back to a human-readable type string.
+
+### `ParseError`
+
+Error class thrown for invalid schema syntax.
+
+### Types
+
+The following TypeScript types are exported:
+
+- `Schema` — union of all schema AST node types
+- `ParsedSchema` — the return type of `defineSchema()`
+- `PrimitiveSchema`, `TupleSchema`, `ArraySchema` — AST node types
+- `ReferenceSchema`, `ReverseReferenceSchema` — reference AST node types
+- `StringLiteralSchema`, `UnionSchema` — literal and union AST node types
+
 ## Schema Syntax
 
 | Type | Schema | Example Value |
 |------|--------|---------------|
 | String | `string` or `identifier` | `hello` |
-| Number | `number` | `42` |
+| Int | `int` | `42` |
+| Float | `float` | `3.14` |
+| Number | `number` | `42` or `3.14` |
+
+> **Note:** `int`, `float`, and `number` all collapse to the `number` type in generated TypeScript declarations (`schemaToTypeString`). The distinction is preserved at parse time — `int` rejects non-integer values while `float`/`number` accept them.
 | Boolean | `boolean` | `true` or `false` |
-| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` or `hello; 42; true` |
+| Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` |
-| Array | `Type[]` or `[Type][]` | `[1; 2; 3]` or `1; 2; 3` |
+| Array | `Type[]` | `[1; 2; 3]` |
-| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` or `[a; 1]; [b; 2]` |
+| Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` |
+| Union | `Type1 \| Type2` | `hello` or `42` (reference members tried first) |
+| String Literal | `'on' \| 'off'` or `"red"` | `on` or `off` |
+| Reference | `@tablename` or `@tablename[]` | (resolved at CSV load time) |
+| Reverse Reference | `~tablename(fk)` | (resolved at CSV load time) |
 
 ## 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
+- In a union, **reference members are tried before non-reference members** (e.g. `@users | string` resolves `1` to the user object, falling back to a plain string when the reference doesn't match)
 - Special characters can be escaped with backslash: `\;`, `\[`, `\]`, `\\`
 - Empty arrays/tuples are not allowed
+- In CSV schema rows, double-quoted string literals like `"active" | "inactive"` are handled automatically by the loader; avoid commas inside string literals (use single-quoted literals like `'a,b'` for those)
+- For CSV loading with reference resolution, see [csv-loader.md](./csv-loader.md)
 
-## CSV Loader
+## Migration from 1.x
 
-For loading CSV files with schema validation in rspack, see [csv-loader.md](./csv-loader.md).
+Version 2.0.0 introduces breaking changes to the schema DSL:
+
+1. **Composite values must be fully bracketed.** Tuple and array values now always require `[]` — `[a; 1]; [b; 2]` is no longer accepted; write `[[a; 1]; [b; 2]]`.
+2. **The `[Type][]` array form is removed.** Use `Type[]` (e.g. `[string; number][]` instead of `[[string; number]][]`).
+3. **`[single]` is now a 1-tuple, not an array.** Use `Type[]` for single-element arrays.
+4. **Union resolution prefers reference members.** In a union containing references, reference members are tried before non-reference members regardless of author order (see the notes above).
+5. **Schema cells may be fully quoted.** Double-quoted string literals like `"active" | "inactive"` in a CSV schema row are handled automatically by the loader.
 
 ```javascript
 // rspack.config.js
@@ -157,7 +178,7 @@ module.exports = {
     rules: [
       {
         test: /\.schema\.csv$/,
-        use: 'inline-schema/csv-loader',
+        use: 'typed-csv/csv-loader',
       },
     ],
   },

csv-loader.md

@@ -1,18 +1,18 @@
-# inline-schema/csv-loader
+# typed-csv/csv-loader
 
-A rspack/rollup loader for CSV files that uses inline-schema for type validation.
+A bundler loader (rspack/webpack/rollup/esbuild) for CSV files that uses typed-csv for type validation and cross-table reference resolution.
 
 ## Installation
 
 ```bash
-npm install inline-schema
+npm install typed-csv
 ```
 
 ## Usage
 
 The loader expects:
 - **First row**: Property names (headers)
-- **Second row**: Inline-schema definitions for each property
+- **Second row**: typed-csv schema definitions for each property
 - **Remaining rows**: Data values
 
 ### Example CSV
@@ -35,7 +35,7 @@ module.exports = {
       {
         test: /\.schema\.csv$/,
         use: {
-          loader: 'inline-schema/csv-loader',
+          loader: 'typed-csv/csv-loader',
           options: {
             delimiter: ',',
             quote: '"',
@@ -60,7 +60,7 @@ module.exports = {
 
 ```typescript
 import { defineConfig } from 'vite';
-import { csvLoader } from 'inline-schema/csv-loader/rollup';
+import { csvLoader } from 'typed-csv/csv-loader/rollup';
 
 export default defineConfig({
   plugins: [
@@ -85,7 +85,7 @@ export default defineConfig({
 
 ```typescript
 import { defineConfig } from 'tsup';
-import { csvLoader } from 'inline-schema/csv-loader/rollup';
+import { csvLoader } from 'typed-csv/csv-loader/rollup';
 
 export default defineConfig({
   entry: ['src/index.ts'],
@@ -139,16 +139,26 @@ import data from './data.csv';
 
 ## Schema Syntax
 
-Uses [inline-schema](https://github.com/your-repo/inline-schema) syntax:
+Uses [typed-csv](https://github.com/your-repo/typed-csv) syntax:
 
 | Type | Schema | Example |
 |------|--------|---------|
 | String | `string` | `hello` |
 | Number | `number` | `42` |
 | Boolean | `boolean` | `true` |
-| Array | `string[]` or `[string][]` | `[a; b; c]` |
+| Array | `string[]` | `[a; b; c]` |
 | Tuple | `[string; number]` | `[hello; 42]` |
 
+> **Note:** `int` and `float` are accepted in schemas and validated at parse time, but both collapse to `number` in generated type declarations.
+
+## Migration from 1.x
+
+- Composite values must be fully bracketed: `[[a; 1]; [b; 2]]`, not `[a; 1]; [b; 2]`.
+- The `[Type][]` array form is removed — use `Type[]`.
+- `[single]` is a 1-tuple, not an array.
+- In unions containing references, reference members are tried first.
+- Double-quoted string literals (`"active" | "inactive"`) in a schema row are handled automatically.
+
 ## License
 
 ISC

docs/syntax-rework-plan.md

@@ -0,0 +1,106 @@
+# Implementation Plan: Syntax Clarity & Parser Robustness
+
+Status: **In progress — Phases 1, 2, 3 & 4 applied** (Phases 5–6 not yet done)
+
+## Goals
+
+1. Eliminate the backtracking heuristics in the value parser by making the value grammar context-free.
+2. Remove redundant/ambiguous syntax forms.
+3. Make union resolution deterministic and structural (not error-message-driven).
+4. Address the `csv-parse` quote conflict.
+5. Keep the `;` separator (forced by CSV constraints — not the source of ambiguity).
+
+All changes are **breaking** to the DSL → bump to `2.0.0`, update README + `csv-loader.md`, add a migration note.
+
+---
+
+## Phase 1 — Mandatory brackets for composite values ✅ Applied
+
+**Files:** `src/value-parser.ts`, `src/index.test.ts`, `src/csv-loader/reference-resolver.ts`
+
+- Removed the `allowOmitBrackets` parameter from `parseValue`, `parseTupleValue`, `parseArrayValue`.
+- Deleted the `elementIsTupleOrArray` disambiguation block and all `savedPos` restore logic in `parseArrayValue`.
+- Dropped the `allowOmitBrackets = schema.type === "tuple" || "array"` special case in top-level `parseValue` — brackets are always required.
+- Array references (`@table[]` values) now also require brackets, for consistency.
+- Values must now be fully bracketed: `[a; 1]; [b; 2]` (no more `[a; 1]; [b; 2]` without outer brackets).
+
+**Decision:** Full mandatory brackets (no carve-out).
+
+---
+
+## Phase 2 — Single array form `Type[]` ✅ Applied
+
+**Files:** `src/parser.ts`, `src/index.test.ts`
+
+- Removed the `[Type][]` array syntax from `parseSchemaInternal`. Kept only `Type[]`.
+- `[string]` is now a **1-tuple** (previously it collapsed to an array). The tuple branch always returns `{ type: "tuple", elements }`.
+- Updated `schemaToTypeString` in `src/type-utils.ts` — the `array` case no longer special-cases tuple elements; arrays are always `elementType[]` (kept the `(union)[]` paren wrapping).
+
+**Tests updated:** `index.test.ts` bracket-optional tests, `encounter.csv` / `enemy_intents.csv` fixtures, and `parseCsv-typeDeclarations.test.ts` array-of-tuple values.
+
+---
+
+## Phase 3 — Deterministic union resolution ✅ Applied
+
+**Files:** `src/csv-loader/reference-resolver.ts`, `src/csv-loader/module-gen.ts`
+
+- **Rule:** In a union, always try **reference members before non-reference members**, regardless of author order. This makes fallback structural instead of error-message-driven.
+- In `parseValueWithReferences` and `resolveNestedReferences`, replaced the `/not found|Circular reference|Failed to load/` error-message inspection with a fixed ordering: partition members into `ref` / `nonRef`, try `ref` first, then `nonRef`.
+- `module-gen.ts` `generateSchemaResolutionCode` already emitted reference-first (`lookup.get(...) ?? value`), so runtime now matches generated code.
+- **Documented the rule** in README and AGENTS.md.
+
+**Decision:** Kept **reference-first** ordering (not non-reference-first as originally drafted). Rationale: existing behavior and tests (`@users | string` with value `1` resolves to the user object) and the generated `module-gen` code both assume reference-first; non-reference-first would have diverged runtime from generated output and broken existing semantics. The plan's real goal — removing the error-message regex — is achieved.
+
+---
+
+## Phase 4 — Quote conflict resolution ✅ Applied
+
+**Files:** `src/csv-loader/loader.ts`, `src/csv-loader/tests/parseCsv-basic.test.ts`, README, `csv-loader.md`
+
+- Added `escapeSchemaRowQuotes()` in `loader.ts`: the schema row (2nd non-empty line) is split on the delimiter, and any cell containing the quote char has its inner quotes escaped and is wrapped in quotes before `csv-parse` runs.
+- This lets users write `"active" | "inactive"` naturally in a schema row — previously csv-parse threw `Invalid Closing Quote`.
+- Single-quoted literals (`'on' | 'off'`) are untouched (no `"` present).
+- Added a test in `parseCsv-basic.test.ts`.
+
+**Decision:** Implemented option (b) — loader-side escaping of the schema row. This fixes the root cause (schema cells containing `"` break csv-parse) without redesigning the literal syntax.
+
+**Known limitation (pre-existing, out of scope):** a comma inside a string literal (e.g. `"a,b"`) is ambiguous with the CSV delimiter and still fails — use single-quoted literals (`'a,b'`) for those, or a non-comma delimiter.
+
+---
+
+## Phase 5 — Cleanup & consistency
+
+**Files:** `src/csv-loader/reference-resolver.ts`, `src/csv-loader/loader.ts`, `src/csv-loader/module-gen.ts`
+
+- **Reverse-reference performance:** `resolveReverseReference` does `refTable.filter(...)` per row. Build a `Map<fk, rows[]>` lookup once per referenced table (mirroring what `module-gen.ts` already generates) and reuse it. Cache the lookup alongside the parsed table in `referenceTableCache`.
+- **Remove the `,` stop-character in `parseReferenceValue`** (value parser has a `,` stop char the schema parser doesn't — drift). Make reference ID parsing consistent with the rest of the value grammar.
+- **`int`/`float`/`number` → `number`:** document the collapse in README (type-level collapse is intentional; parse-time distinction remains).
+
+---
+
+## Phase 6 — Docs & migration
+
+**Files:** `README.md`, `csv-loader.md`, `AGENTS.md`
+
+- Update all syntax tables and examples for mandatory brackets + single array form.
+- Add a **Migration section** listing the breaking changes:
+  1. Composite values must be fully bracketed.
+  2. `[Type][]` array form removed — use `Type[]`.
+  3. `[single]` is now a 1-tuple, not an array.
+  4. Union resolution now prefers reference members (tried before non-reference members).
+  5. (If Phase 4b) schema cells may be fully quoted.
+- Update `AGENTS.md` gotchas: union ordering rule, quote handling.
+
+---
+
+## Validation
+
+- `npm run typecheck`
+- `npm run test` (update `src/index.test.ts`, `src/csv-loader/*.test.ts` first)
+- Manually verify the integration fixture (`user_rev.csv` / `order_rev.csv`) still resolves.
+
+---
+
+## Suggested execution order
+
+Phases 1 → 2 are tightly coupled (both touch bracket parsing) — do them together. Phase 3 is independent. Phase 4 is independent. Phases 5–6 are cleanup/docs and can go last.

package.json

@@ -1,6 +1,6 @@
 {
-  "name": "inline-schema",
+  "name": "typed-csv",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -49,7 +49,7 @@
   ],
   "author": "",
   "license": "ISC",
-  "description": "A TypeScript library for parsing and validating inline schemas",
+  "description": "A TypeScript library for typed CSV data with inline schema validation",
   "dependencies": {
     "csv-parse": "^5.5.6"
   },

src/csv-loader/esbuild.ts

@@ -39,7 +39,7 @@ function matchesPattern(
 }
 
 /**
- * Esbuild plugin for loading CSV files with inline-schema validation.
+ * Esbuild plugin for loading CSV files with typed-csv validation.
  */
 export function csvLoader(options: CsvEsbuildOptions = {}): Plugin {
   const {
@@ -54,12 +54,12 @@ export function csvLoader(options: CsvEsbuildOptions = {}): Plugin {
   const includeFilter = createFilter(include);
 
   return {
-    name: "inline-schema-csv",
+    name: "typed-csv",
 
     setup(build) {
       build.onLoad({ filter: includeFilter }, async (args) => {
         // Check exclude pattern
-        if (exclude && !matchesPattern(args.path, exclude)) {
+        if (exclude && matchesPattern(args.path, exclude)) {
           return null;
         }
 

src/csv-loader/fixtures/encounter.csv

@@ -0,0 +1,7 @@
+# type EncounterType = 'minion'|'elite'|'event'|'shop'|'camp'|'curio'
+# type EnemyList = [name: string; hp: int; effects: [effect: string;stacks: int][]][]
+
+id,type,name,description,enemies,dialogue
+string,EncounterType,string,string,EnemyList,string
+cactus_pair,minion,仙人掌怪,概念：防+强化。【尖刺X】：对攻击者造成X点伤害。,[[仙人掌怪;12;[]];[仙人掌怪;12;[]]],
+snake_pair,minion,蛇,概念：攻+强化。给玩家塞入蛇毒牌（1费：打出时移除此牌。弃掉时受到3点伤害）。,[[蛇;10;[[poison;2];[quick;1]]]],

src/csv-loader/fixtures/enemy_intents.csv

@@ -0,0 +1,7 @@
+# type IntentEffectTarget = 'user' | 'eachEnemy' | 'randomEnemy' | 'player'
+# type IntentEffect = [IntentEffectTarget; string; number]
+# type IntentEffects = IntentEffect[]
+
+id,enemy,initialIntent,nextIntents,brokenIntent,effects
+string,string,boolean,string[],string[],IntentEffects
+仙人掌怪-boost,仙人掌怪,true,[仙人掌怪-boost;仙人掌怪-defend],,[[user;spike;1];[user;defend;4]]

src/csv-loader/fixtures/user_rev.csv

@@ -1,4 +1,4 @@
-# orders := ~order_rev(user)
+# inject orders = ~order_rev(user)
 id,name
 string,string
 u01,Alice

src/csv-loader/loader.ts

@@ -1,4 +1,4 @@
-import { parse } from "csv-parse/sync";
+import { parse } from "csv-parse/browser/esm/sync";
 import {
   parseSchema,
   createValidator,
@@ -16,6 +16,7 @@ import type {
   CsvParseResult,
   PropertyConfig,
   ReverseReferenceDeclaration,
+  TypeDeclaration,
 } from "./types.js";
 import {
   hasNestedReferences,
@@ -31,48 +32,61 @@ import {
   parseReferenceValue,
 } from "./reference-resolver.js";
 import { generateTypeDefinition } from "./type-gen.js";
-import { csvToModule } from "./module-gen.js";
-import * as fs from "fs";
-import * as path from "path";
 
 /**
- * Parse a reverse reference declaration from a comment line.
+ * Escape double-quote characters in the schema row so csv-parse doesn't
- * Format: # fieldName := ~tableName(foreignKey)
+ * misinterpret them as CSV field delimiters.
- * Returns null if the line is not a reverse reference declaration.
+ *
+ * The schema row is the 2nd non-empty line. Cells that contain the quote
+ * character (e.g. `"active" | "inactive"`) have their inner quotes escaped
+ * and are wrapped in quotes, so csv-parse treats each as a single field.
  */
-function parseReverseReferenceDeclaration(
+function escapeSchemaRowQuotes(
-  line: string,
+  content: string,
-  commentChar: string = "#",
+  delimiter: string,
-): ReverseReferenceDeclaration | null {
+  quote: string,
-  const trimmed = line.trim();
+  escape: string,
-  // Must start with the comment character
+): string {
-  if (!trimmed.startsWith(commentChar)) return null;
+  if (!quote || !content.includes(quote)) {
-
+    return content;
-  const content = trimmed.slice(commentChar.length).trim();
-
-  // Match pattern: fieldName := ~tableName(foreignKey)
-  const match = content.match(/^(\w+)\s*:=\s*~(\w+)\((\w+)\)(\?)?$/);
-  if (!match) return null;
-
-  const [, fieldName, tableName, foreignKey, optionalMark] = match;
-  const isOptional = optionalMark === "?";
-
-  const schema: ReverseReferenceSchema = {
-    type: "reverseReference",
-    tableName,
-    foreignKey,
-    isOptional,
-  };
-
-  return {
-    fieldName,
-    tableName,
-    foreignKey,
-    isOptional,
-    schema,
-  };
   }
 
+  const lines = content.split(/\r?\n/);
+  let schemaRowIndex = -1;
+  let nonEmptyCount = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    nonEmptyCount++;
+    if (nonEmptyCount === 2) {
+      schemaRowIndex = i;
+      break;
+    }
+  }
+  if (schemaRowIndex === -1) {
+    return content;
+  }
+
+  const cells = lines[schemaRowIndex].split(delimiter);
+  const transformed = cells
+    .map((cell) => {
+      if (!cell.includes(quote)) {
+        return cell;
+      }
+      const escaped = cell.split(quote).join(escape + quote);
+      return quote + escaped + quote;
+    })
+    .join(delimiter);
+  lines[schemaRowIndex] = transformed;
+  return lines.join("\n");
+}
+import { csvToModule } from "./module-gen.js";
+import {
+  parseTypeDeclaration,
+  parseReverseReferenceDeclaration,
+  expandSchemaString,
+  resolveTypeReferences,
+} from "./type-declarations.js";
+
 /**
  * Parse CSV content string into structured data with schema validation.
  * This is a standalone function that doesn't depend on webpack/rspack LoaderContext.
@@ -99,6 +113,8 @@ export function parseCsv(
   // Pre-strip comment lines from content before passing to csv-parse,
   // to avoid quote parsing errors in comment lines containing double quotes.
   const reverseReferences: ReverseReferenceDeclaration[] = [];
+  // Store raw type declarations (name + schema string) first, resolve after all names are known
+  const typeDeclarationsRaw: { typeName: string; schemaString: string }[] = [];
   let filteredContent = content;
   if (comment) {
     const lines = content.split(/\r?\n/);
@@ -106,18 +122,35 @@ export function parseCsv(
     for (const line of lines) {
       const trimmed = line.trim();
       if (trimmed.startsWith(comment)) {
+        // Try to parse as type declaration first
+        const typeDecl = parseTypeDeclaration(trimmed, comment);
+        if (typeDecl) {
+          typeDeclarationsRaw.push(typeDecl);
+          continue; // Skip type declaration lines
+        }
+        // Try to parse as reverse reference
         const decl = parseReverseReferenceDeclaration(trimmed, comment);
         if (decl) {
           reverseReferences.push(decl);
+          continue; // Skip reverse reference lines
+        }
+        // Regular comment line - strip it (csv-parse can't handle quotes in comments)
+        continue;
       }
-        // Skip comment lines
-      } else {
       nonCommentLines.push(line);
     }
-    }
     filteredContent = nonCommentLines.join("\n");
   }
 
+  // Escape double-quotes in the schema row so csv-parse doesn't treat them
+  // as CSV field delimiters (e.g. `"active" | "inactive"` in a schema cell).
+  filteredContent = escapeSchemaRowQuotes(
+    filteredContent,
+    delimiter,
+    quote,
+    escape,
+  );
+
   const records = parse(filteredContent, {
     delimiter,
     quote,
@@ -147,11 +180,18 @@ export function parseCsv(
 
   const dataRows = filteredRecords.slice(2);
 
-  // Also check schema row cells for comment-prefixed reverse reference declarations
+  // Also check schema row cells for comment-prefixed type declarations
-  // (in case they appear as schema cells rather than separate rows)
+  // and reverse reference declarations
   for (let col = 0; col < schemas.length; col++) {
     const cell = (schemas[col] ?? "").trim();
     if (comment && cell.startsWith(comment)) {
+      // Try type declaration first
+      const typeDecl = parseTypeDeclaration(cell, comment);
+      if (typeDecl) {
+        typeDeclarationsRaw.push(typeDecl);
+        continue;
+      }
+      // Try reverse reference
       const decl = parseReverseReferenceDeclaration(cell, comment);
       if (decl) {
         reverseReferences.push(decl);
@@ -159,18 +199,93 @@ export function parseCsv(
     }
   }
 
+  // Build a map of declared type names first
+  const declaredTypeNames = new Set<string>();
+  for (const decl of typeDeclarationsRaw) {
+    declaredTypeNames.add(decl.typeName);
+  }
+
+  // Build a map of schema strings for expansion (only stores string schemas initially)
+  const declaredSchemaStrings = new Map<string, string>();
+  for (const decl of typeDeclarationsRaw) {
+    // If the schema is a string literal union, store it for expansion
+    declaredSchemaStrings.set(decl.typeName, decl.schemaString);
+  }
+
+  // Parse type declarations with expansion of type name references
+  const typeDeclarationsParsed: {
+    name: string;
+    schema: Schema;
+    schemaString: string;
+  }[] = [];
+  for (const decl of typeDeclarationsRaw) {
+    // Expand any type name references before parsing
+    const expandedSchema = expandSchemaString(
+      decl.schemaString,
+      declaredSchemaStrings,
+    );
+    const schema = parseSchema(expandedSchema.trim());
+    typeDeclarationsParsed.push({
+      name: decl.typeName,
+      schema,
+      schemaString: decl.schemaString,
+    });
+  }
+
+  // Build declared types map
+  const declaredTypes = new Map<string, Schema>();
+  for (const decl of typeDeclarationsParsed) {
+    declaredTypes.set(decl.name, decl.schema);
+  }
+
+  // Now resolve all type references within type declarations (for nested type refs)
+  const typeDeclarations: TypeDeclaration[] = [];
+  for (const decl of typeDeclarationsParsed) {
+    const resolvedSchema = resolveTypeReferences(decl.schema, declaredTypes);
+    typeDeclarations.push({
+      name: decl.name,
+      schema: resolvedSchema,
+      schemaString: decl.schemaString,
+    });
+  }
+
+  // Update declaredTypes with resolved schemas for column schema lookup
+  for (const decl of typeDeclarations) {
+    declaredTypes.set(decl.name, decl.schema);
+  }
+
   const resolveReferences = options.resolveReferences ?? true;
 
   const propertyConfigs: PropertyConfig[] = headers.map(
     (header: string, index: number) => {
       const schemaString = schemas[index];
-      const schema = parseSchema(schemaString);
+      // Check if schema string matches a declared type name
+      let schema: Schema;
+      let declaredTypeName: string | undefined;
+      let columnSchemaString: string | undefined;
+      if (declaredTypes.has(schemaString)) {
+        schema = declaredTypes.get(schemaString)!;
+        declaredTypeName = schemaString;
+      } else {
+        // Expand any custom type name references before parsing
+        const expandedSchema = expandSchemaString(
+          schemaString,
+          declaredSchemaStrings,
+        );
+        schema = parseSchema(expandedSchema.trim());
+        // Only preserve the original schema string if expansion actually changed it
+        if (expandedSchema !== schemaString) {
+          columnSchemaString = schemaString;
+        }
+      }
 
       const config: PropertyConfig = {
         name: header,
         schema,
         validator: createValidator(schema),
         parser: (valueString: string) => parseValue(schema, valueString),
+        declaredTypeName,
+        schemaString: columnSchemaString,
       };
 
       if (schema.type === "reference") {
@@ -327,6 +442,7 @@ export function parseCsv(
     references,
     referenceFields,
     reverseReferences,
+    typeDeclarations,
   };
 
   if (emitTypes) {
@@ -335,6 +451,7 @@ export function parseCsv(
       propertyConfigs,
       references,
       options.currentFilePath,
+      typeDeclarations,
     );
   }
 

src/csv-loader/module-gen.test.ts

@@ -104,7 +104,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("_self_refLookup = new Map(_raw.map");
     expect(result.js).toContain(
-      "parent: _self_refLookup.get(String(row.parent))",
+      "row.parent = _self_refLookup.get(String(row.parent));",
     );
   });
 
@@ -119,7 +119,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).toContain("import _circular_b from './circular_b.csv'");
     expect(result.js).toContain("export default function getData()");
     expect(result.js).toContain("_circular_bLookup");
-    expect(result.js).toContain("related:");
+    expect(result.js).toContain("row.related =");
   });
 
   it("should emit accessor for self-referencing table with nested reference in tuple", () => {
@@ -137,7 +137,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("parent_info:");
+    expect(result.js).toContain("row.parent_info =");
     expect(result.js).toContain(
       "_self_refLookup.get(String(row.parent_info[0]))",
     );
@@ -159,7 +159,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("ref_or_val:");
+    expect(result.js).toContain("row.ref_or_val =");
     expect(result.js).toContain(
       "_self_refLookup.get(String(row.ref_or_val)) ?? row.ref_or_val",
     );
@@ -180,7 +180,7 @@ describe("csvToModule - circular reference support", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refLookup");
     expect(result.js).toContain("export default function getData()");
-    expect(result.js).toContain("children:");
+    expect(result.js).toContain("row.children =");
   });
 
   it("should generate correct type definition for self-referencing table using local singular type", () => {
@@ -247,7 +247,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -255,7 +255,7 @@ describe("csvToModule - reverse reference output", () => {
 
     expect(result.js).toContain("import _orders from './orders.csv'");
     expect(result.js).toContain("_ordersBy_customer");
-    expect(result.js).toContain("orders:");
+    expect(result.js).toContain("row.orders =");
     expect(result.js).toContain("_ordersBy_customer.get(String(row.id))");
   });
 
@@ -263,7 +263,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "1,Alice",
     ].join("\n");
 
@@ -278,7 +278,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -291,7 +291,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# children := ~self_ref(parent)",
+      "# inject children = ~self_ref(parent)",
       "1,Root",
       "2,Child",
     ].join("\n");
@@ -304,14 +304,14 @@ describe("csvToModule - reverse reference output", () => {
     expect(result.js).not.toContain("import _self_ref from './self_ref.csv'");
     expect(result.js).toContain("_self_refBy_parent");
     expect(result.js).toContain("for (const r of _raw)");
-    expect(result.js).toContain("children:");
+    expect(result.js).toContain("row.children =");
   });
 
   it("should generate correct type definition for reverse references", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -329,7 +329,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "1,Alice",
     ].join("\n");
 
@@ -346,7 +346,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name,manager",
       "string,string,@users",
-      "# reports := ~users(manager)",
+      "# inject reports = ~users(manager)",
       "1,Alice,2",
       "2,Bob,",
     ].join("\n");
@@ -365,7 +365,7 @@ describe("csvToModule - reverse reference output", () => {
     const csv = [
       "id,name,creator",
       "string,string,@users",
-      "# reviews := ~users(reviewer)",
+      "# inject reviews = ~users(reviewer)",
       "1,Doc,1",
     ].join("\n");
 

src/csv-loader/module-gen.ts

@@ -186,7 +186,7 @@ export function csvToModule(
   const reverseLookupVar = (tableName: string, foreignKey: string) =>
     reverseLookupVarMap.get(`${tableName}:${foreignKey}`)!;
 
-  const rowResolvers: string[] = [];
+  const rowResolvers: { name: string; code: string }[] = [];
   for (const config of result.propertyConfigs) {
     if (config.isReverseReference) {
       // Reverse reference resolution
@@ -196,13 +196,15 @@ export function csvToModule(
       if (decl) {
         const revLookup = reverseLookupVar(decl.tableName, decl.foreignKey);
         if (decl.isOptional) {
-          rowResolvers.push(
+          rowResolvers.push({
-            `    ${config.name}: (${revLookup}.get(String(row.${defaultPrimaryKey})) || null),`,
+            name: config.name,
-          );
+            code: `(${revLookup}.get(String(row.${defaultPrimaryKey})) || null)`,
+          });
         } else {
-          rowResolvers.push(
+          rowResolvers.push({
-            `    ${config.name}: (${revLookup}.get(String(row.${defaultPrimaryKey})) || []),`,
+            name: config.name,
-          );
+            code: `(${revLookup}.get(String(row.${defaultPrimaryKey})) || [])`,
+          });
         }
       }
     } else if (hasNestedReferences(config.schema)) {
@@ -213,7 +215,7 @@ export function csvToModule(
         defaultPrimaryKey,
         reverseLookupVar,
       );
-      rowResolvers.push(`    ${config.name}: ${resolveCode},`);
+      rowResolvers.push({ name: config.name, code: resolveCode });
     }
   }
 
@@ -233,10 +235,10 @@ export function csvToModule(
     ...reverseLookupInits.map((l) => `  ${l}`),
     ...(rowResolvers.length > 0
       ? [
-          "  _resolved = _raw.map(row => ({",
+          "  _resolved = _raw.map(row => {",
-          "    ...row,",
+          ...rowResolvers.map((r) => `    row.${r.name} = ${r.code};`),
-          ...rowResolvers,
+          "    return row;",
-          "  }));",
+          "  });",
         ]
       : []),
     "  return _resolved;",

src/csv-loader/reference-resolver.ts

@@ -12,6 +12,16 @@ import { parseCsv } from "./loader.js";
 /** Cache for loaded referenced tables */
 const referenceTableCache = new Map<string, Record<string, unknown>[]>();
 
+/**
+ * Cache for reverse-reference lookups: filePath -> (foreignKey -> (fkValue -> rows[])).
+ * Built once per referenced table + foreign key, mirroring what module-gen emits,
+ * so resolveReverseReference doesn't re-filter the whole table per row.
+ */
+const reverseLookupCache = new Map<
+  string,
+  Map<string, Map<string, Record<string, unknown>[]>>
+>();
+
 /** Set of file paths currently being loaded (to detect circular references) */
 const loadingFiles = new Set<string>();
 
@@ -31,14 +41,13 @@ export function hasNestedReferences(schema: Schema): boolean {
   }
 }
 
-export function loadReferenceTable(
+function loadReferenceTableData(
   schema: ReferenceSchema | ReverseReferenceSchema,
   refBaseDir: string | undefined,
-  defaultPrimaryKey: string,
   currentFilePath: string | undefined,
 ): {
-  lookup: Map<string, Record<string, unknown>>;
   refTable: Record<string, unknown>[];
+  refFilePath: string;
 } {
   const baseDir =
     refBaseDir ||
@@ -75,6 +84,30 @@ export function loadReferenceTable(
     }
   }
 
+  return { refTable, refFilePath };
+}
+
+/**
+ * Load a referenced table and build a forward lookup keyed by primary key.
+ * Only call this when forward resolution is actually needed; the reverse
+ * path uses `loadReferenceTableData` directly to avoid building a throwaway map.
+ */
+export function loadReferenceTable(
+  schema: ReferenceSchema | ReverseReferenceSchema,
+  refBaseDir: string | undefined,
+  defaultPrimaryKey: string,
+  currentFilePath: string | undefined,
+): {
+  lookup: Map<string, Record<string, unknown>>;
+  refTable: Record<string, unknown>[];
+  refFilePath: string;
+} {
+  const { refTable, refFilePath } = loadReferenceTableData(
+    schema,
+    refBaseDir,
+    currentFilePath,
+  );
+
   const lookup = new Map<string, Record<string, unknown>>();
   refTable.forEach((row) => {
     const pkValue = row[defaultPrimaryKey];
@@ -83,7 +116,50 @@ export function loadReferenceTable(
     }
   });
 
-  return { lookup, refTable };
+  return { lookup, refTable, refFilePath };
+}
+
+/**
+ * Build (and cache) a reverse lookup for a referenced table + foreign key:
+ * a map from the foreign-key value to the rows that reference it.
+ */
+function getReverseLookup(
+  schema: ReverseReferenceSchema,
+  refBaseDir: string | undefined,
+  defaultPrimaryKey: string,
+  currentFilePath: string | undefined,
+): Map<string, Record<string, unknown>[]> {
+  const { refTable, refFilePath } = loadReferenceTableData(
+    schema,
+    refBaseDir,
+    currentFilePath,
+  );
+
+  let byForeignKey = reverseLookupCache.get(refFilePath);
+  if (!byForeignKey) {
+    byForeignKey = new Map();
+    reverseLookupCache.set(refFilePath, byForeignKey);
+  }
+
+  const cached = byForeignKey.get(schema.foreignKey);
+  if (cached) return cached;
+
+  const lookup = new Map<string, Record<string, unknown>[]>();
+  for (const row of refTable) {
+    const fkValue = row[schema.foreignKey];
+    const fkStr =
+      fkValue !== null && fkValue !== undefined && typeof fkValue === "object"
+        ? String((fkValue as Record<string, unknown>)[defaultPrimaryKey])
+        : String(fkValue);
+    const bucket = lookup.get(fkStr);
+    if (bucket) {
+      bucket.push(row);
+    } else {
+      lookup.set(fkStr, [row]);
+    }
+  }
+  byForeignKey.set(schema.foreignKey, lookup);
+  return lookup;
 }
 
 export function resolveReferenceId(
@@ -299,9 +375,12 @@ export function parseValueWithReferences(
       );
     }
     case "union": {
+      // Try reference members first (more specific), then non-reference members.
+      // This makes the fallback structural rather than error-message-driven.
+      const refMembers = schema.members.filter(hasNestedReferences);
+      const nonRefMembers = schema.members.filter((m) => !hasNestedReferences(m));
       const errors: Error[] = [];
-      for (const member of schema.members) {
+      for (const member of [...refMembers, ...nonRefMembers]) {
-        if (hasNestedReferences(member)) {
         try {
           const parsed = parseValue(member, valueString);
           return resolveNestedReferences(
@@ -316,22 +395,7 @@ export function parseValueWithReferences(
           errors.push(e instanceof Error ? e : new Error(String(e)));
         }
       }
-      }
+      throw errors[0] ?? new Error("Value does not match any union member");
-      if (
-        errors.length > 0 &&
-        errors.every((e) =>
-          /not found|Circular reference|Failed to load/.test(e.message),
-        )
-      ) {
-        for (const member of schema.members) {
-          if (!hasNestedReferences(member)) {
-            try {
-              return parseValue(member, valueString);
-            } catch {}
-          }
-        }
-      }
-      return parseValue(schema, valueString);
     }
     default:
       return parseValue(schema, valueString);
@@ -345,21 +409,13 @@ export function resolveReverseReference(
   defaultPrimaryKey: string,
   currentFilePath: string | undefined,
 ): Record<string, unknown>[] {
-  const { refTable } = loadReferenceTable(
+  const lookup = getReverseLookup(
     schema,
     refBaseDir,
     defaultPrimaryKey,
     currentFilePath,
   );
-  const pkStr = String(pkValue);
+  return lookup.get(String(pkValue)) ?? [];
-  return refTable.filter((row) => {
-    const fkValue = row[schema.foreignKey];
-    const fkStr =
-      fkValue !== null && fkValue !== undefined && typeof fkValue === "object"
-        ? String((fkValue as Record<string, unknown>)[defaultPrimaryKey])
-        : String(fkValue);
-    return fkStr === pkStr;
-  });
 }
 
 export function resolveNestedReferences(
@@ -425,9 +481,11 @@ export function resolveNestedReferences(
       );
     }
     case "union": {
+      // Try reference members first (more specific), then non-reference members.
+      const refMembers = schema.members.filter(hasNestedReferences);
+      const nonRefMembers = schema.members.filter((m) => !hasNestedReferences(m));
       const errors: Error[] = [];
-      for (const member of schema.members) {
+      for (const member of [...refMembers, ...nonRefMembers]) {
-        if (hasNestedReferences(member)) {
         try {
           return resolveNestedReferences(
             value,
@@ -441,7 +499,6 @@ export function resolveNestedReferences(
           errors.push(e instanceof Error ? e : new Error(String(e)));
         }
       }
-      }
       if (errors.length > 0) {
         throw errors[0];
       }

src/csv-loader/rollup.ts

@@ -53,7 +53,7 @@ interface RollupPlugin {
 }
 
 /**
- * Rollup plugin for loading CSV files with inline-schema validation.
+ * Rollup plugin for loading CSV files with typed-csv validation.
  * Works with both Vite and Tsup (esbuild).
  */
 export function csvLoader(options: CsvRollupOptions = {}): RollupPlugin {
@@ -67,7 +67,7 @@ export function csvLoader(options: CsvRollupOptions = {}): RollupPlugin {
   } = options;
 
   return {
-    name: "inline-schema-csv",
+    name: "typed-csv",
 
     transform(code: string, id: string) {
       // Check if file matches the include/exclude patterns

src/csv-loader/tests/parseCsv-basic.test.ts

@@ -65,6 +65,21 @@ describe("parseCsv - basic parsing", () => {
     expect(result.data[1]).toEqual({ name: "Bob", status: "off" });
   });
 
+  it("should parse CSV with double-quoted string literal columns", () => {
+    const csv = [
+      "name,status",
+      'string,"active" | "inactive"',
+      "Alice,active",
+      "Bob,inactive",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.data).toHaveLength(2);
+    expect(result.data[0]).toEqual({ name: "Alice", status: "active" });
+    expect(result.data[1]).toEqual({ name: "Bob", status: "inactive" });
+  });
+
   it("should parse CSV with array columns", () => {
     const csv = [
       "name,tags",

src/csv-loader/tests/parseCsv-combinators.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { parseCsv } from "../loader";
 import * as path from "path";
-import { fixturesDir } from "../test-utils";
+import { fixturesDir, readFixture } from "../test-utils";
 
 describe("parseCsv - references in combinatory schemas", () => {
   it("should resolve reference inside a tuple", () => {
@@ -161,4 +161,74 @@ describe("parseCsv - references in combinatory schemas", () => {
     });
     expect(details[1]).toBe(5);
   });
+
+  it("should parse encounter fixture with custom type aliases and nested tuples/arrays", () => {
+    const encounterCsv = readFixture("encounter.csv");
+
+    const result = parseCsv(encounterCsv, {
+      emitTypes: false,
+      currentFilePath: path.join(fixturesDir, "encounter.csv"),
+    });
+
+    expect(result.data).toHaveLength(2);
+
+    // First row: cactus_pair
+    expect(result.data[0]).toMatchObject({
+      id: "cactus_pair",
+      type: "minion",
+      name: "仙人掌怪",
+      description: "概念：防+强化。【尖刺X】：对攻击者造成X点伤害。",
+      dialogue: "",
+    });
+
+    const cactusEnemies = result.data[0].enemies as unknown[];
+    expect(cactusEnemies).toHaveLength(2);
+    expect(cactusEnemies[0]).toEqual(["仙人掌怪", 12, []]);
+    expect(cactusEnemies[1]).toEqual(["仙人掌怪", 12, []]);
+
+    // Second row: snake_pair
+    expect(result.data[1]).toMatchObject({
+      id: "snake_pair",
+      type: "minion",
+      name: "蛇",
+      description:
+        "概念：攻+强化。给玩家塞入蛇毒牌（1费：打出时移除此牌。弃掉时受到3点伤害）。",
+      dialogue: "",
+    });
+
+    const snakeEnemies = result.data[1].enemies as unknown[];
+    expect(snakeEnemies).toHaveLength(1);
+    expect(snakeEnemies[0]).toEqual([
+      "蛇",
+      10,
+      [
+        ["poison", 2],
+        ["quick", 1],
+      ],
+    ]);
+  });
+
+  it("should parse enemy_intents fixture with tuple arrays and type aliases", () => {
+    const enemyIntentsCsv = readFixture("enemy_intents.csv");
+
+    const result = parseCsv(enemyIntentsCsv, {
+      emitTypes: false,
+      currentFilePath: path.join(fixturesDir, "enemy_intents.csv"),
+    });
+
+    expect(result.data).toHaveLength(1);
+
+    expect(result.data[0]).toMatchObject({
+      id: "仙人掌怪-boost",
+      enemy: "仙人掌怪",
+      initialIntent: true,
+      nextIntents: ["仙人掌怪-boost", "仙人掌怪-defend"],
+      brokenIntent: [],
+    });
+
+    const effects = result.data[0].effects as unknown[][];
+    expect(effects).toHaveLength(2);
+    expect(effects[0]).toEqual(["user", "spike", 1]);
+    expect(effects[1]).toEqual(["user", "defend", 4]);
+  });
 });

src/csv-loader/tests/parseCsv-reverseRefs.test.ts

@@ -20,7 +20,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "id,name",
         "string,string",
-        "# orders := ~rev_orders(customer)",
+        "# inject orders = ~rev_orders(customer)",
         "1,Alice",
         "2,Bob",
       ].join("\n");
@@ -43,6 +43,40 @@ describe("parseCsv - reverse reference resolution", () => {
     }
   });
 
+  it("should resolve reverse reference when the foreign key is an object reference", () => {
+    // The referenced table's foreign key column is itself a reference, so the
+    // stored value is an object and the reverse lookup must key on its primary key.
+    const ordersCsvPath = path.join(fixturesDir, "rev_orders.csv");
+    const ordersContent = [
+      "id,customer,total",
+      "string,@users,number",
+      "1,1,100",
+      "2,1,50",
+    ].join("\n");
+    fs.writeFileSync(ordersCsvPath, ordersContent);
+
+    try {
+      const csv = [
+        "id,name",
+        "string,string",
+        "# inject orders = ~rev_orders(customer)",
+        "1,Alice",
+      ].join("\n");
+
+      const result = parseCsv(csv, {
+        emitTypes: false,
+        currentFilePath: path.join(fixturesDir, "test.csv"),
+      });
+
+      const orders = result.data[0].orders as Record<string, unknown>[];
+      expect(orders).toHaveLength(2);
+      expect(orders[0].id).toBe("1");
+      expect(orders[1].id).toBe("2");
+    } finally {
+      fs.unlinkSync(ordersCsvPath);
+    }
+  });
+
   it("should return empty array for reverse reference with no matches", () => {
     const ordersCsvPath = path.join(fixturesDir, "rev_orders.csv");
     const ordersContent = [
@@ -57,7 +91,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "id,name",
         "string,string",
-        "# orders := ~rev_orders(customer)",
+        "# inject orders = ~rev_orders(customer)",
         "1,Alice",
         "99,Nobody",
       ].join("\n");
@@ -79,7 +113,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)?",
+      "# inject orders = ~orders(customer)?",
       "99,Nobody",
     ].join("\n");
 
@@ -96,7 +130,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -124,7 +158,7 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -140,8 +174,8 @@ describe("parseCsv - reverse reference resolution", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
-      "# parts := ~parts(user)",
+      "# inject parts = ~parts(user)",
       "1,Alice",
     ].join("\n");
 
@@ -162,7 +196,7 @@ describe("parseCsv - reverse reference resolution", () => {
       "id,name",
       "string,string",
       "# This is just a comment",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -190,7 +224,7 @@ describe("parseCsv - reverse reference resolution", () => {
       const csv = [
         "# id: id of user",
         "# orders: list of related orders",
-        "# orders := ~order(user)",
+        "# inject orders = ~order(user)",
         "id,name",
         "string,string",
         "u01,Alice",
@@ -225,7 +259,7 @@ describe("parseCsv - reverse reference with resolveReferences: false", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# orders := ~orders(customer)",
+      "# inject orders = ~orders(customer)",
       "1,Alice",
     ].join("\n");
 
@@ -255,7 +289,7 @@ describe("parseCsv - reverse reference with resolveReferences: false", () => {
     const csv = [
       "id,name",
       "string,string",
-      "# nonexistent := ~nonexistent(some_key)",
+      "# inject nonexistent = ~nonexistent(some_key)",
       "1,Alice",
     ].join("\n");
 

src/csv-loader/tests/parseCsv-typeDeclarations.test.ts

@@ -0,0 +1,330 @@
+import { describe, it, expect } from "vitest";
+import { parseCsv } from "../loader";
+import * as path from "path";
+import { fixturesDir } from "../test-utils";
+
+describe("parseCsv - type declarations", () => {
+  it("should parse type declaration from comment line", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(1);
+    expect(result.typeDeclarations[0]).toMatchObject({
+      name: "Trigger",
+      schema: {
+        type: "union",
+        members: [
+          { type: "stringLiteral", value: "onPlay" },
+          { type: "stringLiteral", value: "onDraw" },
+          { type: "stringLiteral", value: "onDiscard" },
+        ],
+      },
+    });
+  });
+
+  it("should use declared type as column schema", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0]).toEqual({ id: "attack", trigger: "onPlay" });
+  });
+
+  it("should include declared types in type definition", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "card",
+      currentFilePath: path.join(fixturesDir, "card.csv"),
+    });
+
+    expect(result.typeDefinition).toContain("export type Trigger =");
+    expect(result.typeDefinition).toContain(
+      "'onPlay' | 'onDraw' | 'onDiscard'",
+    );
+  });
+
+  it("should parse multiple type declarations", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "# type Status = 'active' | 'inactive'",
+      "id,trigger,status",
+      "string,Trigger,Status",
+      "attack,onPlay,active",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(2);
+    expect(result.typeDeclarations[0].name).toBe("Trigger");
+    expect(result.typeDeclarations[1].name).toBe("Status");
+  });
+
+  it("should include multiple type declarations in type definition", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "# type Status = 'active' | 'inactive'",
+      "id,trigger,status",
+      "string,Trigger,Status",
+      "attack,onPlay,active",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "card",
+      currentFilePath: path.join(fixturesDir, "card.csv"),
+    });
+
+    expect(result.typeDefinition).toContain("export type Trigger =");
+    expect(result.typeDefinition).toContain("export type Status =");
+  });
+
+  it("should ignore comment lines that are not type declarations", () => {
+    const csv = [
+      "# This is just a comment",
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(1);
+    expect(result.typeDeclarations[0].name).toBe("Trigger");
+  });
+
+  it("should handle type declaration with array schema", () => {
+    const csv = [
+      "# type Tags = string[]",
+      "id,tags",
+      "string,Tags",
+      "1,[dev; admin; user]",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(1);
+    expect(result.typeDeclarations[0].name).toBe("Tags");
+    expect(result.data[0].tags).toEqual(["dev", "admin", "user"]);
+  });
+
+  it("should include type declaration before table type in output", () => {
+    const csv = [
+      "# type Status = 'active' | 'inactive'",
+      "id,status",
+      "string,Status",
+      "1,active",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "item",
+      currentFilePath: path.join(fixturesDir, "item.csv"),
+    });
+
+    // Type declaration should appear before the table type
+    const typeDef = result.typeDefinition!;
+    const statusIndex = typeDef.indexOf("type Status =");
+    const itemTableIndex = typeDef.indexOf("type itemTable =");
+    expect(statusIndex).toBeLessThan(itemTableIndex);
+  });
+
+  it("should work with type declarations alongside reverse references", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(1);
+    expect(result.reverseReferences).toHaveLength(0);
+  });
+
+  it("should resolve type references inside tuple type declarations", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Effect = [Trigger; @effect; int]",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(2);
+    expect(result.typeDeclarations[0].name).toBe("Trigger");
+    expect(result.typeDeclarations[1].name).toBe("Effect");
+    // Effect should have a tuple schema with Trigger's schema inlined
+    expect(result.typeDeclarations[1].schema.type).toBe("tuple");
+  });
+
+  it("should include resolved type references in generated type definition", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw' | 'onDiscard'",
+      "# type Effect = [Trigger; @effect; int]",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "card",
+      currentFilePath: path.join(fixturesDir, "card.csv"),
+    });
+
+    // Both type declarations should appear
+    expect(result.typeDefinition).toContain("export type Trigger =");
+    expect(result.typeDefinition).toContain("export type Effect =");
+    // Column should use the declared type name, not expanded union
+    expect(result.typeDefinition).toContain("readonly trigger: Trigger;");
+  });
+
+  it("should expand custom type names inside tuples and arrays", () => {
+    const csv = [
+      "# type IntentEffectTarget = 'user' | 'eachEnemy' | 'randomEnemy' | 'player'",
+      "# type IntentEffect = [IntentEffectTarget; string; int]",
+      "# type IntentEffects = IntentEffect[]",
+      "id,effects",
+      "string,IntentEffects",
+      "boost,[[user;spike;1];[user;defend;4]]",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.typeDeclarations).toHaveLength(3);
+    const intentEffect = result.typeDeclarations.find(
+      (d) => d.name === "IntentEffect",
+    )!;
+    expect(intentEffect.schema.type).toBe("tuple");
+    // First element should be resolved to union, not a string "IntentEffectTarget"
+    const firstEl = (
+      intentEffect.schema as { elements: { schema: { type: string } }[] }
+    ).elements[0].schema;
+    expect(firstEl.type).toBe("union");
+  });
+
+  it("should use declared type names in generated type definition for tuple arrays", () => {
+    const csv = [
+      "# type IntentEffectTarget = 'user' | 'eachEnemy' | 'randomEnemy' | 'player'",
+      "# type IntentEffect = [IntentEffectTarget; string; int]",
+      "# type IntentEffects = IntentEffect[]",
+      "id,effects",
+      "string,IntentEffects",
+      "boost,[[user;spike;1];[user;defend;4]]",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "intent",
+      currentFilePath: path.join(fixturesDir, "intent.csv"),
+    });
+
+    expect(result.typeDefinition).toContain("export type IntentEffectTarget =");
+    expect(result.typeDefinition).toContain("export type IntentEffect =");
+    expect(result.typeDefinition).toContain("export type IntentEffects =");
+    // IntentEffect should reference IntentEffectTarget, not expand it
+    expect(result.typeDefinition).toContain(
+      "[IntentEffectTarget, string, int]",
+    );
+    // IntentEffects should reference IntentEffect, not expand it
+    expect(result.typeDefinition).toContain("IntentEffect[]");
+    // Column should reference IntentEffects, not inline expansion
+    expect(result.typeDefinition).toContain("readonly effects: IntentEffects;");
+  });
+
+  it("should handle custom type inside a tuple used as an array element", () => {
+    const csv = [
+      '# type Type = "apple" | "orange"',
+      "id,items",
+      "string,[Type; int][]",
+      "001,[[apple;2];[orange;3]]",
+    ].join("\n");
+
+    const result = parseCsv(csv, { emitTypes: false });
+
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0]).toEqual({
+      id: "001",
+      items: [
+        ["apple", 2],
+        ["orange", 3],
+      ],
+    });
+
+    const typeResult = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "item",
+      currentFilePath: path.join(fixturesDir, "item.csv"),
+    });
+
+    expect(typeResult.typeDefinition).toContain("export type Type =");
+    expect(typeResult.typeDefinition).toContain("[Type, int][]");
+    expect(typeResult.typeDefinition).toContain(
+      "readonly items: [Type, int][];",
+    );
+  });
+
+  it("should resolve @table references inside declared types to capitalized type names", () => {
+    const csv = [
+      "# type Entry = [@user]",
+      "id,entry",
+      "string,Entry",
+      "1,[1]",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: true,
+      resourceName: "entries",
+      currentFilePath: path.join(fixturesDir, "entries.csv"),
+      resolveReferences: false,
+    });
+
+    expect(result.typeDefinition).toContain("export type Entry = [User]");
+    expect(result.typeDefinition).toContain("readonly entry: Entry;");
+    // It should also import the User type
+    expect(result.typeDefinition).toContain(
+      "import type { User } from './user.csv'",
+    );
+  });
+});
+
+describe("parseCsv - type declarations with resolveReferences: false", () => {
+  it("should populate typeDeclarations even when resolveReferences is false", () => {
+    const csv = [
+      "# type Trigger = 'onPlay' | 'onDraw'",
+      "id,trigger",
+      "string,Trigger",
+      "attack,onPlay",
+    ].join("\n");
+
+    const result = parseCsv(csv, {
+      emitTypes: false,
+      resolveReferences: false,
+    });
+
+    expect(result.typeDeclarations).toHaveLength(1);
+  });
+});

src/csv-loader/type-declarations.ts

@@ -0,0 +1,256 @@
+import type { Schema, ReverseReferenceSchema } from "../types.js";
+import { parseSchema } from "../parser.js";
+
+export interface ReverseReferenceDeclaration {
+  fieldName: string;
+  tableName: string;
+  foreignKey: string;
+  isOptional: boolean;
+  schema: ReverseReferenceSchema;
+}
+
+export interface TypeDeclaration {
+  name: string;
+  schema: Schema;
+}
+
+/**
+ * Parse a type declaration from a comment line.
+ * Format: # type TypeName = schema
+ * Returns null if the line is not a type declaration.
+ */
+export function parseTypeDeclaration(
+  line: string,
+  commentChar: string = "#",
+): { typeName: string; schemaString: string } | null {
+  const trimmed = line.trim();
+  // Must start with the comment character
+  if (!trimmed.startsWith(commentChar)) return null;
+
+  const content = trimmed.slice(commentChar.length).trim();
+
+  // Match pattern: type TypeName = schema
+  const match = content.match(/^type\s+([A-Z][a-zA-Z0-9]*)\s*=\s*(.+)$/);
+  if (!match) return null;
+
+  const [, typeName, schemaString] = match;
+  return { typeName, schemaString };
+}
+
+/**
+ * Expand a type name to its schema by replacing the type name with its schema inline.
+ * Returns the schema string with type names expanded, or null if not a type name.
+ */
+function expandTypeName(
+  schemaString: string,
+  declaredTypes: Map<string, string>,
+): string | null {
+  const trimmed = schemaString.trim();
+  if (declaredTypes.has(trimmed)) {
+    return declaredTypes.get(trimmed)!;
+  }
+  return null;
+}
+
+/**
+ * Recursively expand all type name references in a schema string.
+ * Handles unions, tuples, arrays, and nested structures.
+ */
+export function expandSchemaString(
+  schemaString: string,
+  declaredTypes: Map<string, string>,
+): string {
+  let result = schemaString;
+
+  // Keep expanding until no more changes (handles recursive dependencies)
+  let prev = "";
+  while (prev !== result) {
+    prev = result;
+    result = expandSchemaInString(result, declaredTypes);
+  }
+
+  return result;
+}
+
+/**
+ * Single pass of type name expansion in a schema string.
+ */
+function expandSchemaInString(
+  schemaString: string,
+  declaredTypes: Map<string, string>,
+): string {
+  // Check if the entire string is a type name
+  const expanded = expandTypeName(schemaString.trim(), declaredTypes);
+  if (expanded !== null) {
+    return expanded;
+  }
+
+  // Handle array suffix: TypeName[] or [tuple][]
+  const trimmed = schemaString.trim();
+  if (trimmed.endsWith("[]")) {
+    const inner = trimmed.slice(0, -2);
+    const expandedInner = expandSchemaInString(inner, declaredTypes);
+    return `${expandedInner}[]`;
+  }
+
+  // Handle union types (recursively expand each member)
+  if (schemaString.includes("|")) {
+    // Split by | but respect quotes
+    const parts = splitByToken(schemaString, "|");
+    if (parts.length > 1) {
+      const expandedParts = parts.map((part) =>
+        expandSchemaInString(part.trim(), declaredTypes),
+      );
+      return expandedParts.join(" | ");
+    }
+  }
+
+  // Handle tuple/array syntax [el1; el2; ...] or [elements]
+  // Check if it's a bracketed structure
+  if (schemaString.startsWith("[") && schemaString.endsWith("]")) {
+    const inner = schemaString.slice(1, -1);
+    // Check if it's semicolon-separated (tuple syntax)
+    if (inner.includes(";")) {
+      const elements = splitByToken(inner, ";");
+      const expandedElements = elements.map((el) =>
+        expandSchemaInString(el.trim(), declaredTypes),
+      );
+      return `[${expandedElements.join("; ")}]`;
+    }
+    // Otherwise it's a simple array, expand recursively
+    return `[${expandSchemaInString(inner, declaredTypes)}]`;
+  }
+
+  // Check if it's a type name reference (only uppercase start to avoid conflicts with primitives)
+  const typeNameMatch = schemaString.trim().match(/^[A-Z][a-zA-Z0-9]*$/);
+  if (typeNameMatch) {
+    const expanded = expandTypeName(schemaString.trim(), declaredTypes);
+    if (expanded !== null) {
+      return expanded;
+    }
+  }
+
+  return schemaString;
+}
+
+/**
+ * Split a string by a token, respecting quoted strings.
+ */
+function splitByToken(str: string, token: string): string[] {
+  const result: string[] = [];
+  let current = "";
+  let inQuote: string | null = null;
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+
+    if (inQuote) {
+      if (char === inQuote && str[i - 1] !== "\\") {
+        inQuote = null;
+      }
+      current += char;
+    } else if (char === '"' || char === "'") {
+      inQuote = char;
+      current += char;
+    } else if (char === token && inQuote === null) {
+      result.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.length > 0 || str.endsWith(token)) {
+    result.push(current);
+  }
+
+  return result;
+}
+
+/**
+ * Resolve type name references within a schema using declared types.
+ * For example, if "Trigger" is a declared type, references to "Trigger" in
+ * other schemas will be replaced with the actual Trigger schema definition.
+ */
+export function resolveTypeReferences(
+  schema: Schema,
+  declaredTypes: Map<string, Schema>,
+): Schema {
+  switch (schema.type) {
+    case "union":
+      return {
+        type: "union",
+        members: schema.members.map((m) =>
+          resolveTypeReferences(m, declaredTypes),
+        ),
+      };
+    case "tuple":
+      return {
+        type: "tuple",
+        elements: schema.elements.map((el) => ({
+          name: el.name,
+          schema: resolveTypeReferences(el.schema, declaredTypes),
+        })),
+      };
+    case "array":
+      return {
+        type: "array",
+        element: resolveTypeReferences(schema.element, declaredTypes),
+      };
+    case "reference":
+      // Don't resolve references to other tables
+      return schema;
+    default:
+      return schema;
+  }
+}
+
+/**
+ * Resolve type name references in a type declaration's schema string.
+ * Called after all type names are known.
+ */
+export function resolveTypeDeclarationSchema(
+  schemaString: string,
+  declaredTypes: Map<string, Schema>,
+): Schema {
+  const schema = parseSchema(schemaString.trim());
+  return resolveTypeReferences(schema, declaredTypes);
+}
+
+/**
+ * Parse a reverse reference declaration from a comment line.
+ * Format: # inject fieldName = ~tableName(foreignKey)
+ * Returns null if the line is not a reverse reference declaration.
+ */
+export function parseReverseReferenceDeclaration(
+  line: string,
+  commentChar: string = "#",
+): ReverseReferenceDeclaration | null {
+  const trimmed = line.trim();
+  // Must start with the comment character
+  if (!trimmed.startsWith(commentChar)) return null;
+
+  const content = trimmed.slice(commentChar.length).trim();
+
+  // Match pattern: inject fieldName = ~tableName(foreignKey)
+  const match = content.match(/^inject\s+(\w+)\s*=\s*~(\w+)\((\w+)\)(\?)?$/);
+  if (!match) return null;
+
+  const [, fieldName, tableName, foreignKey, optionalMark] = match;
+  const isOptional = optionalMark === "?";
+
+  const schema: ReverseReferenceSchema = {
+    type: "reverseReference",
+    tableName,
+    foreignKey,
+    isOptional,
+  };
+
+  return {
+    fieldName,
+    tableName,
+    foreignKey,
+    isOptional,
+    schema,
+  };
+}

src/csv-loader/type-gen.ts

@@ -1,6 +1,20 @@
 import * as path from "path";
 import { schemaToTypeString } from "../index.js";
-import type { PropertyConfig } from "./types.js";
+import type { PropertyConfig, TypeDeclaration } from "./types.js";
+
+function resolveReferencesInSchemaString(
+  schemaString: string,
+  resourceNames: Map<string, string>,
+): string {
+  return schemaString
+    .replace(/@([a-zA-Z0-9\-_]+)(\[\])?/g, (_match, tableName, arraySuffix) => {
+      const typeName =
+        resourceNames.get(tableName) ||
+        tableName.charAt(0).toUpperCase() + tableName.slice(1);
+      return arraySuffix ? `${typeName}[]` : typeName;
+    })
+    .replace(/; ?/g, ", ");
+}
 
 /**
  * Generate TypeScript interface for the CSV data
@@ -10,6 +24,7 @@ export function generateTypeDefinition(
   propertyConfigs: PropertyConfig[],
   references: Set<string>,
   currentFilePath?: string,
+  typeDeclarations: TypeDeclaration[] = [],
 ): string {
   const typeName = resourceName ? `${resourceName}Table` : "Table";
   const currentTableName = currentFilePath
@@ -44,11 +59,26 @@ export function generateTypeDefinition(
 
   const importSection = imports.length > 0 ? imports.join("\n") + "\n\n" : "";
 
-  const properties = propertyConfigs
+  // Generate type declarations for user-defined types
+  const typeDeclarationSection =
+    typeDeclarations.length > 0
+      ? typeDeclarations
           .map(
-      (config) =>
+            (decl) =>
-        `    readonly ${config.name}: ${schemaToTypeString(config.schema, resourceNames)};`,
+              `export type ${decl.name} = ${decl.schemaString ? resolveReferencesInSchemaString(decl.schemaString, resourceNames) : schemaToTypeString(decl.schema, resourceNames)};`,
           )
+          .join("\n") + "\n\n"
+      : "";
+
+  const properties = propertyConfigs
+    .map((config) => {
+      const typeStr = config.declaredTypeName
+        ? config.declaredTypeName
+        : config.schemaString
+          ? resolveReferencesInSchemaString(config.schemaString, resourceNames)
+          : schemaToTypeString(config.schema, resourceNames);
+      return `    readonly ${config.name}: ${typeStr};`;
+    })
     .join("\n");
 
   let exportAlias = "";
@@ -58,7 +88,7 @@ export function generateTypeDefinition(
     exportAlias = `\nexport type ${singularType} = ${typeName}[number];`;
   }
 
-  return `${importSection}type ${typeName} = readonly {
+  return `${importSection}${typeDeclarationSection}type ${typeName} = readonly {
 ${properties}
 }[];
 ${exportAlias}

src/csv-loader/types.ts

@@ -57,6 +57,8 @@ export interface CsvParseResult {
   referenceFields: ReferenceFieldInfo[];
   /** Reverse reference declarations parsed from comment lines */
   reverseReferences: ReverseReferenceDeclaration[];
+  /** Type declarations parsed from comment lines */
+  typeDeclarations: TypeDeclaration[];
 }
 
 export interface PropertyConfig {
@@ -74,6 +76,10 @@ export interface PropertyConfig {
   isReverseReference?: boolean;
   /** Foreign key field name for reverse references */
   reverseReferenceForeignKey?: string;
+  /** When a column uses a declared type name, this stores that name */
+  declaredTypeName?: string;
+  /** The original schema string for the column (preserves type name references for output) */
+  schemaString?: string;
 }
 
 /** Parsed reverse reference declaration from a comment line */
@@ -89,3 +95,13 @@ export interface ReverseReferenceDeclaration {
   /** The parsed schema */
   schema: ReverseReferenceSchema;
 }
+
+/** Parsed type declaration from a comment line */
+export interface TypeDeclaration {
+  /** Name of the type being defined */
+  name: string;
+  /** The original schema string (preserves type name references for output) */
+  schemaString: string;
+  /** The parsed schema for this type */
+  schema: Schema;
+}

src/index.test.ts

@@ -174,10 +174,11 @@ describe("Tuples", () => {
     expect(schema.validator(["hello", "42"])).toBe(false);
   });
 
-  it("should parse tuple without brackets", () => {
+  it("should require brackets for tuple values", () => {
     const schema = defineSchema("[string; number]");
-    const value = schema.parse("hello; 42");
+    const value = schema.parse("[hello; 42]");
     expect(value).toEqual(["hello", 42]);
+    expect(() => schema.parse("hello; 42")).toThrow(ParseError);
   });
 
   it("should parse named tuple", () => {
@@ -212,10 +213,11 @@ describe("Arrays", () => {
     expect(schema.validator(["hello", 42])).toBe(false);
   });
 
-  it("should parse array without brackets", () => {
+  it("should require brackets for array values", () => {
     const schema = defineSchema("string[]");
-    const value = schema.parse("hello; world; test");
+    const value = schema.parse("[hello; world; test]");
     expect(value).toEqual(["hello", "world", "test"]);
+    expect(() => schema.parse("hello; world; test")).toThrow(ParseError);
   });
 
   it("should parse array of numbers", () => {
@@ -246,14 +248,15 @@ describe("Arrays", () => {
     ]);
   });
 
-  it("should parse array of tuples without outer brackets", () => {
+  it("should require outer brackets for array of tuples", () => {
     const schema = defineSchema("[string; number][]");
-    const value = schema.parse("[a; 1]; [b; 2]; [c; 3]");
+    const value = schema.parse("[[a; 1]; [b; 2]; [c; 3]]");
     expect(value).toEqual([
       ["a", 1],
       ["b", 2],
       ["c", 3],
     ]);
+    expect(() => schema.parse("[a; 1]; [b; 2]; [c; 3]")).toThrow(ParseError);
   });
 
   it("should parse array of unions", () => {
@@ -283,7 +286,7 @@ describe("Escaping", () => {
 
   it("should handle escaped semicolon in tuple", () => {
     const schema = defineSchema("[string; string]");
-    const value = schema.parse("hello\\;world; test");
+    const value = schema.parse("[hello\\;world; test]");
     expect(value).toEqual(["hello;world", "test"]);
   });
 });
@@ -682,14 +685,15 @@ describe("Reference value parsing (parseValue)", () => {
     expect(result).toEqual(["1", "2", "3"]);
   });
 
-  it("should parse array reference IDs without brackets", () => {
+  it("should require brackets for array reference IDs", () => {
     const schema: import("./types").ReferenceSchema = {
       type: "reference",
       tableName: "users",
       isArray: true,
     };
-    const result = parseValue(schema, "1; 2; 3");
+    const result = parseValue(schema, "[1; 2; 3]");
     expect(result).toEqual(["1", "2", "3"]);
+    expect(() => parseValue(schema, "1; 2; 3")).toThrow(ParseError);
   });
 
   it("should parse empty array reference", () => {

src/parser.ts

@@ -14,10 +14,20 @@ export class ParseError extends Error {
   constructor(
     message: string,
     public position?: number,
+    public schema?: string,
+    public value?: string,
   ) {
-    super(
+    let fullMessage = message;
-      position !== undefined ? `${message} at position ${position}` : message,
+    if (position !== undefined) {
-    );
+      fullMessage += ` at position ${position}`;
+    }
+    if (schema !== undefined) {
+      fullMessage += `. Schema: ${schema}`;
+    }
+    if (value !== undefined) {
+      fullMessage += `. Value: ${value}`;
+    }
+    super(fullMessage);
     this.name = "ParseError";
   }
 }
@@ -240,20 +250,7 @@ class Parser {
         throw new ParseError("Expected ]", this.pos);
       }
 
-      if (this.consumeStr("[")) {
+      // [t] is always a 1-tuple (the [Type][] array form was removed)
-        this.skipWhitespace();
-        if (!this.consumeStr("]")) {
-          throw new ParseError("Expected ]", this.pos);
-        }
-        if (elements.length === 1 && !elements[0].name) {
-          return { type: "array", element: elements[0].schema };
-        }
-        return { type: "array", element: { type: "tuple", elements } };
-      }
-
-      if (elements.length === 1 && !elements[0].name) {
-        return { type: "array", element: elements[0].schema };
-      }
       return { type: "tuple", elements };
     }
 

src/type-utils.ts

@@ -0,0 +1,104 @@
+import type {
+  Schema,
+  ReferenceSchema,
+  ReverseReferenceSchema,
+  UnionSchema,
+} from "./types";
+
+export function schemaToTypeString(
+  schema: Schema,
+  resourceNames?: Map<string, string>,
+): string {
+  switch (schema.type) {
+    case "string":
+      return "string";
+    case "number":
+    case "int":
+    case "float":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "stringLiteral":
+      return `"${schema.value}"`;
+    case "union":
+      return schema.members
+        .map((m) => schemaToTypeString(m, resourceNames))
+        .join(" | ");
+    case "reference": {
+      const typeName =
+        resourceNames?.get(schema.tableName) ||
+        schema.tableName.charAt(0).toUpperCase() + schema.tableName.slice(1);
+      const baseType = schema.isArray ? `${typeName}[]` : typeName;
+      return schema.isOptional ? `${baseType} | null` : baseType;
+    }
+    case "reverseReference": {
+      const typeName =
+        resourceNames?.get(schema.tableName) ||
+        schema.tableName.charAt(0).toUpperCase() + schema.tableName.slice(1);
+      const baseType = `${typeName}[]`;
+      return schema.isOptional ? `${baseType} | null` : baseType;
+    }
+    case "array":
+      const elementType = schemaToTypeString(schema.element, resourceNames);
+      if (schema.element.type === "union") {
+        return `(${elementType})[]`;
+      }
+      return `${elementType}[]`;
+    case "tuple":
+      const tupleElements = schema.elements.map((el) => {
+        const typeStr = schemaToTypeString(el.schema, resourceNames);
+        return el.name ? `${el.name}: ${typeStr}` : typeStr;
+      });
+      return `[${tupleElements.join(", ")}]`;
+    default:
+      return "unknown";
+  }
+}
+
+export function createValidator(schema: Schema): (value: unknown) => boolean {
+  return function validate(value: unknown): boolean {
+    switch (schema.type) {
+      case "string":
+        return typeof value === "string";
+      case "number":
+        return typeof value === "number" && !isNaN(value);
+      case "int":
+        return (
+          typeof value === "number" && !isNaN(value) && Number.isInteger(value)
+        );
+      case "float":
+        return typeof value === "number" && !isNaN(value);
+      case "boolean":
+        return typeof value === "boolean";
+      case "stringLiteral":
+        return typeof value === "string" && value === schema.value;
+      case "union":
+        return schema.members.some((member) => createValidator(member)(value));
+      case "tuple":
+        if (!Array.isArray(value)) return false;
+        if (value.length !== schema.elements.length) return false;
+        return schema.elements.every((elementSchema, index) =>
+          createValidator(elementSchema.schema)(value[index]),
+        );
+      case "array":
+        if (!Array.isArray(value)) return false;
+        return value.every((item) => createValidator(schema.element)(item));
+      case "reference":
+        if (schema.isOptional && value === null) return true;
+        if (schema.isArray) {
+          return (
+            Array.isArray(value) && value.every((id) => typeof id === "string")
+          );
+        }
+        return (
+          typeof value === "string" ||
+          (Array.isArray(value) && value.every((id) => typeof id === "string"))
+        );
+      case "reverseReference":
+        if (schema.isOptional && value === null) return true;
+        return Array.isArray(value);
+      default:
+        return false;
+    }
+  };
+}

src/validator.ts

@@ -1,540 +1,3 @@
-import type {
+// Re-export everything from the split modules
-  Schema,
+export { parseValue } from "./value-parser";
-  PrimitiveSchema,
+export { schemaToTypeString, createValidator } from "./type-utils";
-  TupleSchema,
-  ArraySchema,
-  NamedSchema,
-  ReferenceSchema,
-  ReverseReferenceSchema,
-  StringLiteralSchema,
-  UnionSchema,
-} from "./types";
-import { ParseError } from "./parser";
-
-class ValueParser {
-  private input: string;
-  private pos: number = 0;
-
-  constructor(input: string) {
-    this.input = input;
-  }
-
-  private peek(): string {
-    return this.input[this.pos] || "";
-  }
-
-  private consume(): string {
-    return this.input[this.pos++] || "";
-  }
-
-  private skipWhitespace(): void {
-    while (this.pos < this.input.length && /\s/.test(this.input[this.pos])) {
-      this.pos++;
-    }
-  }
-
-  private consumeStr(str: string): boolean {
-    if (this.input.slice(this.pos, this.pos + str.length) === str) {
-      this.pos += str.length;
-      return true;
-    }
-    return false;
-  }
-
-  parseValue(schema: Schema, allowOmitBrackets: boolean = false): unknown {
-    this.skipWhitespace();
-
-    switch (schema.type) {
-      case "string":
-        return this.parseStringValue();
-      case "number":
-        return this.parseNumberValue();
-      case "int":
-        return this.parseIntValue();
-      case "float":
-        return this.parseFloatValue();
-      case "boolean":
-        return this.parseBooleanValue();
-      case "stringLiteral":
-        return this.parseStringLiteralValue(schema);
-      case "union":
-        return this.parseUnionValue(schema);
-      case "tuple":
-        return this.parseTupleValue(schema, allowOmitBrackets);
-      case "array":
-        return this.parseArrayValue(schema, allowOmitBrackets);
-      case "reference":
-        // Reference values are parsed as strings (IDs) initially, resolved later
-        return this.parseReferenceValue(schema);
-      case "reverseReference":
-        // Reverse references are derived fields, not stored in CSV cells
-        // They resolve to null at parse time; actual resolution happens in the loader
-        return null;
-      default:
-        throw new ParseError(
-          `Unknown schema type: ${(schema as { type: string }).type}`,
-          this.pos,
-        );
-    }
-  }
-
-  private parseStringValue(): string {
-    let result = "";
-    while (this.pos < this.input.length) {
-      const char = this.peek();
-
-      if (char === "\\") {
-        this.consume();
-        const nextChar = this.consume();
-        if (
-          nextChar === ";" ||
-          nextChar === "[" ||
-          nextChar === "]" ||
-          nextChar === "\\"
-        ) {
-          result += nextChar;
-        } else {
-          result += "\\" + nextChar;
-        }
-      } else if (char === ";" || char === "]") {
-        break;
-      } else {
-        result += this.consume();
-      }
-    }
-    return result.trim();
-  }
-
-  private parseNumberValue(): number {
-    let numStr = "";
-    while (this.pos < this.input.length && /[\d.\-+eE]/.test(this.peek())) {
-      numStr += this.consume();
-    }
-    const num = parseFloat(numStr);
-    if (isNaN(num)) {
-      throw new ParseError("Invalid number", this.pos - numStr.length);
-    }
-    return num;
-  }
-
-  private parseIntValue(): number {
-    let numStr = "";
-    while (this.pos < this.input.length && /[\d.\-+eE]/.test(this.peek())) {
-      numStr += this.consume();
-    }
-    const num = parseFloat(numStr);
-    if (isNaN(num)) {
-      throw new ParseError("Invalid number", this.pos - numStr.length);
-    }
-    if (!Number.isInteger(num)) {
-      throw new ParseError("Expected integer value", this.pos - numStr.length);
-    }
-    return num;
-  }
-
-  private parseFloatValue(): number {
-    return this.parseNumberValue();
-  }
-
-  private parseBooleanValue(): boolean {
-    if (this.consumeStr("true")) {
-      return true;
-    }
-    if (this.consumeStr("false")) {
-      return false;
-    }
-    throw new ParseError("Expected true or false", this.pos);
-  }
-
-  private parseStringLiteralValue(schema: StringLiteralSchema): string {
-    const quote = this.peek();
-
-    // 支持带引号或不带引号的字符串值
-    if (quote === '"' || quote === "'") {
-      this.consume(); // Consume opening quote
-
-      let value = "";
-      while (this.pos < this.input.length) {
-        const char = this.peek();
-
-        if (char === "\\") {
-          this.consume();
-          const nextChar = this.consume();
-          if (
-            nextChar === '"' ||
-            nextChar === "'" ||
-            nextChar === "\\" ||
-            nextChar === ";"
-          ) {
-            value += nextChar;
-          } else {
-            value += "\\" + nextChar;
-          }
-        } else if (char === quote) {
-          this.consume(); // Consume closing quote
-
-          if (value !== schema.value) {
-            throw new ParseError(
-              `Invalid value '"${value}"'. Expected '"${schema.value}"'`,
-              this.pos,
-            );
-          }
-
-          return value;
-        } else {
-          value += this.consume();
-        }
-      }
-
-      throw new ParseError("Unterminated string literal", this.pos);
-    } else {
-      // 不带引号的字符串，像普通字符串一样解析
-      let value = "";
-      while (this.pos < this.input.length) {
-        const char = this.peek();
-        if (char === ";" || char === "]" || char === ")") {
-          break;
-        }
-        value += this.consume();
-      }
-
-      value = value.trim();
-
-      if (value !== schema.value) {
-        throw new ParseError(
-          `Invalid value '${value}'. Expected '${schema.value}'`,
-          this.pos - value.length,
-        );
-      }
-
-      return value;
-    }
-  }
-
-  private parseUnionValue(schema: UnionSchema): unknown {
-    const savedPos = this.pos;
-    const errors: Error[] = [];
-
-    // Try each union member until one succeeds
-    for (let i = 0; i < schema.members.length; i++) {
-      this.pos = savedPos;
-      try {
-        return this.parseValue(schema.members[i], false);
-      } catch (e) {
-        errors.push(e as Error);
-        // Continue to next member
-      }
-    }
-
-    // If all members fail, throw a descriptive error
-    throw new ParseError(
-      `Value does not match any union member. Tried ${schema.members.length} alternatives.`,
-      this.pos,
-    );
-  }
-
-  private parseTupleValue(
-    schema: TupleSchema,
-    allowOmitBrackets: boolean,
-  ): unknown[] {
-    let hasOpenBracket = false;
-
-    if (this.peek() === "[") {
-      this.consume();
-      hasOpenBracket = true;
-    } else if (!allowOmitBrackets) {
-      throw new ParseError("Expected [", this.pos);
-    }
-
-    this.skipWhitespace();
-
-    if (this.peek() === "]" && hasOpenBracket) {
-      this.consume();
-      return [];
-    }
-
-    const result: unknown[] = [];
-    for (let i = 0; i < schema.elements.length; i++) {
-      this.skipWhitespace();
-      const elementSchema = schema.elements[i];
-
-      // Try to consume optional name prefix (e.g., "current:")
-      if (elementSchema.name) {
-        this.skipWhitespace();
-        const savedPos = this.pos;
-        if (this.consumeStr(`${elementSchema.name}:`)) {
-          this.skipWhitespace();
-        } else {
-          // Name not found, reset position and continue without name
-          this.pos = savedPos;
-        }
-      }
-
-      result.push(this.parseValue(elementSchema.schema, false));
-      this.skipWhitespace();
-
-      if (i < schema.elements.length - 1) {
-        if (!this.consumeStr(";")) {
-          throw new ParseError("Expected ;", this.pos);
-        }
-      }
-    }
-
-    this.skipWhitespace();
-
-    if (hasOpenBracket) {
-      if (!this.consumeStr("]")) {
-        throw new ParseError("Expected ]", this.pos);
-      }
-    }
-
-    return result;
-  }
-
-  private parseArrayValue(
-    schema: ArraySchema,
-    allowOmitBrackets: boolean,
-  ): unknown[] {
-    let hasOpenBracket = false;
-    const elementIsTupleOrArray =
-      schema.element.type === "tuple" || schema.element.type === "array";
-
-    if (this.pos >= this.input.length || !this.input.trim()) {
-      return [];
-    }
-
-    if (this.peek() === "[") {
-      if (!elementIsTupleOrArray) {
-        this.consume();
-        hasOpenBracket = true;
-      } else if (this.input[this.pos + 1] === "[") {
-        this.consume();
-        hasOpenBracket = true;
-      }
-    }
-
-    if (!hasOpenBracket && !allowOmitBrackets && !elementIsTupleOrArray) {
-      throw new ParseError("Expected [", this.pos);
-    }
-
-    this.skipWhitespace();
-
-    if (this.peek() === "]" && hasOpenBracket) {
-      this.consume();
-      return [];
-    }
-
-    const result: unknown[] = [];
-    while (true) {
-      this.skipWhitespace();
-      result.push(this.parseValue(schema.element, false));
-      this.skipWhitespace();
-
-      if (!this.consumeStr(";")) {
-        break;
-      }
-    }
-
-    this.skipWhitespace();
-
-    if (hasOpenBracket) {
-      if (!this.consumeStr("]")) {
-        throw new ParseError("Expected ]", this.pos);
-      }
-    }
-
-    return result;
-  }
-
-  private parseReferenceValue(
-    schema: ReferenceSchema,
-  ): string | string[] | null {
-    if (schema.isOptional) {
-      this.skipWhitespace();
-      if (this.pos >= this.input.length) {
-        return null;
-      }
-    }
-
-    if (schema.isArray) {
-      // Parse array of IDs: [id1; id2; id3]
-      let hasOpenBracket = false;
-      if (this.peek() === "[") {
-        this.consume();
-        hasOpenBracket = true;
-      }
-
-      this.skipWhitespace();
-
-      if (this.peek() === "]" && hasOpenBracket) {
-        this.consume();
-        return [];
-      }
-
-      const ids: string[] = [];
-      while (true) {
-        this.skipWhitespace();
-        // Parse each ID as a string
-        let id = "";
-        while (
-          this.pos < this.input.length &&
-          this.peek() !== ";" &&
-          this.peek() !== "]"
-        ) {
-          id += this.consume();
-        }
-        ids.push(id.trim());
-        this.skipWhitespace();
-
-        if (!this.consumeStr(";")) {
-          break;
-        }
-      }
-
-      if (hasOpenBracket) {
-        if (!this.consumeStr("]")) {
-          throw new ParseError("Expected ]", this.pos);
-        }
-      }
-
-      return ids;
-    } else {
-      // Parse single ID as string
-      let id = "";
-      while (this.pos < this.input.length) {
-        const char = this.peek();
-        if (char === ";" || char === "]" || char === ",") {
-          break;
-        }
-        id += this.consume();
-      }
-      return id.trim();
-    }
-  }
-
-  getPosition(): number {
-    return this.pos;
-  }
-
-  getInputLength(): number {
-    return this.input.length;
-  }
-}
-
-export function parseValue(schema: Schema, valueString: string): unknown {
-  const parser = new ValueParser(valueString.trim());
-  const allowOmitBrackets = schema.type === "tuple" || schema.type === "array";
-  const value = parser.parseValue(schema, allowOmitBrackets);
-
-  if (parser.getPosition() < parser.getInputLength()) {
-    throw new ParseError("Unexpected input after value", parser.getPosition());
-  }
-
-  return value;
-}
-
-export function schemaToTypeString(
-  schema: Schema,
-  resourceNames?: Map<string, string>,
-): string {
-  switch (schema.type) {
-    case "string":
-      return "string";
-    case "number":
-    case "int":
-    case "float":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "stringLiteral":
-      return `"${schema.value}"`;
-    case "union":
-      return schema.members
-        .map((m) => schemaToTypeString(m, resourceNames))
-        .join(" | ");
-    case "reference": {
-      const typeName =
-        resourceNames?.get(schema.tableName) ||
-        schema.tableName.charAt(0).toUpperCase() + schema.tableName.slice(1);
-      const baseType = schema.isArray ? `${typeName}[]` : typeName;
-      return schema.isOptional ? `${baseType} | null` : baseType;
-    }
-    case "reverseReference": {
-      const typeName =
-        resourceNames?.get(schema.tableName) ||
-        schema.tableName.charAt(0).toUpperCase() + schema.tableName.slice(1);
-      // Reverse references always resolve to an array (one-to-many)
-      const baseType = `${typeName}[]`;
-      return schema.isOptional ? `${baseType} | null` : baseType;
-    }
-    case "array":
-      if (schema.element.type === "tuple") {
-        const tupleElements = schema.element.elements.map((el) => {
-          const typeStr = schemaToTypeString(el.schema, resourceNames);
-          return el.name ? `${el.name}: ${typeStr}` : typeStr;
-        });
-        return `[${tupleElements.join(", ")}][]`;
-      }
-      const elementType = schemaToTypeString(schema.element, resourceNames);
-      if (schema.element.type === "union") {
-        return `(${elementType})[]`;
-      }
-      return `${elementType}[]`;
-    case "tuple":
-      const tupleElements = schema.elements.map((el) => {
-        const typeStr = schemaToTypeString(el.schema, resourceNames);
-        return el.name ? `${el.name}: ${typeStr}` : typeStr;
-      });
-      return `[${tupleElements.join(", ")}]`;
-    default:
-      return "unknown";
-  }
-}
-
-export function createValidator(schema: Schema): (value: unknown) => boolean {
-  return function validate(value: unknown): boolean {
-    switch (schema.type) {
-      case "string":
-        return typeof value === "string";
-      case "number":
-        return typeof value === "number" && !isNaN(value);
-      case "int":
-        return (
-          typeof value === "number" && !isNaN(value) && Number.isInteger(value)
-        );
-      case "float":
-        return typeof value === "number" && !isNaN(value);
-      case "boolean":
-        return typeof value === "boolean";
-      case "stringLiteral":
-        return typeof value === "string" && value === schema.value;
-      case "union":
-        return schema.members.some((member) => createValidator(member)(value));
-      case "tuple":
-        if (!Array.isArray(value)) return false;
-        if (value.length !== schema.elements.length) return false;
-        return schema.elements.every((elementSchema, index) =>
-          createValidator(elementSchema.schema)(value[index]),
-        );
-      case "array":
-        if (!Array.isArray(value)) return false;
-        return value.every((item) => createValidator(schema.element)(item));
-      case "reference":
-        if (schema.isOptional && value === null) return true;
-        if (schema.isArray) {
-          return (
-            Array.isArray(value) && value.every((id) => typeof id === "string")
-          );
-        }
-        return (
-          typeof value === "string" ||
-          (Array.isArray(value) && value.every((id) => typeof id === "string"))
-        );
-      case "reverseReference":
-        if (schema.isOptional && value === null) return true;
-        return Array.isArray(value);
-      default:
-        return false;
-    }
-  };
-}

src/value-parser.ts

@@ -0,0 +1,481 @@
+import type {
+  Schema,
+  TupleSchema,
+  ArraySchema,
+  ReferenceSchema,
+  StringLiteralSchema,
+  UnionSchema,
+} from "./types";
+import { ParseError } from "./parser";
+import { schemaToTypeString } from "./type-utils";
+
+class ValueParser {
+  private input: string;
+  private schemaString: string;
+  private pos: number = 0;
+
+  constructor(input: string, schemaString: string) {
+    this.input = input;
+    this.schemaString = schemaString;
+  }
+
+  private peek(): string {
+    return this.input[this.pos] || "";
+  }
+
+  private consume(): string {
+    return this.input[this.pos++] || "";
+  }
+
+  private skipWhitespace(): void {
+    while (this.pos < this.input.length && /\s/.test(this.input[this.pos])) {
+      this.pos++;
+    }
+  }
+
+  private consumeStr(str: string): boolean {
+    if (this.input.slice(this.pos, this.pos + str.length) === str) {
+      this.pos += str.length;
+      return true;
+    }
+    return false;
+  }
+
+  parseValue(schema: Schema): unknown {
+    this.skipWhitespace();
+
+    switch (schema.type) {
+      case "string":
+        return this.parseStringValue();
+      case "number":
+        return this.parseNumberValue();
+      case "int":
+        return this.parseIntValue();
+      case "float":
+        return this.parseFloatValue();
+      case "boolean":
+        return this.parseBooleanValue();
+      case "stringLiteral":
+        return this.parseStringLiteralValue(schema);
+      case "union":
+        return this.parseUnionValue(schema);
+      case "tuple":
+        return this.parseTupleValue(schema);
+      case "array":
+        return this.parseArrayValue(schema);
+      case "reference":
+        // Reference values are parsed as strings (IDs) initially, resolved later
+        return this.parseReferenceValue(schema);
+      case "reverseReference":
+        // Reverse references are derived fields, not stored in CSV cells
+        // They resolve to null at parse time; actual resolution happens in the loader
+        return null;
+      default:
+        throw new ParseError(
+          `Unknown schema type: ${(schema as { type: string }).type}`,
+          this.pos,
+          this.schemaString,
+          this.input,
+        );
+    }
+  }
+
+  private parseStringValue(): string {
+    let result = "";
+    while (this.pos < this.input.length) {
+      const char = this.peek();
+
+      if (char === "\\") {
+        this.consume();
+        const nextChar = this.consume();
+        if (
+          nextChar === ";" ||
+          nextChar === "[" ||
+          nextChar === "]" ||
+          nextChar === "\\"
+        ) {
+          result += nextChar;
+        } else {
+          result += "\\" + nextChar;
+        }
+      } else if (char === ";" || char === "]") {
+        break;
+      } else {
+        result += this.consume();
+      }
+    }
+    return result.trim();
+  }
+
+  private parseNumberValue(): number {
+    let numStr = "";
+    while (this.pos < this.input.length && /[\d.\-+eE]/.test(this.peek())) {
+      numStr += this.consume();
+    }
+    const num = parseFloat(numStr);
+    if (isNaN(num)) {
+      throw new ParseError(
+        "Invalid number",
+        this.pos - numStr.length,
+        this.schemaString,
+        this.input,
+      );
+    }
+    return num;
+  }
+
+  private parseIntValue(): number {
+    let numStr = "";
+    while (this.pos < this.input.length && /[\d.\-+eE]/.test(this.peek())) {
+      numStr += this.consume();
+    }
+    const num = parseFloat(numStr);
+    if (isNaN(num)) {
+      throw new ParseError(
+        "Invalid number",
+        this.pos - numStr.length,
+        this.schemaString,
+        this.input,
+      );
+    }
+    if (!Number.isInteger(num)) {
+      throw new ParseError(
+        "Expected integer value",
+        this.pos - numStr.length,
+        this.schemaString,
+        this.input,
+      );
+    }
+    return num;
+  }
+
+  private parseFloatValue(): number {
+    return this.parseNumberValue();
+  }
+
+  private parseBooleanValue(): boolean {
+    if (this.consumeStr("true")) {
+      return true;
+    }
+    if (this.consumeStr("false")) {
+      return false;
+    }
+    throw new ParseError(
+      "Expected true or false",
+      this.pos,
+      this.schemaString,
+      this.input,
+    );
+  }
+
+  private parseStringLiteralValue(schema: StringLiteralSchema): string {
+    const quote = this.peek();
+
+    // 支持带引号或不带引号的字符串值
+    if (quote === '"' || quote === "'") {
+      this.consume(); // Consume opening quote
+
+      let value = "";
+      while (this.pos < this.input.length) {
+        const char = this.peek();
+
+        if (char === "\\") {
+          this.consume();
+          const nextChar = this.consume();
+          if (
+            nextChar === '"' ||
+            nextChar === "'" ||
+            nextChar === "\\" ||
+            nextChar === ";"
+          ) {
+            value += nextChar;
+          } else {
+            value += "\\" + nextChar;
+          }
+        } else if (char === quote) {
+          this.consume(); // Consume closing quote
+
+          if (value !== schema.value) {
+            throw new ParseError(
+              `Invalid value '"${value}"'. Expected '"${schema.value}"'`,
+              this.pos,
+              this.schemaString,
+              this.input,
+            );
+          }
+
+          return value;
+        } else {
+          value += this.consume();
+        }
+      }
+
+      throw new ParseError(
+        "Unterminated string literal",
+        this.pos,
+        this.schemaString,
+        this.input,
+      );
+    } else {
+      // 不带引号的字符串，像普通字符串一样解析
+      let value = "";
+      while (this.pos < this.input.length) {
+        const char = this.peek();
+        if (char === ";" || char === "]" || char === ")") {
+          break;
+        }
+        value += this.consume();
+      }
+
+      value = value.trim();
+
+      if (value !== schema.value) {
+        throw new ParseError(
+          `Invalid value '${value}'. Expected '${schema.value}'`,
+          this.pos - value.length,
+          this.schemaString,
+          this.input,
+        );
+      }
+
+      return value;
+    }
+  }
+
+  private parseUnionValue(schema: UnionSchema): unknown {
+    const savedPos = this.pos;
+    const errors: Error[] = [];
+
+    // Try each union member until one succeeds
+    for (let i = 0; i < schema.members.length; i++) {
+      this.pos = savedPos;
+      try {
+        return this.parseValue(schema.members[i]);
+      } catch (e) {
+        errors.push(e as Error);
+        // Continue to next member
+      }
+    }
+
+    // If all members fail, throw a descriptive error
+    throw new ParseError(
+      `Value does not match any union member. Tried ${schema.members.length} alternatives.`,
+      this.pos,
+      this.schemaString,
+      this.input,
+    );
+  }
+
+  private parseTupleValue(schema: TupleSchema): unknown[] {
+    if (!this.consumeStr("[")) {
+      throw new ParseError(
+        "Expected [",
+        this.pos,
+        this.schemaString,
+        this.input,
+      );
+    }
+
+    this.skipWhitespace();
+
+    if (this.peek() === "]") {
+      this.consume();
+      return [];
+    }
+
+    const result: unknown[] = [];
+    for (let i = 0; i < schema.elements.length; i++) {
+      this.skipWhitespace();
+      const elementSchema = schema.elements[i];
+
+      // Try to consume optional name prefix (e.g., "current:")
+      if (elementSchema.name) {
+        this.skipWhitespace();
+        const savedPos = this.pos;
+        if (this.consumeStr(`${elementSchema.name}:`)) {
+          this.skipWhitespace();
+        } else {
+          // Name not found, reset position and continue without name
+          this.pos = savedPos;
+        }
+      }
+
+      result.push(this.parseValue(elementSchema.schema));
+      this.skipWhitespace();
+
+      if (i < schema.elements.length - 1) {
+        if (!this.consumeStr(";")) {
+          throw new ParseError(
+            "Expected ;",
+            this.pos,
+            this.schemaString,
+            this.input,
+          );
+        }
+      }
+    }
+
+    this.skipWhitespace();
+
+    if (!this.consumeStr("]")) {
+      throw new ParseError(
+        "Expected ]",
+        this.pos,
+        this.schemaString,
+        this.input,
+      );
+    }
+
+    return result;
+  }
+
+  private parseArrayValue(schema: ArraySchema): unknown[] {
+    if (this.pos >= this.input.length || !this.input.trim()) {
+      return [];
+    }
+
+    if (!this.consumeStr("[")) {
+      throw new ParseError(
+        "Expected [",
+        this.pos,
+        this.schemaString,
+        this.input,
+      );
+    }
+
+    this.skipWhitespace();
+
+    if (this.peek() === "]") {
+      this.consume();
+      return [];
+    }
+
+    const result: unknown[] = [];
+    while (true) {
+      this.skipWhitespace();
+
+      result.push(this.parseValue(schema.element));
+      this.skipWhitespace();
+
+      if (!this.consumeStr(";")) {
+        break;
+      }
+    }
+
+    this.skipWhitespace();
+
+    if (!this.consumeStr("]")) {
+      throw new ParseError(
+        "Expected ]",
+        this.pos,
+        this.schemaString,
+        this.input,
+      );
+    }
+
+    return result;
+  }
+
+  private parseReferenceValue(
+    schema: ReferenceSchema,
+  ): string | string[] | null {
+    if (schema.isOptional) {
+      this.skipWhitespace();
+      if (this.pos >= this.input.length) {
+        return null;
+      }
+    }
+
+    if (schema.isArray) {
+      // Parse array of IDs: [id1; id2; id3]
+      if (!this.consumeStr("[")) {
+        throw new ParseError(
+          "Expected [",
+          this.pos,
+          this.schemaString,
+          this.input,
+        );
+      }
+
+      this.skipWhitespace();
+
+      if (this.peek() === "]") {
+        this.consume();
+        return [];
+      }
+
+      const ids: string[] = [];
+      while (true) {
+        this.skipWhitespace();
+        // Parse each ID as a string
+        let id = "";
+        while (
+          this.pos < this.input.length &&
+          this.peek() !== ";" &&
+          this.peek() !== "]"
+        ) {
+          id += this.consume();
+        }
+        ids.push(id.trim());
+        this.skipWhitespace();
+
+        if (!this.consumeStr(";")) {
+          break;
+        }
+      }
+
+      this.skipWhitespace();
+
+      if (!this.consumeStr("]")) {
+        throw new ParseError(
+          "Expected ]",
+          this.pos,
+          this.schemaString,
+          this.input,
+        );
+      }
+
+      return ids;
+    } else {
+      // Parse single ID as string
+      let id = "";
+      while (this.pos < this.input.length) {
+        const char = this.peek();
+        if (char === ";" || char === "]" || char === ",") {
+          break;
+        }
+        id += this.consume();
+      }
+      return id.trim();
+    }
+  }
+
+  getPosition(): number {
+    return this.pos;
+  }
+
+  getInputLength(): number {
+    return this.input.length;
+  }
+}
+
+export function parseValue(
+  schema: Schema,
+  valueString: string,
+  schemaString?: string,
+): unknown {
+  const sStr = schemaString || schemaToTypeString(schema);
+  const parser = new ValueParser(valueString.trim(), sStr);
+  const value = parser.parseValue(schema);
+
+  if (parser.getPosition() < parser.getInputLength()) {
+    throw new ParseError(
+      "Unexpected input after value",
+      parser.getPosition(),
+      sStr,
+      valueString.trim(),
+    );
+  }
+
+  return value;
+}