@ttsc/unplugin 0.8.0

package/README.md

@@ -0,0 +1,286 @@
+# `@ttsc/unplugin`
+
+![banner of @ttsc/unplugin](https://raw.githubusercontent.com/samchon/ttsc/refs/heads/master/assets/og.jpg)
+
+[![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/unplugin.svg)](https://www.npmjs.com/package/@ttsc/unplugin)
+[![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/unplugin.svg)](https://www.npmjs.com/package/@ttsc/unplugin)
+[![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest)
+[![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://github.com/samchon/ttsc/tree/master/docs)
+[![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
+
+Bundler adapter for `ttsc` plugins.
+
+Use it when Vite, Rollup, esbuild, Webpack, Rspack, Next.js, Farm, or Bun should run the same `compilerOptions.plugins` entries that `ttsc` and `ttsx` use.
+
+## Setup
+
+Install `ttsc` and TypeScript-Go first. Then install the bundler adapter:
+
+```bash
+npm install -D ttsc @typescript/native-preview
+npm install -D @ttsc/unplugin
+```
+
+Choose your bundler and add the adapter.
+
+### Vite
+
+```ts
+// vite.config.ts
+import ttsc from "@ttsc/unplugin/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [ttsc()],
+});
+```
+
+### Rollup
+
+```ts
+// rollup.config.ts
+import ttsc from "@ttsc/unplugin/rollup";
+
+export default {
+  input: "src/index.ts",
+  output: {
+    dir: "dist",
+    format: "esm",
+  },
+  plugins: [ttsc()],
+};
+```
+
+### Rolldown
+
+```ts
+// rolldown.config.ts
+import ttsc from "@ttsc/unplugin/rolldown";
+
+export default {
+  input: "src/index.ts",
+  output: {
+    dir: "dist",
+    format: "esm",
+  },
+  plugins: [ttsc()],
+};
+```
+
+### esbuild
+
+```ts
+// esbuild.config.ts
+import { build } from "esbuild";
+import ttsc from "@ttsc/unplugin/esbuild";
+
+await build({
+  entryPoints: ["src/index.ts"],
+  outdir: "dist",
+  bundle: true,
+  plugins: [ttsc()],
+});
+```
+
+### Webpack
+
+```js
+// webpack.config.cjs
+const ttsc = require("@ttsc/unplugin/webpack").default;
+
+module.exports = {
+  entry: "./src/index.ts",
+  output: {
+    path: `${__dirname}/dist`,
+  },
+  plugins: [ttsc()],
+};
+```
+
+### Rspack
+
+```js
+// rspack.config.cjs
+const ttsc = require("@ttsc/unplugin/rspack").default;
+
+module.exports = {
+  entry: "./src/index.ts",
+  plugins: [ttsc()],
+};
+```
+
+### Next.js
+
+```js
+// next.config.mjs
+import withTtsc from "@ttsc/unplugin/next";
+
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+export default withTtsc(nextConfig);
+```
+
+### Farm
+
+```ts
+// farm.config.ts
+import ttsc from "@ttsc/unplugin/farm";
+import { defineConfig } from "@farmfe/core";
+
+export default defineConfig({
+  plugins: [ttsc()],
+});
+```
+
+### Bun
+
+```ts
+// build.ts
+import ttsc from "@ttsc/unplugin/bun";
+
+await Bun.build({
+  entrypoints: ["src/index.ts"],
+  outdir: "dist",
+  plugins: [ttsc()],
+});
+```
+
+## Configuration
+
+By default, `@ttsc/unplugin` finds the nearest `tsconfig.json` from the file being transformed and reads its existing `compilerOptions.plugins`.
+
+If that is already the config you want, `ttsc()` is enough.
+
+### Project Selection
+
+Use `project` when the bundler should read a different config file:
+
+```ts
+import ttsc from "@ttsc/unplugin/vite";
+
+export default {
+  plugins: [
+    ttsc({
+      project: "tsconfig.bundle.json",
+    }),
+  ],
+};
+```
+
+The project path is resolved from `process.cwd()`.
+
+### Inline Compiler Options
+
+Use `compilerOptions` when the bundler needs a small override without another config file:
+
+```ts
+import ttsc from "@ttsc/unplugin/vite";
+
+export default {
+  plugins: [
+    ttsc({
+      compilerOptions: {
+        plugins: [
+          {
+            transform: "@ttsc/lint",
+            config: { "no-var": "error" },
+          },
+          { transform: "typia/lib/transform" },
+        ],
+      },
+    }),
+  ],
+};
+```
+
+`compilerOptions` is layered on top of the selected project config. Existing settings stay in place, and only the fields you pass here are changed for the bundler build.
+
+### Plugin Overrides
+
+Use the top-level `plugins` option inside `ttsc(...)` when the bundler should ignore the plugin list from `tsconfig.json`:
+
+```ts
+import ttsc from "@ttsc/unplugin/vite";
+
+export default {
+  plugins: [
+    ttsc({
+      plugins: [
+        { transform: "@ttsc/lint", config: { "no-var": "error" } },
+        { transform: "typia/lib/transform" },
+      ],
+    }),
+  ],
+};
+```
+
+Plugin resolution order:
+
+1. `plugins` option.
+2. `compilerOptions.plugins` option.
+3. `compilerOptions.plugins` from `project` / discovered `tsconfig.json`.
+
+Set `plugins: false` to run the adapter without loading project plugins.
+
+### Next.js Options
+
+Pass adapter options as the second argument:
+
+```js
+// next.config.mjs
+import withTtsc from "@ttsc/unplugin/next";
+
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+export default withTtsc(nextConfig, {
+  project: "tsconfig.bundle.json",
+});
+```
+
+### Adapter Entrypoints
+
+Import the entrypoint that matches your bundler:
+
+```ts
+import ttsc from "@ttsc/unplugin/vite";
+```
+
+Supported entrypoints are:
+
+- `@ttsc/unplugin/vite`
+- `@ttsc/unplugin/esbuild`
+- `@ttsc/unplugin/rollup`
+- `@ttsc/unplugin/rolldown`
+- `@ttsc/unplugin/webpack`
+- `@ttsc/unplugin/rspack`
+- `@ttsc/unplugin/farm`
+- `@ttsc/unplugin/next`
+- `@ttsc/unplugin/bun`
+
+### Options
+
+```ts
+import type { TtscUnpluginOptions } from "@ttsc/unplugin";
+
+const options: TtscUnpluginOptions = {
+  project: "tsconfig.json",
+  compilerOptions: {
+    baseUrl: ".",
+  },
+  plugins: false,
+};
+```
+
+- `project`: path to the `tsconfig.json` used by the bundler.
+- `compilerOptions`: temporary override layered on the selected project config.
+- `plugins`: direct `ttsc` plugin list override, or `false` to disable plugins.
+
+## References
+
+Inspired by [`@ryoppippi/unplugin-typia`](https://github.com/ryoppippi/unplugin-typia).

package/lib/api.d.ts

@@ -0,0 +1 @@
+export * from "./core/index";

package/lib/api.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core/index"), exports);
+//# sourceMappingURL=api.js.map

package/lib/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B"}

package/lib/bun.d.ts

@@ -0,0 +1,15 @@
+import type { TtscUnpluginOptions } from "./core/options";
+export interface BunLikePlugin {
+    name: string;
+    setup(build: BunLikeBuild): void | Promise<void>;
+}
+export interface BunLikeBuild {
+    onLoad(options: {
+        filter: RegExp;
+    }, loader: (args: {
+        path: string;
+    }) => Promise<{
+        contents: string;
+    }>): void;
+}
+export default function bun(options?: TtscUnpluginOptions): BunLikePlugin;

package/lib/bun.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = bun;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const api_1 = require("./api");
+const sourceFilePattern = /\.[cm]?[jt]sx?$/;
+function bun(options) {
+    return {
+        name: "ttsc-unplugin",
+        setup(build) {
+            const raw = api_1.unplugin.raw(options, {});
+            build.onLoad({ filter: sourceFilePattern }, async (args) => {
+                const source = await promises_1.default.readFile(args.path, "utf8");
+                const result = typeof raw.transform === "function"
+                    ? await raw.transform.call({}, source, args.path)
+                    : undefined;
+                if (typeof result === "string") {
+                    return { contents: result };
+                }
+                if (typeof result === "object" &&
+                    result !== null &&
+                    "code" in result &&
+                    typeof result.code === "string") {
+                    return { contents: result.code };
+                }
+                return { contents: source };
+            });
+        },
+    };
+}
+//# sourceMappingURL=bun.js.map

package/lib/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.js","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":";;;;;;AAAA,gEAAkC;AAGlC,+BAAiC;AAejC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAE5C,aAA4B,OAA6B;IACvD,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,GAAG,cAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,EAAyB,CAAC,CAAC;YAC7D,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACzD,MAAM,MAAM,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACpD,MAAM,MAAM,GACV,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;oBACjC,CAAC,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAW,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC;oBAC1D,CAAC,CAAC,SAAS,CAAC;gBAChB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAC9B,CAAC;gBACD,IACE,OAAO,MAAM,KAAK,QAAQ;oBAC1B,MAAM,KAAK,IAAI;oBACf,MAAM,IAAI,MAAM;oBAChB,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAC/B,CAAC;oBACD,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;gBACnC,CAAC;gBACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YAC9B,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/core/index.d.ts

@@ -0,0 +1,8 @@
+import type { UnpluginInstance } from "unplugin";
+import type { TtscUnpluginOptions } from "./options";
+import { resolveOptions } from "./options";
+import { transformTtsc } from "./transform";
+declare const unplugin: UnpluginInstance<TtscUnpluginOptions | undefined, false>;
+export type { TtscUnpluginCompilerOptionsJson, TtscUnpluginOptions, } from "./options";
+export { resolveOptions, transformTtsc, unplugin };
+export default unplugin;

package/lib/core/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unplugin = exports.transformTtsc = exports.resolveOptions = void 0;
+const unplugin_1 = require("unplugin");
+const options_1 = require("./options");
+Object.defineProperty(exports, "resolveOptions", { enumerable: true, get: function () { return options_1.resolveOptions; } });
+const transform_1 = require("./transform");
+Object.defineProperty(exports, "transformTtsc", { enumerable: true, get: function () { return transform_1.transformTtsc; } });
+const name = "ttsc-unplugin";
+const sourceFilePattern = /\.[cm]?[jt]sx?$/;
+const nodeModulesPattern = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
+const unpluginFactory = (rawOptions = {}) => {
+    const options = (0, options_1.resolveOptions)(rawOptions);
+    let aliases;
+    return {
+        name,
+        enforce: "pre",
+        vite: {
+            configResolved(config) {
+                aliases = config.resolve.alias;
+            },
+        },
+        transformInclude(id) {
+            const file = (0, transform_1.stripQuery)(id);
+            return isTransformTarget(file);
+        },
+        async transform(source, id) {
+            const file = (0, transform_1.stripQuery)(id);
+            if (!isTransformTarget(file)) {
+                return undefined;
+            }
+            return (0, transform_1.transformTtsc)(file, source, options, aliases);
+        },
+    };
+};
+const unplugin = (0, unplugin_1.createUnplugin)(unpluginFactory);
+exports.unplugin = unplugin;
+exports.default = unplugin;
+function isTransformTarget(id) {
+    return (sourceFilePattern.test(id) &&
+        !(0, transform_1.isDeclarationFile)(id) &&
+        !nodeModulesPattern.test(id));
+}
+//# sourceMappingURL=index.js.map

package/lib/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";;;AACA,uCAA0C;AAG1C,uCAA2C;+FAAlC,wBAAc;AACvB,2CAA2E;8FAAnC,yBAAa;AAErD,MAAM,IAAI,GAAG,eAAe,CAAC;AAC7B,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAC5C,MAAM,kBAAkB,GAAG,oCAAoC,CAAC;AAEhE,MAAM,eAAe,GAGjB,CAAC,UAAU,GAAG,EAAE,EAAE,EAAE;IACtB,MAAM,OAAO,GAAG,IAAA,wBAAc,EAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,OAAgB,CAAC;IAErB,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,KAAK;QAEd,IAAI,EAAE;YACJ,cAAc,CAAC,MAAM;gBACnB,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YACjC,CAAC;SACF;QAED,gBAAgB,CAAC,EAAE;YACjB,MAAM,IAAI,GAAG,IAAA,sBAAU,EAAC,EAAE,CAAC,CAAC;YAC5B,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE;YACxB,MAAM,IAAI,GAAG,IAAA,sBAAU,EAAC,EAAE,CAAC,CAAC;YAC5B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,IAAA,yBAAa,EAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,QAAQ,GACZ,IAAA,yBAAc,EAAC,eAAe,CAAC,CAAC;QAMM,QAAQ;kBAEjC,QAAQ;AAEvB,SAAS,iBAAiB,CAAC,EAAU;IACnC,OAAO,CACL,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,CAAC,IAAA,6BAAiB,EAAC,EAAE,CAAC;QACtB,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAC7B,CAAC;AACJ,CAAC"}

package/lib/core/options.d.ts

@@ -0,0 +1,32 @@
+import type { ITtscProjectPluginConfig } from "ttsc";
+export type TtscUnpluginCompilerOptionsJson = Record<string, unknown>;
+export interface TtscUnpluginOptions {
+    /**
+     * Project config used by the bundler adapter.
+     *
+     * Relative paths resolve from `process.cwd()`. When omitted, the nearest
+     * `tsconfig.json` is discovered from the transformed file.
+     */
+    project?: string;
+    /**
+     * Compiler options overlaid on top of the selected project config.
+     *
+     * This can include `plugins`; `plugins` passed at the top level still wins as
+     * the explicit plugin override.
+     */
+    compilerOptions?: TtscUnpluginCompilerOptionsJson;
+    /**
+     * `ttsc` plugin entries.
+     *
+     * `undefined` reads `compilerOptions.plugins` from the project config,
+     * `false` disables project plugins, and an array overrides the project
+     * plugin list.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+}
+export interface ResolvedTtscUnpluginOptions {
+    compilerOptions: TtscUnpluginCompilerOptionsJson;
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+    project?: string;
+}
+export declare function resolveOptions(options?: TtscUnpluginOptions): ResolvedTtscUnpluginOptions;

package/lib/core/options.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOptions = resolveOptions;
+const defaultOptions = {
+    compilerOptions: {},
+    plugins: undefined,
+    project: undefined,
+};
+function resolveOptions(options = {}) {
+    return {
+        compilerOptions: { ...(options.compilerOptions ?? {}) },
+        plugins: "plugins" in options ? options.plugins : defaultOptions.plugins,
+        project: options.project ?? defaultOptions.project,
+    };
+}
+//# sourceMappingURL=options.js.map

package/lib/core/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/core/options.ts"],"names":[],"mappings":";;;AAqCA,MAAM,cAAc,GAAgC;IAClD,eAAe,EAAE,EAAE;IACnB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,wBACE,OAAO,GAAwB,EAAE;IAEjC,OAAO;QACL,eAAe,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE;QACvD,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO;QACxE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,OAAO;KACnD,CAAC;AACJ,CAAC"}

package/lib/core/transform.d.ts

@@ -0,0 +1,11 @@
+import type { TransformResult } from "unplugin";
+import type { ResolvedTtscUnpluginOptions } from "./options";
+export type TtscTransformResult = Exclude<TransformResult, string | null | undefined>;
+export interface TtscTransformAlias {
+    find: string | RegExp;
+    replacement: string;
+}
+export declare function transformTtsc(id: string, source: string, options: ResolvedTtscUnpluginOptions, aliases?: unknown): Promise<TtscTransformResult | undefined>;
+export declare function stripQuery(id: string): string;
+export declare function isDeclarationFile(id: string): boolean;
+export declare function createTransformResult(source: string, code: string, id: string): TtscTransformResult | undefined;