ttsc 0.3.1 → 0.4.0-dev.20260425

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,127 @@
-# 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](https://raw.githubusercontent.com/samchon/ttsc/refs/heads/master/assets/og.jpg)
 
-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` toolchain for compiler-powered transforms and type-safe execution.
 
-And it supports TS5.
+- **`ttsc`**: build, check, and transform.
+- **`ttsx`**: execute TypeScript with type checking.
+  - 10x faster than `ts-node`.
+  - type checking that `tsx` does not provide.
+- **transformer support**: compiler-powered libraries, such as `typia`.
 
-[![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)
+> `ttsx` (CLI command) can run existing `typescript@6` projects.
 
-# ttypescript
+## Setup
 
-## Existing contributors
-
--   @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'
-```
---->
-
-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.
-
-## How to install
+Install the native TypeScript preview package with `ttsc`:
 
+```bash
+npm i -D ttsc @typescript/native-preview
 ```
-npm i ttypescript -D
-```
-
-ttypescript uses your installed `typescript` in your `node_modules`
-
-## How to use
-
-### tsconfig.json
 
-Set a transformer path to the `tsconfig.json` in `compilerOptions` section `plugin` array:
+Run TypeScript directly with `ttsx` (CLI command):
 
+```bash
+npx ttsx src/index.ts
 ```
-{
-    "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;
+Build, check, or watch the project with `ttsc`:
 
-    /**
-     * 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;
-}
+```bash
+npx ttsc
+npx ttsc --noEmit
+npx ttsc --watch
 ```
 
-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`
-
-### PluginConfig.type
-
-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>;
-```
---->
-
-#### program
-
-If the transformer has a factory signature using `program` as first argument:
-
-```ts
-(program: ts.Program, config?: PluginConfig) => ts.TransformerFactory;
-where;
-ts.TransformerFactory = (context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile;
-```
-
-Plugin config entry: `{ "transform": "transformer-module" }`.
-
-#### config
-
-For the signature with transformer's config:
-
-```ts
-(config: PluginConfig) => ts.TransformerFactory;
-```
-
-Plugin config entry: `{ "transform": "transformer-module", type: "config" }`.
-
-#### checker
-
-For the signature with ts.TypeChecker:
-
-```ts
-(checker: ts.TypeChecker, config?: PluginConfig) => ts.TransformerFactory;
-```
-
-Plugin config entry: `{ "transform": "transformer-module", type: "checker" }`.
-
-#### raw
-
-For the signature without factory wrapper:
-
-```ts
-ts.TransformerFactory;
-```
-
-Plugin config entry: `{ "transform": "transformer-module", type: "raw" }`.
-
-#### compilerOptions
-
-```ts
-(compilerOpts: ts.CompilerOptions, config?: PluginConfig) => ts.TransformerFactory;
-```
+## Transformer Configuration
 
-Plugin config entry: `{ "transform": "transformer-module", type: "compilerOptions" }`.
+`ttsc` reads `compilerOptions.plugins` from `tsconfig.json`.
 
 ```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" }
-        ]
-    }
+  "compilerOptions": {
+    "plugins": [
+      { "transform": "typia/lib/transform" }
+    ]
+  }
 }
 ```
 
-### Command line
-
-Like usual `tsc`, all arguments work the same way.
-
-```
-ttsc
-```
-
-### ts-node
-
-```
-ts-node --compiler ttypescript index.ts
-or
-ts-node -C ttypescript index.ts
-```
-
-### Parcel
-
-Just install a parcel plugin
-
-```
-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'
-        }
-    }
-```
-
-### Rollup
-
-```js
-// rollup.config.js
-import ttypescript from 'ttypescript';
-import tsPlugin from 'rollup-plugin-typescript2';
-
-export default {
-    // ...
-    plugins: [
-        // ...
-        tsPlugin({
-            typescript: ttypescript,
-        }),
-    ],
-};
-```
-
-### 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",
-```
+The same configuration is used by both `ttsc` commands.
 
-### Jest, ts-jest
+```bash
+# compile
+npx ttsc
 
-```js
-module.exports = {
-    // [...]
-    globals: {
-        'ts-jest': {
-            compiler: 'ttypescript',
-        },
-    },
-};
+# execute
+npx ttsx src/index.ts
 ```
 
-or in `package.json`
-
-```json
-{
-    "jest": {
-        "globals": {
-            "ts-jest": {
-                "compiler": "ttypescript"
-            }
-        }
-    }
-}
-```
+This gives compiler-powered libraries one transform path for both build-time and runtime execution.
 
-## Transformers
+## What Is a Transform?
 
-You can use transformers written in ts or js
+A transform uses TypeScript types to generate JavaScript before runtime.
 
 ```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 typia, { tags } from "typia";
