43 lines
3.0 KiB
Markdown
43 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
- **`inline-schema`** (`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
|
|
- `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
|
|
- `@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`.
|