Project

Project Outline

Product Contract

Nestia is a set of NestJS helper libraries built around one idea: a pure TypeScript type definition should replace the stack of decorators, validators, transformers, and Swagger annotations that NestJS normally needs. The compile-time transform reads those types and injects everything else.

All eight packages publish from packages/* at one shared version and move together on release:

• @nestia/core: typed request/response decorators for NestJS controllers (TypedRoute, TypedBody, TypedParam, TypedQuery, TypedFormData, TypedHeaders, TypedException, WebSocketRoute, McpRoute, and the Swagger customizers). Replaces class-validator and class-transformer with type-driven validation and serialization. Owns the shared Go transform under native/.
• @nestia/sdk: generators for Swagger documents, typed SDK libraries, mockup simulators, and automatic e2e suites, driven by the nestia CLI. Its Go code under native/sdk is a contributor linked into the @nestia/core host binary, not a second plugin. website/src/content/docs/setup.mdx documents it as a runtime dependency, not a dev dependency: the Go binary must resolve it, and NestiaSwaggerComposer consumers need it at runtime anyway.
• @nestia/fetcher: the typed fetch runtime that generated SDKs sit on. Plain and AES-encrypted variants, with simulation support for mockup mode.
• @nestia/migrate: converts a Swagger/OpenAPI document into a NestJS project or SDK. Generated templates ship without interactive dependencies.
• @nestia/e2e: test utilities for hand-written and generated e2e suites. DynamicExecutor discovers test functions by prefix; TestValidator, ArrayUtil, and RandomGenerator are the shared assertion and data helpers.
• @nestia/benchmark: a published load-test runner (DynamicBenchmarker) that drives e2e functions and emits markdown reports for a user's own server.
• @nestia/editor: Swagger UI with an embedded cloud TypeScript editor, shipped as both a static app and a NestiaEditorModule library.
• nestia: the CLI binary that drives @nestia/sdk.

Downstream projects (@agentica, @autobe) build on this stack but are not part of this repository's contract.

Decorator names, INestiaConfig options, CLI flags, the @nestia/fetcher runtime surface, and the generated SDK / Swagger / e2e output are all public. Renaming or removing any of them is a deliberate, separate change.

How The Transform Composes

A single Go binary performs the compile-time transform that injects validators, stringifiers, and SDK metadata. There is no TypeScript-side transformer, and reintroducing one is out of bounds.

packages/core/package.json is the only package that registers a ttsc plugin:

"ttsc": { "plugin": { "transform": "@nestia/core/native/transform.cjs" } }

That manifest target, packages/core/native/transform.cjs, is the operative descriptor. It declares three things:

• source: the Go entrypoint at <@nestia/core root>/native/cmd/ttsc-nestia, which ttsc compiles into a binary on first use.
• composes: ["typia/lib/transform"]: the typia transform is composed in rather than reimplemented.
• contributors: <@nestia/sdk root>/native/sdk, resolved and added only when @nestia/sdk is resolvable from the consuming project.

@nestia/core/lib/transform, the plugin path nestia v11 documented, is exported as the same native/transform.cjs file, so a v11 plugin list resolves to this one descriptor and ttsc's package auto-discovery deduplicates it; a descriptor of its own built a second native host beside the composed typia entry and failed the build (#1690). packages/sdk/src/transform.ts is also a plugin descriptor, not a transformer: it resolves its installed package root through createRequire(...).resolve("@nestia/sdk/package.json") and returns the Go entrypoint. packages/sdk deliberately has no ttsc key: its Go source is package sdk, a non-main package that ttsc statically links into the core host binary. Adding a second plugin entry for @nestia/sdk is a misconfiguration for new projects, as the plugin descriptor and compatibility tests establish; the SDK's linked plugin still honors such an entry from a v11 plugin list and attaches SDK metadata in every build, as v11 did.

Consumers reach the binary through ttsc / ttsx and the published descriptors. TypeScript test workspace entries use cross-env to carry the NODE_OPTIONS="--no-experimental-strip-types --no-experimental-detect-module" that Node 24 needs. The Evidence process suite runs plain Node.

Canonical test commands and independently invoked SDK and migration integrations resolve TTSC_CACHE_DIR and TTSC_GO_CACHE_DIR against the repository root before changing workspaces. Defaults use node_modules/.cache/ttsc and its go-build child for native plugins and Go units; explicit GOCACHE and toolchain settings retain caller ownership. Go's own toolchain and input keys govern object reuse. Unit entries consume already-built package artifacts. SDK and migration integration entries own their necessary consumer, compiler and runtime connections; tests/test-e2e contains only direct units of packages/e2e. Test-language preparation is recorded separately from integration preparation.

Layout

• packages/*: the eight published packages. The shared Go plugin lives under packages/core/native (module github.com/samchon/nestia/packages/core/native, with cmd/ttsc-nestia and the transform/ tree); the SDK contributor lives under packages/sdk/native/sdk. Both native/go.work files carry the same fifteen replace directives: fourteen redirect the github.com/microsoft/typescript-go/shim/* modules to a pinned github.com/samchon/ttsc pseudo-version, and the fifteenth redirects github.com/samchon/ttsc/packages/ttsc itself.
• packages/core/test and packages/sdk/test: the Go unit-test modules, each its own module — core's replaces ../native, the SDK's replaces both ../native and ../../core/native. Native production trees carry no test files. Emitted-validator execution against installed runtimes belongs to SDK integration; pure option and provenance decisions belong to the native unit modules.
• tests/test-*: the workspaces are test-benchmark, test-cli, test-e2e, test-editor, test-migrate and test-sdk. test-e2e owns only direct packages/e2e units. SDK and migration workspaces separate direct units from necessary integration execution; the retired transform-options workspace's portable decisions belong to Go units and its installed boundaries share SDK preparation. See development for actual-call-path classification and assertion-preservation rules.
• tests/config/tsconfig.json: the shared strict base config. Pure unit workspaces and the integrated E2E fixture extend it at their actual relative depth. Not a package.
• config/: @nestia/config, the private workspace holding shared rolldown and tsconfig build configuration and test artifact/cache preparation under testing/.
• benchmark/: @samchon/nestia-benchmark, the private measurement workspace, with committed per-CPU results under benchmark/results/**. See .agents/skills/benchmark/SKILL.md.
• website/: the Nextra site published at https://nestia.io, with guides under website/src/content/docs/**. See .agents/skills/documentation/SKILL.md.
• deploy/: release scripts — tarballs/index.js (topologically ordered pnpm pack) and copy-readme.cjs (copies the root README into every packages/* directory; root package:prepare runs it after the full build).