Project

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:

"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.