ArkType is TypeScript's smallest, fastest validator. It parses TypeScript-like string syntax at runtime.
- arktype.io/llms.txt indexes the docs (llmstxt.org format) with a link to each page's Markdown, and arktype.io/llms-full.txt is every ArkType page in one file. Precompile, ArkRegex, Attest, JSON Schema and Internals each have a full file at
arktype.io/docs/<section>/llms.txt, e.g. arktype.io/docs/regex/llms.txt. Any single page is at its URL plus.md. All of it is generated fromark/docs/content/docsbyark/docs/lib/writeMarkdown.ts. ark/type/skills/arktype/SKILL.mdis the Agent Skill users install withnpx skills add arktypeio/arktype. Keep its examples type-checking against the current API:pnpm testSkillchecks them. Itsreferences/migrating.mdis written from the docs'migrating.mdxwhen the docs build, so edit that page instead.- Precompile (
ark/docs/content/docs/precompile) is the reference for@ark/aot;ark/aot/README.mdonly points to it. - Every benchmark number or superlative the docs state lives in
ark/docs/lib/claims.ts, with the benchmark that backs it, except the homepage's own benchmark and Size at scale, whichark/docs/lib/benchcomputes from its data (sizeScale.tswrites that page's every number and comparison frompnpm benchSizeScale's). Don't state one elsewhere. - The cheat sheet (
ark/docs/content/docs/(arktype)/cheat-sheet.mdx) is an abbreviated version of the skill covering the most common syntax and gotchas.
pnpm i && pnpm build # install and build all packages
pnpm test # run tests without type checking
pnpm testFiles ark/type/__tests__/brand.test.ts # run and type check only the named test files
pnpm typecheckRepo # incremental typecheck of the whole repo
pnpm prChecks # lint, build, typecheck and test, except @ark/aot (run before PRs)
pnpm testAot # @ark/aot's tests, which prChecks leaves out, in up to eight shards at once
pnpm testAot --jobs 4 # in four shards at once; --jobs 1 runs them in one process
ARK_SHARD=3/8 pnpm testAot # the third of the eight shards CI runs them inTests and typechecking read each package's source through the ark-ts condition, so neither needs pnpm build. Pass test files to pnpm testFiles before any flags, e.g. pnpm testFiles a.test.ts --skipTypes. pnpm testTyped a.test.ts runs every test, because mocha adds named files to the configured spec.
pnpm testAot without ARK_SHARD runs half as many shards as there are cores, up to eight (one where CI is set), each in its own process with its own fixture directory (ARK_AOT_TEMP, under ark/aot/__tests__/temp) and attest cache (ATTEST_CACHE_DIR). It prints each failing shard's output whole, then the failing tests by shard. A fixture a test writes at a fixed path goes through tempPath() from ark/aot/__tests__/utils.ts, never fromHere("temp", ...), so concurrent shards don't overwrite each other's.
pr.yml runs on every PR, and its prChecks job is the gate. It runs three groups in parallel:
core: lint, docs build (with twoslash cache),pnpm testRepoWithBenchesandpnpm testJitless.typescript:attest@tsgoandrepo@6.0.3.aot:pnpm testAotin eight shards, one runner each.ark/repo/testAotShard.tsdeals the test files among them by the secondsark/aot/__tests__/timings.jsonhas for each, heaviest first, andpnpm testAot --listprints the result. A file without an entry weighs the median, so a new test file needs none. A file heavier than one shard's share has entries for its heavier top-leveldescribes and one for the rest of its tests, and is divided among shards by--grep; adescribeadded to it later runs with the rest. A shard that takes over twice the mean shard's planned seconds timesARK_SHARD_BUDGET_FACTOR(4 unless set) fails and says to runpnpm writeAotTimings, which runs the tests once and rewritestimings.json. Commit the result.
pr.yml also runs suggest (ark/repo/suggestCiSuites.ts) on non-fork PRs to post or update a single comment recommending relevant extended suites based on modified folders.
nightly.yml runs the extended suites offloaded from pr.yml — OS/Node compatibility (pnpm testRepoCompat), history (pnpm testHistory --jobs 4), full typescript version matrix, environments (Deno, Bun, Chrome, Firefox), and @ark/aot's derived suites (testDifferential, testCache, testPerturbation, testPrograms). It runs:
- nightly on
main. A failing night opens the issue "nightly failing", labellednightly, or comments on it, and the next passing night closes it. - on a PR labelled
aot:full,ci:compat,ci:history,ci:ts,ci:environmentsorci:all, when the label is added and on each push after. - on a PR when a maintainer comments
/run <suite...>(e.g./run aot:full ci:historyor/run all), viapr-commands.yml. - on demand from the Actions tab (
workflow_dispatch), and from another workflow throughworkflow_call.
ark/type: main validation library (arktypeon npm)ark/schema: schema layer (constraint nodes, refinements, scopes)ark/sets: the set algebra arktype reduces, relates and converts Types with, and the reader behindfromJsonSchema(arksets, internal and unpublished)ark/util: shared utilitiesark/docs: documentation site (Next.js)ark/aot: build-time precompilation of Types to standalone validators (@ark/aoton npm)ark/regex: ArkRegex type-safe regexark/attest: assertion/test libraryark/fast-check: property testing integration
Keywords follow typescriptType.constraint.subconstraint, e.g. string.email, number.integer, string.json.parse.
To add a regex string validator, add its English phrase to ark/type/keywords/phrases.ts under its flat alias (e.g. "string.email": "an email address") and its German one to ark/type/locales/de.ts, create it with regexStringNode(/^pattern$/, "string.alias") (patterns must be anchored), register it in the Scope.module() in ark/type/keywords/string.ts and add it to the namespace $ type. Other keyword nodes with authored text take their meta from keywordMeta(alias), so messages can find the phrase by meta.keyword.
To add a number keyword, use node("intersection", …) with a domain node and min/max, divisor or predicate nodes. See ark/type/keywords/number.ts.
- Tabs, no semicolons, no trailing commas (
prettierenforced) experimentalTernaries: true:?at end of line,:on next linearrowParens: "avoid":x => xnot(x) => x- Tests use
attestwith.snap()for snapshots