Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (58 loc) · 3.29 KB

AGENTS.md

File metadata and controls

75 lines (58 loc) · 3.29 KB
Raw

Agent Guidelines

This file is for coding agents working in the TypKit repository.

Project Snapshot

TypKit is a TypeScript ESM schema-validation library for Node 18+, Bun, and the browser. Schemas are built with the t builder by chaining constraints (t.int().min(1).max(5), primary) or with an equivalent config object — both compile to the identical validator, once, on first use, into a single monomorphic function via new Function. The surface is check / assert / parse, plus ['~standard'] (Standard Schema), toJsonSchema() (JSON Schema), and t.infer<> (inference). Framework helpers live in src/middleware/.

Development uses Bun for scripts and tests. There is no build engine and no required runtime dependency.

Core Rules

  • Zero happy-path allocation. Validators return 0 on success; error records and paths are built only on failure. Don't allocate on the success path.
  • Inline constraints only. Built-in rules emit literal expressions/loops, never closures. t.refine is the single, documented closure (slow path).
  • finite opt-in. t.number() allows NaN/Infinity by default (JSON-safe).
  • Discriminated unions dispatch O(1) through a switch on the tag.
  • Keep ['~standard'] and toJsonSchema() in sync with every node change.
  • Cross-runtime (src/ runs on Node 18+, Bun, browser); Standard Schema type is vendored. Keep strict TypeScript and ESLint intact. No console.* in the core.
  • Don't revert or overwrite unrelated user changes.

Repository Map

  • src/index.ts — package exports (barrel).
  • src/typkit.ts — the t builder + t.infer namespace.
  • src/compiler.ts — Emitter codegen + lazily-compiled TypeNode base.
  • src/nodes/ — scalars.ts, object.ts, array.ts, union.ts, modifiers.ts.
  • src/constraints/ — string / number / array inline emitters.
  • src/formats.ts — precompiled format regexes.
  • src/coerce.ts — query-param coercion nodes.
  • src/json-schema.ts, src/standard-schema.ts, src/errors.ts, src/infer.ts.
  • src/middleware/ — Elysia / Hono / tRPC helpers + shared.ts.
  • docs/*.md — guide, api, constraints, frameworks, json-schema, comparison.
  • examples/, bench.ts — bench-results.md is auto-generated by bench.ts.

Style

  • TypeScript strict. Tabs, single quotes, semicolons. const by default.
  • camelCase values, PascalCase types/classes, UPPER_SNAKE_CASE constants, kebab-case files. ESM with explicit .js specifiers.
  • any only at the codegen/runtime boundary (emitted JS, middleware contexts).
  • Focused comments that explain non-obvious codegen.

Testing And Checks

bun run typecheck
bun run lint
bun run test
bun test src/constraints.test.ts   # targeted

Add *.test.ts next to non-trivial logic. A constraint or node change needs a test covering valid/invalid behavior and the resulting issue path.

Documentation Rules

  • Public API changes: update README.md and docs/.
  • Constraint/format changes: update docs/constraints.md.
  • Performance claims: cite only bench-results.md and re-run bun run bench.
  • Don't create new Markdown files unless requested or clearly needed.

Contribution Metadata

Follow CONTRIBUTING.md for branch names, commit messages, and PR descriptions. Repository-facing text must be in English.