@effected/tsconfig-json 0.3.3 → 0.4.0

package/PortableTsconfig.js

@@ -86,6 +86,7 @@ const PRESERVED_OPTIONS = [
 	...PRESERVED_ENUM_OPTIONS,
 	...PRESERVED_STRING_OPTIONS
 ];
+const OPT_IN_TYPES_OPTION = "types";
 /**
 * A `ResolvedTsconfig` carries a string `configPath`, an array `extendedPaths`
 * AND an object `compilerOptions`; a bare `CompilerOptions.Type` never carries
@@ -101,13 +102,17 @@ const PRESERVED_OPTIONS = [
 * is filtered, which is the safe outcome.)
 */
 const isResolvedTsconfig = (input) => typeof input.configPath === "string" && Array.isArray(input.extendedPaths) && typeof input.compilerOptions === "object" && input.compilerOptions !== null;
-const make = (input) => {
+const make = (input, options) => {
 	const source = isResolvedTsconfig(input) ? input.compilerOptions : input;
 	const compilerOptions = {};
 	for (const key of PRESERVED_OPTIONS) {
 		const value = source[key];
 		if (value !== void 0) compilerOptions[key] = value;
 	}
+	if (options?.includeTypes === true) {
+		const types = source[OPT_IN_TYPES_OPTION];
+		if (types !== void 0) compilerOptions[OPT_IN_TYPES_OPTION] = types;
+	}
 	compilerOptions.composite = false;
 	compilerOptions.noEmit = true;
 	return {
@@ -134,6 +139,19 @@ var PortableTsconfig = class {
 	* is dropped; this is an allow-list, not a deny-list, so an option this
 	* package does not yet classify never leaks onto the portable shape by
 	* accident.
+	*
+	* `types` is the one deliberate exception, and it is opt-in rather than
+	* unclassified: it is portable (package names, not paths) but carrying it
+	* makes TypeScript demand those packages be resolvable, which a virtual
+	* environment with no `node_modules` cannot satisfy. Pass
+	* {@link PortableTsconfigOptions.includeTypes} when the consumer
+	* materializes `@types`; leave it off for the permissive default. Related
+	* `typeRoots` is never carried — machine-specific,
+	* config-location-dependent directories.
+	*
+	* @param input - The resolved config, or a bare compiler-options bag.
+	* @param options - Opt-ins for options that are portable but
+	* resolution-dependent. Omitted means the strict, always-safe subset.
 	*/
 	static make = make;
 };

package/README.md

@@ -82,8 +82,13 @@ console.log(TsEnumCodec.encodeCompilerOptions({ target: "es2023", strict: true,
 
 console.log(PortableTsconfig.make(resolved).compilerOptions.noEmit);
 // true — always forced, whatever the source config declared
+
+console.log(PortableTsconfig.make(resolved, { includeTypes: true }).compilerOptions.types);
+// carries the source config's `types` package names when it declares them, omitted when absent
 ```
 
+`includeTypes` is opt-in and defaults to `false` because emitting `types` makes tsc demand those `@types` packages resolve — a hard error in a virtual environment with no `node_modules`. Pass it when your environment materializes `@types` itself; leave it off for the permissive default where TypeScript auto-includes whatever it finds.
+
 ## Synchronous loading
 
 Bundler plugin hooks and config factories often cannot await. `TsconfigLoaderSync` runs the unchanged loader pipeline synchronously over file and path operations you supply — the package still imports no `node:*` module, and Node's built-ins satisfy the operations directly:
@@ -154,7 +159,7 @@ console.log(fsMap.size);
 - `ResolvedTsconfig` — the pure merge engine behind `resolve`: per-field merge semantics, path-option absolutization against the declaring config's directory, final `${configDir}` substitution and `pathsBase` provenance, with no filesystem access at all.
 - `TsconfigDiscovery.findNearest` — the nearest `tsconfig.json` (or any filename via `options.filename`) at or above a starting directory, over `@effected/walker`; one unreadable ancestor cannot hide a config above it.
 - `TsEnumCodec` — the string↔numeric enum tables as plain data with zero `typescript` imports. `encodeCompilerOptions` returns the exported `ProgrammaticCompilerOptions` type — the numeric shape `ts.CompilerOptions` expects, so you hand it to a `ts.CompilerOptions`-shaped API without a cast — with `lib` entries in the file-name form the compiler resolves verbatim; `decodeCompilerOptions` reverses it.
-- `PortableTsconfig.make` — an allow-list projection down to machine-independent type-semantics options, with `composite: false` and `noEmit: true` forced: the slice a virtual TypeScript environment (Twoslash, API Extractor, an in-memory language service) can safely inherit.
+- `PortableTsconfig.make` — an allow-list projection down to machine-independent type-semantics options, with `composite: false` and `noEmit: true` forced: the slice a virtual TypeScript environment (Twoslash, API Extractor, an in-memory language service) can safely inherit. An optional `{ includeTypes }` argument carries the source config's `types` package names onto the portable shape too, for a caller whose virtual environment can resolve `@types` packages itself; `typeRoots` stays dropped either way, since it names machine-specific, config-location-dependent directories.
 - `JsxConfig.fromCompilerOptions` — the JSX transform a bundler can configure, projected from decoded options: `react-jsx` / `react-jsxdev` select the automatic runtime with its import source (defaulting to `react`, tsc's own default), `react` selects classic, and `preserve`, `react-native` or an absent `jsx` yield `Option.none()`.
 - Typed failures everywhere: a malformed file is a `TsconfigParseError` carrying its path, a broken chain is a `TsconfigExtendsError` with a `not-found` / `cycle` / `depth` / `empty` reason and the full resolution chain, and IO errors flow through as `PlatformError`. Nothing fails as a defect.
 

package/index.d.ts

@@ -603,6 +603,28 @@ interface PortableTsconfig {
   /** The allow-listed, forced-flag-applied compiler options. */
   readonly compilerOptions: Record<string, unknown>;
 }
+/**
+ * Options for {@link (PortableTsconfig:class).make}.
+ *
+ * @public
+ */
+interface PortableTsconfigOptions {
+  /**
+   * Carry `types` (an array of `@types` package NAMES) onto the portable
+   * shape when the source declares it. Defaults to `false`.
+   *
+   * Opt in when the consuming environment can resolve those packages — it
+   * materializes `@types` into its virtual filesystem, or type-checks against
+   * a real `node_modules`. Leaving it off keeps the permissive default, where
+   * TypeScript auto-includes whatever `@types` the environment happens to
+   * have and never errors on a missing one.
+   *
+   * `typeRoots` is NOT carried under this flag: it names filesystem
+   * directories, which are machine-specific and config-location-dependent,
+   * so they are never portable.
+   */
+  readonly includeTypes?: boolean;
+}
 /**
  * The portable-tsconfig filter: {@link (PortableTsconfig:class).make}
  * narrows a resolved or bare compiler-options object to the allow-listed,
@@ -622,8 +644,21 @@ declare class PortableTsconfig {
    * is dropped; this is an allow-list, not a deny-list, so an option this
    * package does not yet classify never leaks onto the portable shape by
    * accident.
+   *
+   * `types` is the one deliberate exception, and it is opt-in rather than
+   * unclassified: it is portable (package names, not paths) but carrying it
+   * makes TypeScript demand those packages be resolvable, which a virtual
+   * environment with no `node_modules` cannot satisfy. Pass
+   * {@link PortableTsconfigOptions.includeTypes} when the consumer
+   * materializes `@types`; leave it off for the permissive default. Related
+   * `typeRoots` is never carried — machine-specific,
+   * config-location-dependent directories.
+   *
+   * @param input - The resolved config, or a bare compiler-options bag.
+   * @param options - Opt-ins for options that are portable but
+   * resolution-dependent. Omitted means the strict, always-safe subset.
    */
-  static readonly make: (input: ResolvedTsconfig | CompilerOptions.Type) => PortableTsconfig;
+  static readonly make: (input: ResolvedTsconfig | CompilerOptions.Type, options?: PortableTsconfigOptions) => PortableTsconfig;
 }
 //#endregion
 //#region src/TsconfigDiscovery.d.ts
@@ -1264,5 +1299,5 @@ declare class TsEnumCodec {
   static readonly decodeCompilerOptions: (numeric: Readonly<Record<string, unknown>>) => Record<string, unknown>;
 }
 //#endregion
-export { CompilerOptions, type EnumFamily, FallbackPolling, type FindNearestOptions, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, type ProgrammaticCompilerOptions, type ProgrammaticCompilerOptionsValue, Reference, ResolvedTsconfig, type SyncFileSystem, type SyncPath, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, type TsconfigLoaderSyncOptions, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };
+export { CompilerOptions, type EnumFamily, FallbackPolling, type FindNearestOptions, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, type PortableTsconfigOptions, type ProgrammaticCompilerOptions, type ProgrammaticCompilerOptionsValue, Reference, ResolvedTsconfig, type SyncFileSystem, type SyncPath, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, type TsconfigLoaderSyncOptions, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/tsconfig-json",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [