Files

T

hypercross c969c7f6fc refactor: enforce mandatory brackets for composite values

Implements Phase 1 and 2 of the syntax rework plan:
- Brackets `[]` are now mandatory for all tuple and array values.
- Removed the `[Type][]` array syntax; arrays now only use `Type[]`.
- `[single]` is now strictly a 1-tuple rather than an array.
- Updated documentation and test fixtures to reflect these breaking
  changes.

2026-08-06 09:19:39 +08:00

3.1 KiB

Raw Blame History

AGENTS.md

Commands

Build: npm run build (tsup, CJS + ESM + d.ts for all entry points)
Test: npm run test (vitest run) | npm run test:watch (vitest watch)
Type check: npm run typecheck
Run a single test: npx vitest run -t "test name pattern"

No linter or formatter is configured. No CI pipeline exists.

Architecture

Single-package TypeScript library with two runtime entry points:

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
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

Build produces separate bundles per entry point (see tsup.config.ts). The csv-loader entries externalize csv-parse, @rspack/core, esbuild, and rollup.

Key conventions

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
References can appear nested inside tuples, arrays, and unions; the loader resolves them recursively

Gotchas

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).
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.