@ttsc/unplugin 0.28.1 → 0.28.2

package/lib/api.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Public API surface for `@ttsc/unplugin`.
+ *
+ * Re-exports everything from `core/index` so consumers can access the unified
+ * `unplugin` instance, the transform helpers, and the option types from the
+ * `@ttsc/unplugin/api` entry point without importing directly from `core/`.
+ */
+export * from "./core/index.cjs";

package/lib/api.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Public API surface for `@ttsc/unplugin`.
+ *
+ * Re-exports everything from `core/index` so consumers can access the unified
+ * `unplugin` instance, the transform helpers, and the option types from the
+ * `@ttsc/unplugin/api` entry point without importing directly from `core/`.
+ */
+export * from "./core/index.mjs";

package/lib/bun-register.d.cts

@@ -0,0 +1,25 @@
+import type { TtscUnpluginOptions } from "./core/options.cjs";
+/**
+ * Register the ttsc transform as a Bun **runtime** plugin.
+ *
+ * The other `@ttsc/unplugin/*` adapters cover bundlers (`Bun.build`, Vite,
+ * Webpack, …). This entry is the runtime counterpart: loading it registers the
+ * same transform on Bun's module loader, so `bun run` / `bun test` apply ttsc
+ * plugins (e.g. typia's `typia/lib/transform`) as files are imported, with no
+ * bundling step. Wire it up once via a `bunfig.toml` preload entry — `preload =
+ * ["@ttsc/unplugin/bun-register"]` — or imperatively with `import
+ * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
+ * `tsconfig.json`, identical to the bundler adapters.
+ *
+ * Registration is idempotent: the first call (implicit on import, or explicit)
+ * registers the one loader with Bun; later calls only update the effective
+ * options, so accessing the explicit API cannot install a second default loader
+ * that shadows the caller's configuration. Repeated explicit calls are
+ * last-write-wins for the effective options.
+ *
+ * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
+ *   is unavailable). The auto-registration below stays silent off Bun so the
+ *   module is harmless to import from Node (tests, tooling).
+ */
+export declare function register(options?: TtscUnpluginOptions): void;
+export default register;

package/lib/bun-register.d.mts

@@ -0,0 +1,25 @@
+import type { TtscUnpluginOptions } from "./core/options.mjs";
+/**
+ * Register the ttsc transform as a Bun **runtime** plugin.
+ *
+ * The other `@ttsc/unplugin/*` adapters cover bundlers (`Bun.build`, Vite,
+ * Webpack, …). This entry is the runtime counterpart: loading it registers the
+ * same transform on Bun's module loader, so `bun run` / `bun test` apply ttsc
+ * plugins (e.g. typia's `typia/lib/transform`) as files are imported, with no
+ * bundling step. Wire it up once via a `bunfig.toml` preload entry — `preload =
+ * ["@ttsc/unplugin/bun-register"]` — or imperatively with `import
+ * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
+ * `tsconfig.json`, identical to the bundler adapters.
+ *
+ * Registration is idempotent: the first call (implicit on import, or explicit)
+ * registers the one loader with Bun; later calls only update the effective
+ * options, so accessing the explicit API cannot install a second default loader
+ * that shadows the caller's configuration. Repeated explicit calls are
+ * last-write-wins for the effective options.
+ *
+ * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
+ *   is unavailable). The auto-registration below stays silent off Bun so the
+ *   module is harmless to import from Node (tests, tooling).
+ */
+export declare function register(options?: TtscUnpluginOptions): void;
+export default register;

package/lib/bun.d.cts

