inline-schema/AGENTS.md

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