ttsc 0.3.1 → 0.4.0-dev.20260424

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 sunrabbit123
+Copyright (c) 2026 Jeongho Nam
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,396 +1,310 @@
-# ttsc
+# `ttsc`
 
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/solar-religion/ttsc/blob/main/LICENSE)
-[![npm version](https://img.shields.io/npm/v/ttsc.svg)](https://www.npmjs.com/package/ttsc)
-[![Downloads](https://img.shields.io/npm/dm/ttsc.svg)](https://www.npmjs.com/package/ttsc)
+![banner of ttsc and ttsx](https://private-user-images.githubusercontent.com/13158709/583518390-6df1deb5-9e8c-4f4b-9d0f-eae1cc3bb55c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzcwNTQ2NzUsIm5iZiI6MTc3NzA1NDM3NSwicGF0aCI6Ii8xMzE1ODcwOS81ODM1MTgzOTAtNmRmMWRlYjUtOWU4Yy00ZjRiLTlkMGYtZWFlMWNjM2JiNTVjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MjQlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDI0VDE4MTI1NVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTEzMzUxNTE4YThlZDYyNDZjYTVjYmRiMmZiYzAwYzYyZTkyNDk4MjVlYmI4OGZkYjE3NDllNWQzY2IxNmRhYWEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9.7MYb2S99lZfQV-BqD09ZrZwdj1C3XDyJ9nkaSEr901M)
 
-This repository was created due to a perceived lack of management of `ttypescript`.
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/ttsc.svg)](https://www.npmjs.com/package/ttsc)
+[![NPM Downloads](https://img.shields.io/npm/dm/ttsc.svg)](https://www.npmjs.com/package/ttsc)
+[![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest)
 
-Also, we don't currently support `ts-node` and `cache systems`, as they weren't supported in the original, and we need time to figure out a way around that.
+A `typescript-go` compiler host for build-time transforms.
 
-And it supports TS5.
+- **Build and check**: run the project through the native TypeScript compiler lane.
+- **Transformer support**: load `compilerOptions.plugins` from `tsconfig.json`.
+- **Library author surface**: publish `ttsc` plugins with native backends or JS output hooks.
 
-[![npm version](https://badge.fury.io/js/ttypescript.svg)](https://badge.fury.io/js/ttypescript) [![Build Status](https://travis-ci.org/cevek/ttypescript.svg?branch=master)](https://travis-ci.org/cevek/ttypescript)
+`ttsc` is the compiler host used by `ttsx`. Use `ttsc` when you want one project-aware path for type checking, JavaScript emit, transformer loading, and native backend selection.
 
-# ttypescript
+## Setup
 
-## Existing contributors
+Install the native TypeScript preview package with `ttsc`:
 
--   @cevek
--   @zerkalica
--   @SalvatorePreviti
--   @timocov
--   @SlurpTheo
--   @samchon
--   @henriquehbr
--   @JiangWeixian
--   @mdmitry01
--   @jirutka
--   @alexgorbatchev
--   @oscard0m
--   @sveyret
--   @Jack-Works
--   @MicahZoltu
--   @Igorbek
--   @gfx
--   @danielpza
--   @mikeyhew
--   @huafu
--   @dsherret
--   @SupernaviX
--   @HitkoDev
-
-## What it is
-
-Currently TypeScript doesn't support custom transformers in the tsconfig.json, but supports it programmatically.
-
-And there is no way to compile your files using custom transformers using `tsc` command.
-
-TTypescript (Transformer TypeScript) solves this problem by patching on the fly the compile module to use transformers from `tsconfig.json`.
-
-<!---
-TTypescript is a drop-in replacement for all typescript modules, located in ``` node_modules/typescript/lib ``` directory:
-
-```ts
-import * as ts from 'ttypescript'
-import * as tsServer from 'ttypescript/lib/tsserver'
-import * as watchGuard from 'ttypescript/lib/watchGuard'
+```bash
+npm i -D ttsc @typescript/native-preview
 ```
---->
-
-Instead of tsc and tsserver, use ttsc and ttsserver wrappers. This wrappers try to use locally installed typescript first.
 
-No version lock-ins - typescript used as peer dependency.
+Build, check, or watch the project:
 
-## How to install
-
-```
-npm i ttypescript -D
+```bash
+npx ttsc
+npx ttsc --noEmit
+npx ttsc --watch
 ```
 
-ttypescript uses your installed `typescript` in your `node_modules`
+Transform a single file:
 
-## How to use
+```bash
+npx ttsc transform --file src/index.ts
+```
 
-### tsconfig.json
+## Transformer Configuration
 
-Set a transformer path to the `tsconfig.json` in `compilerOptions` section `plugin` array:
+`ttsc` reads `compilerOptions.plugins` from `tsconfig.json`.
 
-```
+```json
 {
-    "compilerOptions": {
-        "plugins": [
-            { "transform": "transformer-module" },
-        ]
-    }
-}
-```
-
-plugin entries described in `PluginConfig`:
-
-```ts
-export interface PluginConfig {
-    /**
-     * Path to transformer or transformer module name
-     */
-    transform?: string;
-
-    /**
-     * The optional name of the exported transform plugin in the transform module.
-     */
-    import?: string;
-
-    /**
-     * Plugin entry point format type, default is program
-     */
-    type?: 'program' | 'config' | 'checker' | 'raw' | 'compilerOptions';
-
-    /**
-     * Should transformer applied after all ones
-     */
-    after?: boolean;
-
-    /**
-     * Should transformer applied for d.ts files, supports from TS2.9
-     */
-    afterDeclarations?: boolean;
-    /**
-     * any other properties provided to the transformer as config argument
-     * */
-    [options: string]: any;
+  "compilerOptions": {
+    "plugins": [
+      { "transform": "typia/lib/transform" }
+    ]
+  }
 }
 ```
 
-You just need to add the `transform` block with optional `import`, `type`, `after`, `afterDeclarations` and plugin-related options.
-
-`transform` can accept npm module or local file path (.ts or .js) related to `tsconfig.json`
+The same configuration is used by `ttsc` and `ttsx`.
 
-### PluginConfig.type
+```bash
+# compile
+npx ttsc
 
-Because currently transformers can run only programmatically, most of them use factory wrapper with different signatures.
-For the possible to work with any of them you can specify `type` in the plugin config.
-
-By default will be used a `program` type.
-
-<!---
-
-Most of transformers exports ``` ts.TransformerFactory<ts.SourceFile> ```.
-But better to export TransformerBasePlugin, described below. In most cases it's a plugin responsibility to when run a transformer.
-
-```ts
-export interface TransformerBasePlugin {
-    before?: ts.TransformerFactory<ts.SourceFile>;
-    after?: ts.TransformerFactory<ts.SourceFile>;
-    afterDeclarations?: ts.TransformerFactory<ts.SourceFile>;
-}
-
-export type TransformerPlugin = TransformerBasePlugin | ts.TransformerFactory<ts.SourceFile>;
+# execute
+npx ttsx src/index.ts
 ```
---->
 
-#### program
+This gives compiler-powered libraries one transform path for build-time and runtime execution.
 
-If the transformer has a factory signature using `program` as first argument:
+## CLI
 
-```ts
-(program: ts.Program, config?: PluginConfig) => ts.TransformerFactory;
-where;
-ts.TransformerFactory = (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile;
+```bash
+ttsc [options]
+ttsc transform --file <path> [options]
+ttsc version
 ```
 
-Plugin config entry: `{ "transform": "transformer-module" }`.
-
-#### config
-
-For the signature with transformer's config:
+Common commands:
 
-```ts
-(config: PluginConfig) => ts.TransformerFactory;
+```bash
+ttsc
+ttsc -p tsconfig.json
+ttsc --noEmit
+ttsc --watch
+ttsc --outDir lib
+ttsc --verbose
+ttsc transform --file src/index.ts
+ttsc transform --file src/index.ts --out tmp/index.js
 ```
 
-Plugin config entry: `{ "transform": "transformer-module", type: "config" }`.
-
-#### checker
-
-For the signature with ts.TypeChecker:
-
-```ts
-(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory;
+Supported options:
+
+- `-p, --project <file>`: resolve project settings from this config file.
+- `--tsconfig <file>`: alias for an explicit project config file.
+- `--cwd <dir>`: resolve project-relative paths from another directory.
+- `--emit`: force emitted files during build.
+- `--noEmit`: type check and transform without writing emitted files.
+- `-w, --watch`: rebuild when project files change.
+- `--preserveWatchOutput`: keep watch output on screen.
+- `--outDir <dir>`: override `compilerOptions.outDir`.
+- `--rewrite-mode <mode>`: force a native rewrite backend id.
+- `--quiet`: keep native build output quiet.
+- `--verbose`: print the native build summary and emitted files.
+- `--out <path>`: write single-file transform output to a file.
+- `--binary <path>`: use an explicit native backend binary.
+
+Compatibility aliases:
+
+```bash
+ttsc build
+ttsc check
 ```
 
-Plugin config entry: `{ "transform": "transformer-module", type: "checker" }`.
+`ttsc build` is the same project build lane as `ttsc`. `ttsc check` is the same as `ttsc --noEmit`.
 
-#### raw
+## JS API
 
-For the signature without factory wrapper:
+`ttsc` exposes a small JS API for bundlers, runners, and higher-level tools.
 
 ```ts
-ts.TransformerFactory;
+import { build, check, transform, version } from "ttsc";
 ```
 
-Plugin config entry: `{ "transform": "transformer-module", type: "raw" }`.
-
-#### compilerOptions
+Transform one file:
 
 ```ts
-(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory;
-```
-
-Plugin config entry: `{ "transform": "transformer-module", type: "compilerOptions" }`.
+import { transform } from "ttsc";
 
-```json
-{
-    "compilerOptions": {
-        "plugins": [
-            { "transform": "transformer-module", "someOption1": 123, "someOption2": 321 },
-            { "transform": "./transformers/my-transformer.ts" },
-            { "transform": "transformer-module", "after": true },
-            { "transform": "transformer-module", "afterDeclarations": true },
-            { "transform": "transformer-module", "type": "ls" }
-        ]
-    }
-}
-```
-
-### Command line
-
-Like usual `tsc`, all arguments work the same way.
-
-```
-ttsc
+const code = transform({
+  cwd: "/project",
+  file: "/project/src/index.ts",
+  tsconfig: "/project/tsconfig.json",
+});
 ```
 
-### ts-node
+Build or check a project:
 
-```
-ts-node --compiler ttypescript index.ts
-or
-ts-node -C ttypescript index.ts
-```
-
-### Parcel
+```ts
+import { build, check } from "ttsc";
 
-Just install a parcel plugin
+const built = build({
+  cwd: process.cwd(),
+  tsconfig: "tsconfig.json",
+  emit: true,
+});
 
-```
-npm i parcel-plugin-ttypescript
-```
-
-### Webpack
-
-```js
-    {
-        test: /\.(ts|tsx)$/,
-        loader: require.resolve('awesome-typescript-loader'),
-        // or
-        loader: require.resolve('ts-loader'),
-        options: {
-            compiler: 'ttypescript'
-        }
-    }
-```
+if (built.status !== 0) {
+  console.error(built.stderr);
+}
 
-### Rollup
-
-```js
-// rollup.config.js
-import ttypescript from 'ttypescript';
-import tsPlugin from 'rollup-plugin-typescript2';
-
-export default {
-    // ...
-    plugins: [
-        // ...
-        tsPlugin({
-            typescript: ttypescript,
-        }),
-    ],
-};
+const checked = check({
+  tsconfig: "tsconfig.json",
+});
 ```
 
-### VS Code
-
-If you want to compile your project with VS Code task runner you need to overwrite the config `typescript.tsdk` to path of the installed `ttypescript`:
-
-```
-"typescript.tsdk": "/usr/local/lib/node_modules/ttypescript/lib",
-or
-"typescript.tsdk": "node_modules/ttypescript/lib",
-```
+`transform()` throws when the native compiler exits with an error. `build()` and `check()` return `{ status, stdout, stderr }`, so callers can decide how to surface compiler failures.
 
-### Jest, ts-jest
-
-```js
-module.exports = {
-    // [...]
-    globals: {
-        'ts-jest': {
-            compiler: 'ttypescript',
-        },
-    },
-};
-```
+## Transformer Library Authors
 
-or in `package.json`
+Transformer libraries publish a normal tsconfig plugin entry:
 
 ```json
 {
-    "jest": {
-        "globals": {
-            "ts-jest": {
-                "compiler": "ttypescript"
-            }
-        }
-    }
+  "compilerOptions": {
+    "plugins": [
+      { "transform": "my-lib/lib/transform" }
+    ]
+  }
 }
 ```
 
-## Transformers
+The `transform` value may be:
+
+- a package specifier.
+- an absolute path.
+- a relative path from the project root.
 
-You can use transformers written in ts or js
+The plugin module may export a plugin object directly, a default export, a `plugin` export, or a `createTtscPlugin` factory.
 
 ```ts
-// transformer1-module
-import * as ts from 'typescript';
-export default function (program: ts.Program, pluginOptions: {}) {
-    return (ctx: ts.TransformationContext) => {
-        return (sourceFile: ts.SourceFile) => {
-            function visitor(node: ts.Node): ts.Node {
-                // if (ts.isCallExpression(node)) {
-                //     return ts.createLiteral('call');
-                // }
-                return ts.visitEachChild(node, visitor, ctx);
-            }
-            return ts.visitEachChild(sourceFile, visitor, ctx);
-        };
-    };
-}
+import { definePlugin } from "ttsc";
+
+export default definePlugin((config, context) => ({
+  name: "my-lib",
+  native: {
+    mode: "my-lib",
+    binary: require.resolve("my-lib-native/bin/ttsc-my-lib.js"),
+    contractVersion: 1,
+    capabilities: ["rewrite", "diagnostics"],
+  },
+}));
 ```
 
-Examples of transformers:
-
-[`{ "transform": "ts-nameof", type: "raw"}`](https://github.com/dsherret/ts-nameof)
+The factory receives:
 
-[`{ "transform": "ts-optchain/transform" }`](https://github.com/rimeto/ts-optchain)
+- `config`: the raw `compilerOptions.plugins[]` entry.
+- `context.binary`: the fallback `ttsc` native binary path.
+- `context.cwd`: the invocation working directory.
+- `context.projectRoot`: the resolved project root.
+- `context.tsconfig`: the resolved config file path.
 
-[`{ "transform": "ts-transform-asset" }`](https://github.com/slune-org/ts-transform-asset)
+Keep this Node-side entry small. Use it for package discovery, feature flags, native binary selection, and manifest construction. Put compiler-sensitive work in the native backend.
 
-[`{ "transform": "ts-transform-auto-require" }`](https://github.com/slune-org/ts-transform-auto-require)
+## Native Backend Contract
 
-[`{ "transform": "ts-transform-css-modules/dist/transform", type: "config" }`](https://github.com/longlho/ts-transform-css-modules)
+A native transform plugin describes the backend that owns type analysis and rewrite work.
 
-[`{ "transform": "ts-transform-graphql-tag/dist/transformer" }`](https://github.com/firede/ts-transform-graphql-tag)
-
-[`{ "transform": "ts-transform-img/dist/transform", type: "config" }`](https://github.com/longlho/ts-transform-img)
+```ts
+import { definePlugin } from "ttsc";
+
+export default definePlugin(() => ({
+  name: "my-lib",
+  native: {
+    mode: "my-lib",
+    binary: require.resolve("my-lib-native/bin/ttsc-my-lib.js"),
+    contractVersion: 1,
+    capabilities: ["rewrite", "diagnostics", "assets"],
+  },
+}));
+```
 
-[`{ "transform": "ts-transform-react-intl/dist/transform", import: "transform", type: "config" }`](https://github.com/longlho/ts-transform-react-intl)
+Descriptor shape:
 
-[`{ "transform": "ts-transformer-enumerate/transformer" }`](https://github.com/kimamula/ts-transformer-enumerate)
+```ts
+interface TtscNativeBackend {
+  mode: string;
+  binary?: string;
+  contractVersion?: 1;
+  capabilities?: readonly string[];
+}
+```
 
-[`{ "transform": "ts-transformer-keys/transformer" }`](https://github.com/kimamula/ts-transformer-keys)
+- `mode` is the rewrite backend id passed to the native compiler process.
+- `binary` points at a consumer-owned native binary.
+- `contractVersion` pins the plugin to the current host protocol.
+- `capabilities` records the backend responsibilities.
 
-[`{ "transform": "ts-transformer-minify-privates" }`](https://github.com/timocov/ts-transformer-minify-privates)
+The backend is responsible for the work old TypeScript transformer libraries used to do through in-process compiler APIs:
 
-[`{ "transform": "typescript-is/lib/transform-inline/transformer" }`](https://github.com/woutervh-/typescript-is)
+- loading the project through the `typescript-go` lane.
+- finding marker calls such as `typia.is<T>()`.
+- analyzing types through native checker access or a serialized IR.
+- emitting replacement JavaScript.
+- reporting plugin-specific diagnostics.
+- emitting plugin-owned assets when needed.
 
-[`{ "transform": "typescript-plugin-styled-components", type: "config" }`](https://github.com/Igorbek/typescript-plugin-styled-components#ttypescript-compiler)
+## JS Output Hooks
 
-[`{ "transform": "typescript-transform-jsx" }`](https://github.com/LeDDGroup/typescript-transform-jsx)
+For text-level post-processing, a plugin can provide `transformOutput()`.
 
-[`{ "transform": "typescript-transform-macros" }`](https://github.com/LeDDGroup/typescript-transform-macros)
+```ts
+import { definePlugin } from "ttsc";
 
-[`{ "transform": "typescript-transform-paths" }`](https://github.com/LeDDGroup/typescript-transform-paths)
+export default definePlugin((config) => ({
+  name: "banner-plugin",
+  transformOutput(context) {
+    if (context.command === "build") {
+      return `/* generated by ${config.transform} */\n${context.code}`;
+    }
+    return context.code;
+  },
+}));
+```
 
-[`{ "transform": "@zerollup/ts-transform-paths" }`](https://github.com/zerkalica/zerollup/tree/master/packages/ts-transform-paths)
+`transformOutput()` receives JavaScript text after native emit. Use it for:
 
-[`{ "transform": "@zoltu/typescript-transformer-append-js-extension" }`](https://github.com/Zoltu/typescript-transformer-append-js-extension)
+- banner injection.
+- output string patching.
+- runtime helper import rewrites.
+- consumer-specific output normalization.
 
-[`{ "transform": "@magic-works/ttypescript-browser-like-import-transformer" }`](https://github.com/Jack-Works/ttypescript-browser-like-import-transformer)
+Use a native backend for compiler-sensitive work:
 
-[`{ "transform": "typescript-transform-react-jsx-source" }`](https://github.com/alexgorbatchev/typescript-transform-react-jsx-source)
+- type analysis.
+- AST mutation.
+- call-site recognition.
+- `ts.Program` / `ts.TypeChecker` transformer compatibility.
 
-[`{ "transform": "ts-transformer-remove-named-export" }`](https://github.com/dominguezcelada/ts-transformer-remove-named-export)
+## Current Constraints
 
-[`{ "transform": "ts-transformer-export-default-name" }`](https://github.com/jirutka/ts-transformer-export-default-name)
+These are current host constraints transformer authors should design around.
 
-[`{ "transform": "ts-transformer-inline-file/transformer" }`](https://github.com/jirutka/ts-transformer-inline-file)
+- One invocation can select one native `mode` / `binary` pair.
+- Multiple text-only `transformOutput()` plugins can run in order.
+- Passing `plugins` to the JS API replaces the tsconfig plugin list.
+- `transformOutput()` is a JS text hook, not a JS AST hook.
+- The current setup lane is `@typescript/native-preview`.
 
-[`{ "transform": "ts-transformer-strip-const-enums", "entrySourceFiles": ["./src/index.ts" }`](https://github.com/timocov/ts-transformer-strip-const-enums)
+## Integration Patterns
 
-[`{ "transform": "ts-transformer-properties-rename", "entrySourceFiles": ["./src/index.ts"] }`](https://github.com/timocov/ts-transformer-properties-rename)
+Consumer library:
 
-[`{ "transform": "tsc-progress", "name": "TSC", "color": "green" }`](https://github.com/JiangWeixian/tsc-progress)
+- publish a tsconfig plugin entry such as `my-lib/lib/transform`.
+- resolve a consumer-owned native backend binary from that entry.
+- keep type analysis and rewrite logic in the native backend.
+- optionally layer `transformOutput()` for final JavaScript text normalization.
 
-[Tutorial how to write a typescript transformer](https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943)
+Bundler adapter:
 
--   [Tutorial how to write a typescript transformer](https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943)
--   [Transformer framework](https://github.com/slune-org/simple-ts-transform)
--   [Unit testing transformer compiler](https://github.com/slune-org/ts-transform-test-compiler)
+- call `transform()` for per-file rewrites.
+- pass `plugins` when the adapter needs deterministic plugin state.
+- let `ttsc` resolve the native backend instead of spawning it manually.
 
-## Example
+Runner:
 
-An example project is in the [example](./packages/ttypescript-examples) directory
+- use `ttsx` for direct execution.
+- reuse the same `compilerOptions.plugins` contract.
+- keep build-time and runtime transform behavior aligned.
 
-## License
+## References
 
-MIT License
+- TypeScript runners: [`ts-node`](https://github.com/TypeStrong/ts-node) and [`tsx`](https://github.com/privatenumber/tsx)
+- Transformer tooling: [`ttypescript`](https://github.com/cevek/ttypescript) and [`ts-patch`](https://github.com/nonara/ts-patch)
+- Inspired by: [`typical`](https://github.com/samchon/typical) and [`tsgonest`](https://github.com/samchon/tsgonest)