@@ -0,0 +1,95 @@
+import type { TtscUnpluginOptions } from "./core/options.cjs";
+/**
+ * Minimal subset of the Bun plugin API consumed by this adapter.
+ *
+ * Bun does not yet ship TypeScript types for its bundler plugin interface, so
+ * we define the subset we need here. This keeps the adapter free of a Bun
+ * runtime dependency while remaining type-safe.
+ */
+export interface BunLikePlugin {
+    /** Plugin identifier shown in Bun bundler output. */
+    name: string;
+    /** Called by Bun when the plugin is registered. */
+    setup(build: BunLikeBuild): void | Promise<void>;
+}
+/** Bun loader identifiers this adapter can emit (only TypeScript is matched). */
+export type BunLoader = "ts" | "tsx";
+/**
+ * Options accepted by {@link bun}, either resolved eagerly or supplied through a
+ * provider evaluated lazily on the first `onLoad` call.
+ *
+ * The provider form exists for the runtime registration path (`bun-register`),
+ * where a single Bun plugin is registered on import but its effective options
+ * may be overridden by an explicit `register(options)` call made in the same
+ * synchronous tick. Resolving through the provider on first load, rather than
+ * at registration, lets that later call win without Bun ever seeing a second
+ * shadowing loader.
+ */
+export type TtscBunOptions = TtscUnpluginOptions | (() => TtscUnpluginOptions | undefined);
+/**
+ * Minimal subset of the Bun `BuildConfig` plugin build object.
+ *
+ * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`,
+ * which is used when available to forward the shared plugin's build lifecycle
+ * and clear its per-build cache. The runtime plugin API omits that hook, so
+ * plugin setup itself starts its one process-scoped module-loading session.
+ */
+export interface BunLikeBuild {
+    /**
+     * Build configuration exposed unchanged by Bun's bundler plugin builder.
+     *
+     * Runtime plugin builders do not supply `files`. Bun's bundler accepts an
+     * in-memory file map whose values deliberately remain `unknown` here because
+     * this adapter only needs to preserve ownership, not consume their contents.
+     */
+    config?: {
+        files?: Readonly<Record<string, unknown>>;
+    };
+    /**
+     * Register a callback for the start of a bundler build.
+     *
+     * Optional because `Bun.plugin()` runtime builders do not expose this hook.
+     */
+    onStart?(callback: () => void | Promise<void>): void;
+    /**
+     * Register a loader callback for files matching `filter`.
+     *
+     * The callback receives the file path and must return the transformed file
+     * contents plus the `loader` Bun should apply next. Configured in-memory
+     * files retain relative key spellings; ordinary disk files are normally
+     * absolute. The `loader` matters most for the runtime path (`Bun.plugin`),
+     * where Bun must be told the returned contents are still TypeScript so it
+     * keeps transpiling them before execution.
+     */
+    onLoad(options: {
+        filter: RegExp;
+    }, loader: (args: {
+        path: string;
+    }) => Promise<{
+        contents: string;
+        loader: BunLoader;
+    } | undefined>): void;
+}
+/**
+ * Create a ttsc plugin for Bun's bundler AND runtime.
+ *
+ * Bun does not implement the unplugin protocol, so this adapter wires the
+ * shared ttsc transform core to Bun's `onLoad` hook directly. It reads each
+ * included file from disk and forwards the content to the transform. Under
+ * `Bun.build`, excluded files and no-op transforms return `undefined` so the
+ * next loader retains ownership. Entries supplied through `BuildConfig.files`
+ * also stay with Bun's in-memory loader: they are not filesystem project inputs
+ * and reading the same path from disk would either fail or silently replace the
+ * configured contents. The runtime `Bun.plugin()` API rejects an undefined
+ * `onLoad` result, so that path explicitly returns the original source and
+ * loader instead.
+ *
+ * The same object works for `Bun.build({ plugins: [ttsc()] })` (bundler) and
+ * for `Bun.plugin(ttsc())` / a `bunfig.toml` preload (runtime) — see
+ * `bun-register`. Every result carries an explicit `loader` so Bun keeps
+ * transpiling the emitted TypeScript at runtime; `bunSourceFilePattern` only
+ * matches TypeScript, so the loader is always `ts`/`tsx`. A runtime plugin
+ * instance is one immutable load session, like Bun's own module cache; restart
+ * the process after changing compiler inputs.
+ */
+export default function bun(options?: TtscBunOptions): BunLikePlugin;

package/lib/bun.d.mts