+import { v4 } from "uuid";
+
+const matched: boolean = typia.is<IMember>({
+  id: v4(),
+  email: "samchon.github@gmail.com",
+  age: 30,
+});
+console.log(matched); // true
+
+interface IMember {
+  id: string & tags.Format<"uuid">;
+  email: string & tags.Format<"email">;
+  age: number &
+    tags.Type<"uint32"> &
+    tags.ExclusiveMinimum<19> &
+    tags.Maximum<100>;
 }
 ```
 
-Examples of transformers:
-
-[`{ "transform": "ts-nameof", type: "raw"}`](https://github.com/dsherret/ts-nameof)
-
-[`{ "transform": "ts-optchain/transform" }`](https://github.com/rimeto/ts-optchain)
-
-[`{ "transform": "ts-transform-asset" }`](https://github.com/slune-org/ts-transform-asset)
-
-[`{ "transform": "ts-transform-auto-require" }`](https://github.com/slune-org/ts-transform-auto-require)
-
-[`{ "transform": "ts-transform-css-modules/dist/transform", type: "config" }`](https://github.com/longlho/ts-transform-css-modules)
-
-[`{ "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)
-
-[`{ "transform": "ts-transform-react-intl/dist/transform", import: "transform", type: "config" }`](https://github.com/longlho/ts-transform-react-intl)
-
-[`{ "transform": "ts-transformer-enumerate/transformer" }`](https://github.com/kimamula/ts-transformer-enumerate)
-
-[`{ "transform": "ts-transformer-keys/transformer" }`](https://github.com/kimamula/ts-transformer-keys)
-
-[`{ "transform": "ts-transformer-minify-privates" }`](https://github.com/timocov/ts-transformer-minify-privates)
-
-[`{ "transform": "typescript-is/lib/transform-inline/transformer" }`](https://github.com/woutervh-/typescript-is)
-
-[`{ "transform": "typescript-plugin-styled-components", type: "config" }`](https://github.com/Igorbek/typescript-plugin-styled-components#ttypescript-compiler)
-
-[`{ "transform": "typescript-transform-jsx" }`](https://github.com/LeDDGroup/typescript-transform-jsx)
-
-[`{ "transform": "typescript-transform-macros" }`](https://github.com/LeDDGroup/typescript-transform-macros)
-
-[`{ "transform": "typescript-transform-paths" }`](https://github.com/LeDDGroup/typescript-transform-paths)
-
-[`{ "transform": "@zerollup/ts-transform-paths" }`](https://github.com/zerkalica/zerollup/tree/master/packages/ts-transform-paths)
-
-[`{ "transform": "@zoltu/typescript-transformer-append-js-extension" }`](https://github.com/Zoltu/typescript-transformer-append-js-extension)
-
-[`{ "transform": "@magic-works/ttypescript-browser-like-import-transformer" }`](https://github.com/Jack-Works/ttypescript-browser-like-import-transformer)
-
-[`{ "transform": "typescript-transform-react-jsx-source" }`](https://github.com/alexgorbatchev/typescript-transform-react-jsx-source)
-
-[`{ "transform": "ts-transformer-remove-named-export" }`](https://github.com/dominguezcelada/ts-transformer-remove-named-export)
-
-[`{ "transform": "ts-transformer-export-default-name" }`](https://github.com/jirutka/ts-transformer-export-default-name)
-
-[`{ "transform": "ts-transformer-inline-file/transformer" }`](https://github.com/jirutka/ts-transformer-inline-file)
-
-[`{ "transform": "ts-transformer-strip-const-enums", "entrySourceFiles": ["./src/index.ts" }`](https://github.com/timocov/ts-transformer-strip-const-enums)
-
-[`{ "transform": "ts-transformer-properties-rename", "entrySourceFiles": ["./src/index.ts"] }`](https://github.com/timocov/ts-transformer-properties-rename)
-
-[`{ "transform": "tsc-progress", "name": "TSC", "color": "green" }`](https://github.com/JiangWeixian/tsc-progress)
-
-[Tutorial how to write a typescript transformer](https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943)
-
--   [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)
-
-## Example
-
-An example project is in the [example](./packages/ttypescript-examples) directory
-
-## License
-
-MIT License
+It is transformed into dedicated JavaScript:
+
+> ```js
+> import typia from "typia";
+> import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail";
+> import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid";
+> import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32";
+> import { v4 } from "uuid";
+>
+> const matched = (() => {
+>   const _io0 = (input) =>
+>     "string" === typeof input.id &&
+>     __typia_transform__isFormatUuid._isFormatUuid(input.id) &&
+>     "string" === typeof input.email &&
+>     __typia_transform__isFormatEmail._isFormatEmail(input.email) &&
+>     "number" === typeof input.age &&
+>     __typia_transform__isTypeUint32._isTypeUint32(input.age) &&
+>     19 < input.age &&
+>     input.age <= 100;
+>   return (input) => "object" === typeof input && null !== input && _io0(input);
+> })()({
+>   id: v4(),
+>   email: "samchon.github@gmai19l.com",
+>   age: 30,
+> });
+> console.log(matched); // true
+> ```
+
+`ttsc` runs this transform during build, and `ttsx` runs through the same transform path during execution.
+
+## References
+
+- 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/elliots/typical) and [`tsgonest`](https://github.com/tsgonest/tsgonest)

package/cmd/ttsc/build.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// runBuild implements the `ttsc` project-build lane. Two modes:
+//
+//   - default (dry run): analyze quietly, surfacing only diagnostics/errors.
+//   - --emit: also run tsgo's emit pipeline, patching every recognized native
+//     consumer call in the resulting .js files.
+func runBuild(args []string) int {
+	fs := flag.NewFlagSet("build", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
+	cwdOverride := fs.String("cwd", "", "override the working directory (defaults to process cwd)")
+	quiet := fs.Bool("quiet", true, "suppress the per-call diagnostic summary")
+	verbose := fs.Bool("verbose", false, "print the per-call diagnostic summary")
+	emit := fs.Bool("emit", false, "force emitted .js files (runs tsgo + ttsc rewrite)")
+	noEmit := fs.Bool("noEmit", false, "force analysis-only run with no file writes")
+	outDir := fs.String("outDir", "", "override compilerOptions.outDir for this build")
+	manifestPath := fs.String("manifest", "", "write emitted file list as JSON to this path")
+	rewriteMode := fs.String("rewrite-mode", "none", "native rewrite backend id")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+	if *emit && *noEmit {
+		fmt.Fprintln(stderr, "ttsc: --emit and --noEmit are mutually exclusive")
+		return 2
+	}
+	if *verbose {
+		*quiet = false
+	}
+
+	cwd := *cwdOverride
+	if cwd == "" {
+		var err error
+		cwd, err = os.Getwd()
+		if err != nil {
+			fmt.Fprintf(stderr, "ttsc: could not get working directory: %v\n", err)
+			return 2
+		}
+	}
+
+	prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
+		ForceEmit:   *emit,
+		ForceNoEmit: *noEmit,
+		OutDir:      *outDir,
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc: %v\n", err)
+		return 2
+	}
+	if len(diags) > 0 {
+		driver.WritePrettyDiagnostics(stderr, diags, cwd)
+		return 2
+	}
+	defer prog.Close()
+	if diags := prog.Diagnostics(); len(diags) > 0 {
+		driver.WritePrettyDiagnostics(stderr, diags, cwd)
+		return 2
+	}
+
+	rewrites := driver.NewRewriteSet()
+	shouldEmit := !prog.ParsedConfig.ParsedConfig.CompilerOptions.NoEmit.IsTrue()
+	if *rewriteMode != "none" {
+		fmt.Fprintf(stderr, "ttsc: rewrite backend %q is not built into the standalone ttsc binary\n", *rewriteMode)
+		fmt.Fprintln(stderr, "ttsc: run through the JS host with the matching compiler plugin so it can select the consumer-provided native binary")
+		return 2
+	}
+	if !*quiet {
+		fmt.Fprintf(stdout, "// ttsc: tsconfig=%s cwd=%s sites=%d emit=%v rewrite=%s\n", *tsconfigPath, cwd, 0, shouldEmit, *rewriteMode)
+	}
+
+	if shouldEmit {
+		writeFile := shimcompiler.WriteFile(
+			func(fileName, text string, _ *shimcompiler.WriteFileData) error {
+				return driver.DefaultWriteFile(fileName, text)
+			},
+		)
+		res, eDiags, err := prog.EmitAll(rewrites, writeFile)
+		if err != nil {
+			fmt.Fprintf(stderr, "ttsc: emit failed: %v\n", err)
+			return 3
+		}
+		for _, d := range eDiags {
+			fmt.Fprintln(stderr, "  -", d.String())
+		}
+		if !*quiet {
+			fmt.Fprintf(stdout, "// ttsc: emitted=%d files\n", len(res.EmittedFiles))
+			for _, f := range res.EmittedFiles {
+				rel := f
+				if abs, err := filepath.Rel(cwd, f); err == nil {
+					rel = abs
+				}
+				fmt.Fprintln(stdout, "  +", rel)
+			}
+		}
+		if *manifestPath != "" {
+			data, err := json.Marshal(res.EmittedFiles)
+			if err != nil {
+				fmt.Fprintf(stderr, "ttsc: manifest marshal failed: %v\n", err)
+				return 3
+			}
+			if err := os.MkdirAll(filepath.Dir(*manifestPath), 0o755); err != nil {
+				fmt.Fprintf(stderr, "ttsc: manifest mkdir failed: %v\n", err)
+				return 3
+			}
+			if err := os.WriteFile(*manifestPath, data, 0o644); err != nil {
+				fmt.Fprintf(stderr, "ttsc: manifest write failed: %v\n", err)
+				return 3
+			}
+		}
+	}
+
+	if !*quiet {
+		fmt.Fprintf(stdout, "// ttsc: recognized=%d total=%d rewrites=%d\n", 0, 0, rewrites.Len())
+	}
+	return 0
+}