Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (41 loc) · 2.35 KB

AGENTS.md

File metadata and controls

58 lines (41 loc) · 2.35 KB

Conformal — AGENTS.md

Agent-focused notes for safe, fast contributions. Format reference: agents.md.

Setup

npm i
npm run typecheck
npm run test

Examples:

cd examples/react && npm i && npm run dev
cd examples/svelte && npm i && npm run dev

Public API

  • conformal: getPath, setPath, decode, parseFormData, serialize, coerceString, coerceNumber, coerceBigint, coerceBoolean, coerceDate, coerceFile, coerceArray; types: PathsFromObject, Submission
  • conformal/valibot: coerceString, coerceNumber, coerceBoolean, coerceDate, coerceBigint, coerceFile, coerceArray (experimental)
  • conformal/zod: string, number, boolean, date, bigint, enum, file, url, email, object, array (deprecated)

Exports live in src/index.ts, src/valibot/index.ts, and src/zod/index.ts.

Non‑negotiable invariants

  • parseFormData is synchronous; throw TypeError("Schema validation must be synchronous") if schema returns a Promise.
  • setPath/getPath are immutable and prototype‑safe (block __proto__, constructor.prototype); support nested arrays/objects and sparse indices.
  • Submission always includes input; separate fieldErrors (dot/bracket paths, numeric indices in brackets) from formErrors.
  • serialize: number/bigint → .toString(), boolean → "on"/"" (configurable), Date → ISO via .toISOString().
  • Types InputValue<T> and PathsFromObject<T> must remain correct for nested structures and browser types.

Code style

  • TypeScript strict mode (see tsconfig.json flags).
  • ESM-only, isomorphic runtime (no Node-only APIs).
  • Prettier formatting: npm run format:write.
  • Keep runtime deps minimal; valibot is an optional peer dependency.

Build & test

# Fast local CI
npm run format:check && npm run typecheck && npm run test

# Focus tests
npx vitest run -t "<name>"      # by test name
npx vitest run test/parse.test.ts

Quick playbooks

  • Add a Valibot coercion pipe: edit src/valibot/coerce.ts, re-export in src/valibot/index.ts, add tests in test/valibot/coerce.test.ts, update README's Valibot section.
  • Fix path bug: add failing test in test/path.test.ts, update src/path.ts (immutability + guards), run full checks.
  • Public API change: update src/index.ts, tests, README; keep exports stable.