@@ -0,0 +1,95 @@
+import type { TtscUnpluginOptions } from "./core/options.mjs";
+/**
+ * Minimal subset of the Bun plugin API consumed by this adapter.
+ *
+ * Bun does not yet ship TypeScript types for its bundler plugin interface, so
+ * we define the subset we need here. This keeps the adapter free of a Bun
+ * runtime dependency while remaining type-safe.
+ */
+export interface BunLikePlugin {
+    /** Plugin identifier shown in Bun bundler output. */
+    name: string;
+    /** Called by Bun when the plugin is registered. */
+    setup(build: BunLikeBuild): void | Promise<void>;
+}
+/** Bun loader identifiers this adapter can emit (only TypeScript is matched). */
+export type BunLoader = "ts" | "tsx";
+/**
+ * Options accepted by {@link bun}, either resolved eagerly or supplied through a
+ * provider evaluated lazily on the first `onLoad` call.
+ *
+ * The provider form exists for the runtime registration path (`bun-register`),
+ * where a single Bun plugin is registered on import but its effective options
+ * may be overridden by an explicit `register(options)` call made in the same
+ * synchronous tick. Resolving through the provider on first load, rather than
+ * at registration, lets that later call win without Bun ever seeing a second
+ * shadowing loader.
+ */
+export type TtscBunOptions = TtscUnpluginOptions | (() => TtscUnpluginOptions | undefined);
+/**
+ * Minimal subset of the Bun `BuildConfig` plugin build object.
+ *
+ * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`,
+ * which is used when available to forward the shared plugin's build lifecycle
+ * and clear its per-build cache. The runtime plugin API omits that hook, so
+ * plugin setup itself starts its one process-scoped module-loading session.
+ */
+export interface BunLikeBuild {
+    /**
+     * Build configuration exposed unchanged by Bun's bundler plugin builder.
+     *
+     * Runtime plugin builders do not supply `files`. Bun's bundler accepts an
+     * in-memory file map whose values deliberately remain `unknown` here because
+     * this adapter only needs to preserve ownership, not consume their contents.
+     */
+    config?: {
+        files?: Readonly<Record<string, unknown>>;
+    };
+    /**
+     * Register a callback for the start of a bundler build.
+     *
+     * Optional because `Bun.plugin()` runtime builders do not expose this hook.
+     */
+    onStart?(callback: () => void | Promise<void>): void;
+    /**
+     * Register a loader callback for files matching `filter`.
+     *
+     * The callback receives the file path and must return the transformed file
+     * contents plus the `loader` Bun should apply next. Configured in-memory
+     * files retain relative key spellings; ordinary disk files are normally
+     * absolute. The `loader` matters most for the runtime path (`Bun.plugin`),
+     * where Bun must be told the returned contents are still TypeScript so it
+     * keeps transpiling them before execution.
+     */
+    onLoad(options: {
+        filter: RegExp;
+    }, loader: (args: {
+        path: string;
+    }) => Promise<{
+        contents: string;
+        loader: BunLoader;
+    } | undefined>): void;
+}
+/**
+ * Create a ttsc plugin for Bun's bundler AND runtime.
+ *
+ * Bun does not implement the unplugin protocol, so this adapter wires the
+ * shared ttsc transform core to Bun's `onLoad` hook directly. It reads each
+ * included file from disk and forwards the content to the transform. Under
+ * `Bun.build`, excluded files and no-op transforms return `undefined` so the
+ * next loader retains ownership. Entries supplied through `BuildConfig.files`
+ * also stay with Bun's in-memory loader: they are not filesystem project inputs
+ * and reading the same path from disk would either fail or silently replace the
+ * configured contents. The runtime `Bun.plugin()` API rejects an undefined
+ * `onLoad` result, so that path explicitly returns the original source and
+ * loader instead.
+ *
+ * The same object works for `Bun.build({ plugins: [ttsc()] })` (bundler) and
+ * for `Bun.plugin(ttsc())` / a `bunfig.toml` preload (runtime) — see
+ * `bun-register`. Every result carries an explicit `loader` so Bun keeps
+ * transpiling the emitted TypeScript at runtime; `bunSourceFilePattern` only
+ * matches TypeScript, so the loader is always `ts`/`tsx`. A runtime plugin
+ * instance is one immutable load session, like Bun's own module cache; restart
+ * the process after changing compiler inputs.
+ */
+export default function bun(options?: TtscBunOptions): BunLikePlugin;

package/lib/core/index.d.cts

@@ -0,0 +1,23 @@
+import type { UnpluginInstance } from "unplugin";
+import type { TtscUnpluginOptions } from "./options.cjs";
+import { resolveOptions } from "./options.cjs";
+import { beginTtscTransformBuild, collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resetTtscTransformCache, transformTtsc } from "./transform.cjs";
+/**
+ * Matches any TypeScript or JavaScript source extension (.ts, .tsx, .mts, .cts,
+ * etc.). Shared with the Bun adapter (`bun.ts`) so the filter is defined once
+ * and both adapters stay in sync.
+ */
+export declare const sourceFilePattern: RegExp;
+declare const unplugin: UnpluginInstance<TtscUnpluginOptions | undefined, false>;
+export type { TtscUnpluginCompilerOptionsJson, TtscUnpluginOptions, } from "./options.cjs";
+export type { TtscTransformFilesystemOperations, TtscTransformHooks, TtscWatchInputEvidence, } from "./transform.cjs";
+export { beginTtscTransformBuild, collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resetTtscTransformCache, resolveOptions, transformTtsc, unplugin, };
+export default unplugin;
+/**
+ * Returns `true` when the module id refers to a real TypeScript/JavaScript
+ * source file that should be processed by the ttsc transform.
+ *
+ * Excluded ids: virtual modules (NUL prefix), `.d.ts` declaration files, and
+ * anything inside `node_modules`.
+ */
+export declare function isTransformTarget(id: string): boolean;

package/lib/core/index.d.mts

