project

---
name: project
description: Defines the typia product contract, workspace layout, package boundaries, and canonical commands. Use when orienting in the repository, working inside any package, or choosing a build, test, or format command.
---

# Project Outline

## Product Contract

Typia is a TypeScript transformer library built around one idea: a pure TypeScript type definition should replace the runtime helpers that other tools require schemas, decorators, or hand-written guards for. The compile-time transform reads those types and emits the runtime validator, serializer, schema, or decoder inline.

The packages:

- **`typia`**: the user-facing library and native transform. Exposes the runtime validators (`is`, `assert`, `assertGuard`, `validate`), enhanced JSON serde (`json.assertParse`, `json.assertStringify`, `json.schema`), LLM function-calling harness (`llm.application`, `llm.schema`, `llm.parse`, `llm.structuredOutput`, `llm.evaluation`), Protocol Buffer encoder/decoder (`protobuf.message`, `protobuf.assertEncode`, `protobuf.assertDecode`), and the random data generator (`random`).
- **`@typia/interface`**: shared public typings (e.g. `IJsonSchemaCollection`, `ILlmSchema`, `IValidation`) consumed by every other package and by user code.
- **`@typia/utils`**: runtime, OpenAPI, and LLM utility helpers (e.g. `LlmTypeChecker`) that live next to but outside the transform.
- **`@typia/langchain`**: LangChain.js integration that adapts typia's LLM harness to LangChain tools.
- **`@typia/mcp`**: Model Context Protocol integration.
- **`@typia/vercel`**: Vercel AI SDK integration.
- **`@typia/jev`**: Jev evaluation model integration, converting `llm.evaluation` questions to the Jev wire format.

Downstream projects (`@nestia/core`, `@agentica`, `@autobe`) build on top of typia but are not part of this repository's contract. The exported `typia.*` surface, the `@typia/interface` typings, and the `ttsc.plugin` descriptor shape are public; renaming or removing any of them is a deliberate, separate change.

A single Go program under `packages/typia/native` performs the compile-time transform that emits validators, stringifiers, schemas, and decoders in place of `typia.*<T>()` call sites. `packages/typia` registers a Go command package that `ttsc` (the TypeScript-Go compiler with native plugin support) compiles into a binary on first use through its plugin manifest:

```json
"ttsc": { "plugin": { "transform": "typia/lib/transform" } }
```

The `packages/typia/src/transform.ts` file is a plugin descriptor, not a transformer; there is no TypeScript-side transform anymore. The descriptor resolves the installed `typia` package root and returns the Go entrypoint under `native/cmd/ttsc-typia`. The adapter packages do not register their own transforms. Consumers reach the binary through `ttsc` / `ttsx` and the published descriptor. ttsc keys each plugin build by content and stores it workspace-wide under `node_modules/.cache/ttsc` (it walks up to `pnpm-workspace.yaml`), so every package and test workspace shares one binary.

## Layout

- `packages/*`: the published packages, including the shared Go plugin under `packages/typia/native`. Public and contract Go tests live under `packages/typia/test`; native Go tests are colocated throughout `packages/typia/native/**`. The test `go.work` resolves `ttsc` and its shims through `../node_modules/`, while the native development `go.work` resolves the sibling `ttsc` checkout.
- `tests/template`: `@typia/template`, a workspace package that ships the structure fixtures (`ObjectSimple`, `ArrayHierarchical`, ...) and the `TestServant` runtime helper consumed by the automated suites.
- `tests/test-*`: feature-test workspaces:
  - `test-typia-schema`, `test-langchain`, `test-mcp`, `test-vercel`, `test-jev`, `test-utils`: function-per-file suites under `src/features/**/test_*.ts`, each file exporting one matching `test_<snake_case>` function discovered by `DynamicExecutor` (from `@nestia/e2e`).
  - `test-utils`, `test-mcp`, `test-langchain`, `test-vercel`, and `test-jev` also hold portable cases under `src/unit/features/**/test_*.ts`, registered explicitly through `node:test` by `src/unit/index.ts` under `tsconfig.unit.json`, which has no native typia plugin. Their `start` runs the unit population before the integration population. Portable utility and adapter semantics belong in the unit population; preserve each exported case's inputs, assertions and failure identity when transferring it from a transformed suite.
  - `test-typia-automated`, `test-utils-automated`: generator-driven matrix suites over their configured typia operations and `@typia/template` structures; their generated `src/features/` trees are rebuilt by the suite.
  - `test-interface`: compile-time tests for exported `@typia/interface` types and public typia signatures; these cases execute no typia factory.
  - `test-error`: transform-rejection verification; the build must fail and every fixture must be named by a typia diagnostic.
- `tests/debug`: `@typia/debug`, a one-off `ttsx` runner for ad-hoc local repros.
- `benchmark/`: `@typia/benchmark`, performance generators with archived results under `benchmark/results/**`. See `.agents/skills/benchmark/SKILL.md`.
- `website/src/content/docs/**`: user-facing MDX guides published at https://typia.io/docs. See `.agents/skills/documentation/SKILL.md`.
- `examples/`, `experiments/`, `scripts/`, `config/`: example sources, tarball staging, repo utilities, and shared build configuration.

## Commands

CI uses Node 24.x and Go 1.26.x, while the workspace pins pnpm exactly to 10.6.4.

```bash
pnpm install
pnpm evidence
pnpm format
pnpm build
pnpm test
```

`pnpm test` runs every `tests/test-*` workspace through `pnpm test:packages`, then runs both Go trees through `pnpm test:toolchain`: `go -C packages/typia/test test ./...` and `go -C packages/typia/test test ../native/...`. It needs `go` on `PATH`. Run `pnpm install` first, or the test Go workspace cannot resolve `ttsc` and its shims through `../node_modules/`. Most feature workspaces execute TypeScript directly through `ttsx`; `test-error` uses a Node harness and `test-interface` invokes TypeScript `tsc --noEmit`. Plugin-building workspaces share the cache under `node_modules/.cache/ttsc`.

`pnpm evidence` checks every enrolled production owner, test feature function, and root tooling configuration without building or generating test matrices. Every enrolled `tests/*/evidence.config.json` selects exactly `src/features/**/test_*.ts` with `symbol: "function"`; unit populations, types, runners and support declarations are outside this selection while their ordinary execution remains intact. `pnpm evidence:packages` and `pnpm evidence:tests` check their enrolled workspace populations separately. The template and both automated test workspaces are not enrolled; their ordinary generation and test commands retain their behavioral coverage.

Release-time commands (most contributors skip these): `pnpm package:rc`, `pnpm package:next`, `pnpm package:latest`, and `pnpm release`. `pnpm package:tgz` stages local tarballs in `experiments/tarballs/` for offline testing. See `.agents/skills/pull-request/SKILL.md` for the remote delivery flow.

More agent context in samchon/typia

11 other files this repository gives its agents.