@@ -0,0 +1,23 @@
+import type { UnpluginInstance } from "unplugin";
+import type { TtscUnpluginOptions } from "./options.mjs";
+import { resolveOptions } from "./options.mjs";
+import { beginTtscTransformBuild, collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resetTtscTransformCache, transformTtsc } from "./transform.mjs";
+/**
+ * Matches any TypeScript or JavaScript source extension (.ts, .tsx, .mts, .cts,
+ * etc.). Shared with the Bun adapter (`bun.ts`) so the filter is defined once
+ * and both adapters stay in sync.
+ */
+export declare const sourceFilePattern: RegExp;
+declare const unplugin: UnpluginInstance<TtscUnpluginOptions | undefined, false>;
+export type { TtscUnpluginCompilerOptionsJson, TtscUnpluginOptions, } from "./options.mjs";
+export type { TtscTransformFilesystemOperations, TtscTransformHooks, TtscWatchInputEvidence, } from "./transform.mjs";
+export { beginTtscTransformBuild, collectExternalInputHashes, collectProjectInputHashes, createTtscTransformCache, isProjectWalkPath, resetTtscTransformCache, resolveOptions, transformTtsc, unplugin, };
+export default unplugin;
+/**
+ * Returns `true` when the module id refers to a real TypeScript/JavaScript
+ * source file that should be processed by the ttsc transform.
+ *
+ * Excluded ids: virtual modules (NUL prefix), `.d.ts` declaration files, and
+ * anything inside `node_modules`.
+ */
+export declare function isTransformTarget(id: string): boolean;

package/lib/core/options.d.cts

@@ -0,0 +1,54 @@
+import type { ITtscProjectPluginConfig } from "ttsc";
+/** Raw compiler-options overlay supplied by the caller as a plain JSON value. */
+export type TtscUnpluginCompilerOptionsJson = Record<string, unknown>;
+/** Options accepted by the `@ttsc/unplugin` bundler adapter. */
+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 project plugins from `compilerOptions.plugins` and
+     * directly installed package markers, `false` disables project plugins, and
+     * an array overrides the project plugin list.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+}
+/**
+ * Fully-resolved plugin options with all defaults applied.
+ *
+ * Produced by {@link resolveOptions}; consumed internally by the transform
+ * pipeline. Every field is present and normalised; callers should not construct
+ * this type directly.
+ */
+export interface ResolvedTtscUnpluginOptions {
+    /** Compiler-options overlay applied on top of the discovered tsconfig. */
+    compilerOptions: TtscUnpluginCompilerOptionsJson;
+    /**
+     * Resolved plugin list; mirrors the semantics of
+     * {@link TtscUnpluginOptions.plugins}.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+    /** Resolved path to the project tsconfig, or `undefined` to auto-discover. */
+    project?: string;
+}
+/**
+ * Normalise raw user-supplied options into {@link ResolvedTtscUnpluginOptions}.
+ *
+ * Merges provided values with defaults. The `plugins` field uses an explicit
+ * `"plugins" in options` presence check rather than a falsy guard so that
+ * `plugins: false` (disable all plugins) is preserved as-is.
+ */
+export declare function resolveOptions(options?: TtscUnpluginOptions): ResolvedTtscUnpluginOptions;

package/lib/core/options.d.mts

@@ -0,0 +1,54 @@
+import type { ITtscProjectPluginConfig } from "ttsc";
+/** Raw compiler-options overlay supplied by the caller as a plain JSON value. */
+export type TtscUnpluginCompilerOptionsJson = Record<string, unknown>;
+/** Options accepted by the `@ttsc/unplugin` bundler adapter. */
+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 project plugins from `compilerOptions.plugins` and
+     * directly installed package markers, `false` disables project plugins, and
+     * an array overrides the project plugin list.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+}
+/**
+ * Fully-resolved plugin options with all defaults applied.
+ *
+ * Produced by {@link resolveOptions}; consumed internally by the transform
+ * pipeline. Every field is present and normalised; callers should not construct
+ * this type directly.
+ */
+export interface ResolvedTtscUnpluginOptions {
+    /** Compiler-options overlay applied on top of the discovered tsconfig. */
+    compilerOptions: TtscUnpluginCompilerOptionsJson;
+    /**
+     * Resolved plugin list; mirrors the semantics of
+     * {@link TtscUnpluginOptions.plugins}.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+    /** Resolved path to the project tsconfig, or `undefined` to auto-discover. */
+    project?: string;
+}
+/**
+ * Normalise raw user-supplied options into {@link ResolvedTtscUnpluginOptions}.
+ *
+ * Merges provided values with defaults. The `plugins` field uses an explicit
+ * `"plugins" in options` presence check rather than a falsy guard so that
+ * `plugins: false` (disable all plugins) is preserved as-is.
+ */
+export declare function resolveOptions(options?: TtscUnpluginOptions): ResolvedTtscUnpluginOptions;